fix(styles): handle search icon in RTL

* docs(web): polish english component docs

* docs(web): polish custom style demos

* docs(web): polish chinese component docs

* docs(web): update release demos

* docs(web): polish tabs component docs

* docs(web): polish chinese component docs

* docs(web): polish chinese component docs

* docs(web): prevent href scroll jumps in card and link demos

* docs(web): sync status icons

* fix(docs): preserve locale in showcase and component doc links

* docs(web): align showcase terminology of chinese version

.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/calm-trees-serve.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-fix label placement in input and select

.changeset/config.json

@@ -1,20 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
-  "changelog": [
-    "@changesets/changelog-github",
-    { "repo": "nextui-org/nextui" }
-  ],
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
-    "onlyUpdatePeerDependentsWhenOutOfRange": true
-  },
-  "ignore": [
-    "@nextui-org/docs",
-    "@nextui-org/storybook"
-  ]
-}

.changeset/curly-zoos-thank.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/listbox": patch
----
-
-change ListboxItem key to optional (#3880)

.changeset/dirty-moles-refuse.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/autocomplete": patch
----
-
-Clicking the clear button clears the selected value without closing the dropdown. (#3788)

.changeset/dull-bags-divide.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/select": patch
----
-
-update label placement in Select to use `shouldLabelBeOutside` instead of `isOutsideLeft`, resolving multiline label placement issues (#3841).

.changeset/fast-horses-explode.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-fix the fullWidth variant in input and select component. (#3745)

.changeset/few-jars-flow.md

@@ -1,53 +0,0 @@
----
-"@nextui-org/table": minor
-"@nextui-org/accordion": minor
-"@nextui-org/autocomplete": minor
-"@nextui-org/avatar": minor
-"@nextui-org/breadcrumbs": minor
-"@nextui-org/button": minor
-"@nextui-org/calendar": minor
-"@nextui-org/card": minor
-"@nextui-org/checkbox": minor
-"@nextui-org/chip": minor
-"@nextui-org/date-input": minor
-"@nextui-org/date-picker": minor
-"@nextui-org/divider": minor
-"@nextui-org/dropdown": minor
-"@nextui-org/input": minor
-"@nextui-org/kbd": minor
-"@nextui-org/link": minor
-"@nextui-org/listbox": minor
-"@nextui-org/menu": minor
-"@nextui-org/modal": minor
-"@nextui-org/navbar": minor
-"@nextui-org/pagination": minor
-"@nextui-org/popover": minor
-"@nextui-org/progress": minor
-"@nextui-org/radio": minor
-"@nextui-org/select": minor
-"@nextui-org/slider": minor
-"@nextui-org/snippet": minor
-"@nextui-org/switch": minor
-"@nextui-org/tabs": minor
-"@nextui-org/tooltip": minor
-"@nextui-org/user": minor
-"@nextui-org/react": minor
-"@nextui-org/system": minor
-"@nextui-org/system-rsc": minor
-"@nextui-org/use-aria-accordion": minor
-"@nextui-org/use-aria-accordion-item": minor
-"@nextui-org/use-aria-button": minor
-"@nextui-org/use-aria-link": minor
-"@nextui-org/use-aria-menu": minor
-"@nextui-org/use-aria-modal-overlay": minor
-"@nextui-org/use-aria-multiselect": minor
-"@nextui-org/use-aria-overlay": minor
-"@nextui-org/use-aria-toggle-button": minor
-"@nextui-org/use-disclosure": minor
-"@nextui-org/use-intersection-observer": minor
-"@nextui-org/use-is-mobile": minor
-"@nextui-org/use-pagination": minor
-"@nextui-org/aria-utils": minor
----
-
-update react-aria version

.changeset/flat-pants-accept.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/date-picker": patch
----
-
-Fixes getCalendarProps to propagate the classNames in the calendarProps. (#3769)

.changeset/forty-doors-flash.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-remove the pseudo cancel btn from input (#3907)

.changeset/giant-worms-hammer.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-replace the use of RTL-specific styles with logical properties.

.changeset/grumpy-mayflies-rhyme.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-bump `tailwind-merge` version (#3614)

.changeset/kind-cobras-travel.md

@@ -1,6 +0,0 @@
----
-"@nextui-org/calendar": patch
-"@nextui-org/date-picker": patch
----
-
-Add month and year picker to DateRangePicker and RangeCalendar (#3089, #3090)

.changeset/light-needles-behave.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/use-theme": minor
----
-
-introduce `use-theme` hook

.changeset/mean-mangos-occur.md

@@ -1,8 +0,0 @@
----
-"@nextui-org/calendar": patch
-"@nextui-org/theme": patch
-"@nextui-org/use-infinite-scroll": patch
-"@nextui-org/shared-utils": patch
----
-
-replaced lodash with native approaches

.changeset/mighty-birds-deny.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/autocomplete": patch
----
-
-Return null if there are items for exit animation on popover close to work

.changeset/neat-donkeys-accept.md

@@ -1,6 +0,0 @@
----
-"@nextui-org/date-picker": minor
-"@nextui-org/theme": minor
----
-
-Add support for selectorButtonPlacement property (#3015)

.changeset/pink-beans-sit.md

@@ -1,6 +0,0 @@
----
-"@nextui-org/use-image": patch
-"@nextui-org/test-utils": patch
----
-
-fix cached image flashing due to use-image always returning pending initially. The fix was to check if the image is loaded instantly through HTMLImageElement.complete attribute and use that to initialize the state.

.changeset/poor-moose-double.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-added stripe color gradients for progress (#1933)

.changeset/poor-sheep-repair.md

@@ -1,6 +0,0 @@
----
-"@nextui-org/alert": patch
-"@nextui-org/theme": patch
----
-
-introduced Alert component (#2250)

.changeset/popular-pigs-begin.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/autocomplete": patch
----
-
-automatically focus first non-disabled item

.changeset/quick-geckos-punch.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-separator icon RTL support in Breadcrumbs component (#2486)

.changeset/shy-mails-live.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/image": patch
----
-
-add missing `w` to `getWrapperProps` dependency (#3801)

.changeset/slimy-cats-brush.md

@@ -1,4 +0,0 @@
----
----
-
-Update Twitter logo, links, and named references to X. Removed Twitter logo from social based on review feedback.

.changeset/slow-paws-punch.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/popover": minor
----
-
-added `shouldCloseOnScroll` to control the popover closing on scroll (#3594)

.changeset/smooth-mayflies-wonder.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/tabs": patch
----
-
-Add tab ref

.changeset/soft-apricots-sleep.md

@@ -1,6 +0,0 @@
----
-"@nextui-org/modal": patch
-"@nextui-org/use-draggable": patch
----
-
-Add draggable modal (#2647)

.changeset/sour-seas-buy.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/menu": patch
----
-
-Use `useMenu` and `useMenuItem` from `@react-aria` instead of custom hooks

.changeset/swift-news-complain.md

@@ -1,15 +0,0 @@
----
-"@nextui-org/accordion": patch
-"@nextui-org/calendar": patch
-"@nextui-org/modal": patch
-"@nextui-org/navbar": patch
-"@nextui-org/popover": patch
-"@nextui-org/ripple": patch
-"@nextui-org/tooltip": patch
-"@nextui-org/theme": patch
-"@nextui-org/use-infinite-scroll": patch
-"@nextui-org/dom-animation": patch
-"@nextui-org/shared-utils": patch
----
-
-framer motion optimization (#3340)

.changeset/thirty-cheetahs-guess.md

@@ -1,20 +0,0 @@
----
-"@nextui-org/accordion": patch
-"@nextui-org/autocomplete": patch
-"@nextui-org/button": patch
-"@nextui-org/calendar": patch
-"@nextui-org/card": patch
-"@nextui-org/dropdown": patch
-"@nextui-org/modal": patch
-"@nextui-org/navbar": patch
-"@nextui-org/popover": patch
-"@nextui-org/ripple": patch
-"@nextui-org/select": patch
-"@nextui-org/snippet": patch
-"@nextui-org/tabs": patch
-"@nextui-org/tooltip": patch
-"@nextui-org/system": patch
-"@nextui-org/framer-utils": patch
----
-
-update `framer-motion` versions

.changeset/tricky-fans-draw.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-show margin only with label in Switch component (#3791)

.changeset/twelve-papayas-clean.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/tabs": patch
----
-
-revise the inert attribute in `TabPanel` (#3972)

.changeset/two-waves-own.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/input": patch
----
-
-clear button should not receive focus when input is disabled.

.changeset/wild-jobs-explain.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/use-image": patch
----
-
-fix Image ReferenceError in SSR

.changeset/witty-socks-bathe.md

@@ -1,5 +0,0 @@
----
-"@nextui-org/theme": patch
----
-
-add missing `data-[hover=true]:` for ghost button with danger color

.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.

.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.**

.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.

.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.

.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`

.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.

.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");
+    }
+  }
+}

.coderabbit.yaml

@@ -1,22 +0,0 @@
-language: "en"
-early_access: false
-reviews:
-  high_level_summary: true
-  poem: false
-  review_status: true
-  collapse_walkthrough: false
-  auto_review:
-      enabled: true
-      ignore_title_keywords:
-        - "WIP"
-        - "DO NOT MERGE"
-        - 'ci(changesets)'
-      drafts: false
-      base_branches:
-        - "main"
-        - "canary"
-        - "fix/.*"
-        - "chore/.*"
-        - "feat/.*"
-chat:
-  auto_reply: true        

.commitlintrc.cjs

@@ -1,16 +0,0 @@
-const conventional = require("@commitlint/config-conventional");
-
-module.exports = {
-  extends: ["@commitlint/config-conventional"],
-  plugins: ["commitlint-plugin-function-rules"],
-  helpUrl: "https://github.com/nextui-org/nextui/blob/main/CONTRIBUTING.md#commit-convention",
-  rules: {
-    ...conventional.rules,
-    "type-enum": [
-      2,
-      "always",
-      ["feat", "feature", "fix", "refactor", "docs", "build", "test", "ci", "chore"],
-    ],
-    "function-rules/header-max-length": [0],
-  },
-};

.editorconfig

@@ -1,9 +1,15 @@
-root = true
+root=true
 
 [*]
-indent_size = 2
-max_line_length = 100
-insert_final_newline = true
-trim_trailing_whitespace = true
-charset = utf-8
-indent_style = space
+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

.env.example

@@ -1,7 +0,0 @@
-SKIP_PREFLIGHT_CHECK=true
-## Algolia client app id
-ALGOLIA_APP_ID=
-## Algolia client search only api key
-ALGOLIA_SEARCH_API_KEY=
-## Algolia admin api key
-ALGOLIA_ADMIN_API_KEY=

.eslintignore

@@ -1,25 +0,0 @@
-.now/*
-.next/*
-*.css
-.changeset
-dist
-esm/*
-public/*
-tests/*
-scripts/*
-*.config.js
-.DS_Store
-node_modules
-coverage
-.next
-build
-!.storybook
-/**/.storybook/**
-!.commitlintrc.cjs
-!.lintstagedrc.cjs
-!jest.config.js
-!plopfile.js
-!react-shim.js
-!tsup.config.ts
-apps/docs/preinstall.js
-apps/docs/next-redirect.js

.eslintrc.json

@@ -1,93 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/eslintrc.json",
-  "env": {
-    "browser": false,
-    "es2021": true,
-    "node": true
-  },
-  "extends": [
-    "plugin:react/recommended",
-    "plugin:prettier/recommended",
-    "plugin:react-hooks/recommended",
-    "plugin:jsx-a11y/recommended"
-  ],
-  "plugins": ["react", "unused-imports", "import", "@typescript-eslint", "jsx-a11y", "prettier"],
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "ecmaFeatures": {
-      "jsx": true
-    },
-    "ecmaVersion": 12,
-    "sourceType": "module"
-  },
-  "settings": {
-    "react": {
-      "version": "detect"
-    }
-  },
-  "rules": {
-    "no-console": "warn",
-    "react/prop-types": "off",
-    "react/jsx-uses-react": "off",
-    "react/react-in-jsx-scope": "off",
-    "react-hooks/exhaustive-deps": "off",
-    "jsx-a11y/click-events-have-key-events": "warn",
-    "jsx-a11y/interactive-supports-focus": "warn",
-    "prettier/prettier": "warn",
-    "no-unused-vars": "off",
-    "unused-imports/no-unused-vars": "off",
-    "unused-imports/no-unused-imports": "warn",
-    "@typescript-eslint/no-unused-vars": [
-      "warn",
-      {
-        "args": "after-used",
-        "ignoreRestSiblings": false,
-        "argsIgnorePattern": "^_.*?$"
-      }
-    ],
-    "import/order": [
-      "warn",
-      {
-        "groups": [
-          "type",
-          "builtin",
-          "object",
-          "external",
-          "internal",
-          "parent",
-          "sibling",
-          "index"
-        ],
-        "pathGroups": [
-          {
-            "pattern": "~/**",
-            "group": "external",
-            "position": "after"
-          }
-        ],
-        "newlines-between": "always"
-      }
-    ],
-    "react/self-closing-comp": "warn",
-    "react/jsx-sort-props": [
-      "warn",
-      {
-        "callbacksLast": true,
-        "shorthandFirst": true,
-        "noSortAlphabetically": false,
-        "reservedFirst": true
-      }
-    ],
-    "padding-line-between-statements": [
-      "warn",
-      {"blankLine": "always", "prev": "*", "next": "return"},
-      {"blankLine": "always", "prev": ["const", "let", "var"], "next": "*"},
-      {
-        "blankLine": "any",
-        "prev": ["const", "let", "var"],
-        "next": ["const", "let", "var"]
-      }
-    ],
-    "import/consistent-type-specifier-style": ["error", "prefer-top-level"]
-  }
-}

.github/FUNDING.yml

@@ -1,8 +1,8 @@
 # These are supported funding model platforms
 
 github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-patreon: jrgarciadev
-open_collective: nextui
+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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,4 +1,4 @@
-name: 'Bug report'
+name: "Bug report"
 title: "[BUG] - YOUR_ISSUE_TITLE_HERE_REPLACE_ME"
 description: Create a report to help us improve
 labels: [bug]
@@ -8,36 +8,40 @@ body:
       value: |
         Thank you for reporting an issue :pray:.
 
-        This issue tracker is for reporting bugs found in [NextUI github repository](https://github.com/nextui-org/nextui/)
+        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:
-          - NextUI's [Discussion's tab](https://github.com/nextui-org/nextui/discussions)
-          - NextUI's [Discord channel](https://discord.gg/9b6yyZKmH4)
+          - 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:
-         - NextUI's [Issue's tab](https://github.com/nextui-org/nextui/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
-         - NextUI's [closed issues tab](https://github.com/nextui-org/nextui/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed)
-         - NextUI's [Discussions tab](https://github.com/nextui-org/nextui/discussions)
+         - 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: NextUI Version
+      label: HeroUI Version
       description: |
-        Please provide the version of NextUI you are using.
-        You can find the version number in the package.json file.
-        For global installation, please state the version only. (e.g. 2.4.2)
-        For individual installation, please state the package name as well. (e.g. @nextui-org/button@2.0.34)
-      placeholder: ex. 2.4.2
+        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.
+      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
@@ -47,7 +51,7 @@ body:
       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 `@nextui-org/react` npm package.
+        - 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: |

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +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/nextui-org/nextui/discussions
+    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 `NextUI` community Discord server.
+    about: Ask quick questions or simply chat on the `HeroUI` community Discord server.
   - name: 💬 New Updates (X)
-    url: https://x.com/getnextui
-    about: Link to our X account if you want to follow us and stay up to date with NextUI news
+    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

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,49 +0,0 @@
-name: Feature request
-title: "[Feature Request] YOUR_FEATURE_TITLE_HERE_REPLACE_ME"
-labels: [feature request]
-description:  |
-  💡 Suggest an idea for the `NextUI` project
-  Examples
-    - propose a new component
-    - improve an exiting component
-    - ....etc
-body:
-  - type: markdown
-    attributes:
-      value: |
-        This issue form is for requesting features only! For example, requesting a new component, behavior ... etc
-        If you want to report a bug, please use the [bug report form](https://github.com/nextui-org/nextui/issues/new?assignees=&labels=&template=bug_report.yml).
-  - type: textarea
-    validations:
-      required: true
-    attributes:
-      label: Is your feature request related to a problem? Please describe.
-      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-  - type: textarea
-    validations:
-      required: true
-    attributes:
-      label: Describe the solution you'd like
-      description: A clear and concise description of what you want to happen.
-      placeholder: |
-        As a user, I expected ___ behavior but ___ ...
-        
-        Ideal Steps I would like to see:
-        1. Go to '...'
-        2. Click on '....'
-        3. ....
-  - type: textarea
-    validations:
-      required: true
-    attributes:
-      label: Describe alternatives you've considered
-      description: A clear and concise description of any alternative solutions or features you've considered.
-  - type: textarea
-    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 ↓

.github/common-actions/install/action.yml

@@ -4,22 +4,38 @@ description: "Sets up Node.js and runs install"
 runs:
   using: composite
   steps:
-    - name: Install dependencies
-      uses: pnpm/action-setup@v4
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
+    - 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"
-        cache: "pnpm"
+
+    - 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"
-
-    - name: Install dependencies
-      shell: bash
-      run: pnpm install

.github/pull_request_template.md

@@ -23,6 +23,6 @@ Closes # <!-- Github issue # here -->
 
 ## 💣 Is this a breaking change (Yes/No):
 
-<!-- If Yes, please describe the impact and migration path for existing NextUI users. -->
+<!-- If Yes, please describe the impact and migration path for existing HeroUI users. -->
 
 ## 📝 Additional Information

.github/workflows/QA.yaml

@@ -4,6 +4,9 @@ on:
   pull_request:
     branches:
       - canary
+      - v3*
+      - "beta-*"
+      - "rc-*"
 
 jobs:
   build:
@@ -11,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install
         uses: ./.github/common-actions/install
@@ -19,25 +22,12 @@ jobs:
       - name: Build packages
         run: pnpm build
 
-  tests:
-    name: Tests
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout branch
-        uses: actions/checkout@v4
-
-      - name: Install
-        uses: ./.github/common-actions/install
-
-      - name: Run tests
-        run: pnpm test
-
   eslint:
     name: ESLint
     runs-on: ubuntu-latest
     steps:
       - name: Checkout branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install
         uses: ./.github/common-actions/install
@@ -50,7 +40,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install
         uses: ./.github/common-actions/install
@@ -58,15 +48,24 @@ jobs:
       - name: Run typecheck
         run: pnpm typecheck
 
-  prettier:
-    name: Prettier
+  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@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Install
         uses: ./.github/common-actions/install
 
-      - name: Run prettier
-        run: pnpm format:check
+      - name: Build packages
+        run: pnpm build
+
+      - name: Release
+        run: pnpx pkg-pr-new publish --pnpm './packages/styles' './packages/react'

.github/workflows/enter-pre-release-mode.yaml

@@ -1,33 +0,0 @@
-name: Enter pre-release mode
-on: workflow_dispatch
-
-jobs:
-  enter-pre-release-mode:
-    if: ${{ github.ref == 'refs/heads/beta/release-next' || github.ref == 'refs/heads/canary' }}
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - name: Checkout branch
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install
-        uses: ./.github/common-actions/install
-
-      - name: Enter pre-release mode
-        id: enter-pre-release-mode
-        run: |
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git config user.name "github-actions[bot]"
-          if [ ${{ github.ref }} == 'refs/heads/canary' ]; then
-            pnpm changeset:canary
-          else
-            pnpm changeset:beta
-          fi
-          git add -A
-          git commit -m 'chore(pre-release): enter pre-release mode'
-          git push

.github/workflows/exit-pre-release.yaml

@@ -1,37 +0,0 @@
-name: Exit pre-release mode
-
-on: workflow_dispatch
-jobs:
-  exit-pre-release-mode:
-    if: ${{ github.ref == 'refs/heads/beta/release-next' || github.ref == 'refs/heads/canary' }}
-    name: exit pre-release mode
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-
-    steps:
-      - name: Checkout branch
-        uses: actions/checkout@v3
-        with:
-          ref: ${{ github.event.inputs.branch }}
-          fetch-depth: 0
-
-      - name: Install
-        uses: ./.github/common-actions/install
-
-      - name: remove pre.json
-        # we only remove .changeset/pre.json here 
-        # since we want to keep the changeset files introduced in beta/release-next or canary branch
-        # once we merge it to canary / main, those files will be removed in version PR in canary 
-        # and converted to corresponding changelogs
-        run: npx rimraf .changeset/pre.json
-
-      - name: Commit and push changes
-        run: |
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git config user.name "github-actions[bot]"
-          git add -A
-          git commit -m "ci(changesets): exit pre-release mode"
-          git push

.github/workflows/pre-release.yaml

@@ -1,64 +0,0 @@
-name: Pre-release
-
-on:
-  push:
-    paths:
-      - ".changeset/**"
-      - "packages/**"
-    branches:
-      - "beta/release-next"
-      - "canary"
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  prerelease:
-    name: changesets pre-release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - name: Checkout branch
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install
-        uses: ./.github/common-actions/install
-
-      - name: Check if pre.json exists
-        id: check_if_pre_json_exists
-        uses: andstor/file-existence-action@v3.0.0
-        with:
-          files: ".changeset/pre.json"
-
-      - name: Get pre-release changesets
-        id: get-pre-release-changesets
-        uses: notiz-dev/github-action-json-property@release
-        with:
-          path: ".changeset/pre.json"
-          prop_path: "changesets"
-
-      - name: Create pre-release PR
-        id: create-pre-release-pr
-        if: "${{ steps.check_if_pre_json_exists.outputs.files_exists == 'true' && !startsWith(github.event.head_commit.message, 'ci(changesets): version packages') }}"
-        uses: changesets/action@v1
-        with:
-          version: pnpm run version
-          title: "ci(changesets): :package: version packages"
-          commit: "ci(changesets): version packages"
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish to NPM
-        id: publish-to-npm
-        if: "${{ steps.check_if_pre_json_exists.outputs.files_exists == 'true' && contains(github.event.head_commit.message, 'ci(changesets): :package: version packages') }}"
-        uses: changesets/action@v1
-        with:
-          publish: pnpm run release
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yaml

@@ -1,42 +0,0 @@
-name: Release
-
-on:
-  push:
-    paths:
-      - ".changeset/**"
-      - "packages/**"
-    branches:
-      - main
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout branch
-        uses: actions/checkout@v4
-
-      - name: Install
-        uses: ./.github/common-actions/install
-
-      - name: Build
-        run: pnpm build
-
-      - name: Tests
-        run: pnpm test
-
-      - name: Create Release Pull Request or Publish to NPM
-        id: changesets
-        uses: changesets/action@v1
-        with:
-          publish: pnpm release
-          title: "ci(changesets): :package: version packages"
-          commit: "ci(changesets): version packages"
-          setupGitUser: false
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.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' || '' }}

.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"
+            }

.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 }}

.gitignore

@@ -1,65 +1,93 @@
-
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+# cache
+.turbo
+.cache
+.rollup.cache
+.swc
 
 # dependencies
 node_modules
-/.pnp
+.pnp
 .pnp.js
 
 # testing
-/coverage
 coverage
+__snapshots__
+coverage.json
 
 # next.js
-/.next/
-.next/
-/out/
+.next
+out
+.vercel
 
 # production
-/build
-dist/
-storybook-static
-/packages/storybook/public/tailwind.css
-
-# misc
-.DS_Store
-.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-.env.production
-
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
+build
+dist
 
 # debug
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-.yarn-integrity
+
+# 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
-.now
-dist
-esm
-examples/**/yarn.lock
-examples/**/out
-examples/**/.next
-packages/**/*.backup
-packages/**/*.backup.ts
 
-.vercel
+# temporary
+.temp
 
-# ignore sitemap
-apps/**/sitemap.xml
-
-# turbo
-.turbo
-packages/**/.turbo
+# 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

.husky/commit-msg

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-pnpm commitlint --config .commitlintrc.cjs --edit ${1}
+pnpm commitlint --config commitlint.config.mjs --edit ${1}

.husky/post-merge

@@ -1,5 +1 @@
-#!/usr/bin/env sh
-huskyDir=$(dirname -- "$0")
-. "$huskyDir/_/husky.sh"
-
-. "$huskyDir/scripts/update-dep"
+. "$(dirname -- "$0")/scripts/pnpm-install"

.husky/post-rebase

@@ -1,5 +1 @@
-#!/usr/bin/env sh
-huskyDir=$(dirname -- "$0")
-. "$huskyDir/_/husky.sh"
-
-. "$huskyDir/scripts/update-dep"
+. "$(dirname -- "$0")/scripts/pnpm-install"

.husky/pre-commit

@@ -1,9 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-# Avoid excessive outputs
-if [ -t 2 ]; then
-  exec >/dev/tty 2>&1
-fi
-
-pnpm lint-staged -c .lintstagedrc.cjs
+pnpm lint-staged -c lint-staged.config.mjs

.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"

.husky/scripts/update-dep

@@ -1,11 +0,0 @@
-#!/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[36mDetected changes in pnpm-lock.yaml, starting dependency update\033[0m\n"
-    eval "$2"
-  fi
-}
-
-check_run pnpm-lock.yaml "pnpm install --color"

.lintstagedrc.cjs

@@ -1,26 +0,0 @@
-const {relative} = require("path");
-
-const {ESLint} = require("eslint");
-
-const removeIgnoredFiles = async (files) => {
-  const cwd = process.cwd();
-  const eslint = new ESLint();
-  const relativePaths = files.map((file) => relative(cwd, file));
-  const isIgnored = await Promise.all(relativePaths.map((file) => eslint.isPathIgnored(file)));
-  const filteredFiles = files.filter((_, i) => !isIgnored[i]);
-
-  return filteredFiles.join(" ");
-};
-
-module.exports = {
-  "**/*.{js,ts,jsx,tsx}": async (files) => {
-    const filesToLint = await removeIgnoredFiles(files);
-
-    return [`eslint -c .eslintrc.json --max-warnings=0 --fix ${filesToLint}`];
-  },
-  "**/*.css": async (files) => {
-    const filesToLint = await removeIgnoredFiles(files);
-
-    return [`prettier --config .prettierrc.json --ignore-path --write ${filesToLint}`];
-  },
-};

.npmrc

@@ -1,6 +1,5 @@
-strict-peer-dependencies=false
+auto-install-peers=true
 enable-pre-post-scripts=true
-public-hoist-pattern[]=*tailwind-variants*
-public-hoist-pattern[]=*framer-motion*
-public-hoist-pattern[]=*@react-aria/interactions*
-public-hoist-pattern[]=*@nextui-org/theme*
+lockfile=true
+save-exact=true
+strict-peer-dependencies=false

.nvmrc

@@ -1 +1 @@
-v20.16.0
+v22.14.0

.prettierignore

@@ -1,16 +1,32 @@
-dist
-node_modules
-plop
-coverage
-.changeset
-.next
-build
-scripts
+**/.temp
+**/.next
+**/.swc
+**/.turbo
+**/.cache
+**/.build
+**/.vercel
+**/dist
+**/build
+**/storybook-static
+.rollup.cache
+.rollup.cache/**
+**/node_modules/
+**/public/*
 pnpm-lock.yaml
-!.storybook
-!.commitlintrc.cjs
-!.lintstagedrc.cjs
-!jest.config.js
-!plopfile.js
-!react-shim.js
-!tsup.config.ts
+**/.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

.prettierrc.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/prettierrc.json",
-  "tabWidth": 2,
-  "printWidth": 100,
-  "semi": true,
-  "useTabs": false,
-  "singleQuote": false,
-  "bracketSpacing": false,
-  "endOfLine": "auto",
-  "arrowParens": "always",
-  "trailingComma": "all"
-}

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "bradlc.vscode-tailwindcss",
+    "editorconfig.editorconfig",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "unifiedjs.vscode-mdx"
+  ]
+}

.vscode/settings.json

@@ -1,14 +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"
   },
-  "tailwindCSS.experimental.configFile": {
-    "packages/storybook/tailwind.config.js": ["packages/core/theme/**/*", "packages/components/**/*"],
-    "apps/docs/tailwind.config.js": "apps/docs/**/*"
+  "files.associations": {
+    "**/.vscode/*.json": "jsonc"
   },
-  "tailwindCSS.experimental.classRegex": [
-    ["([\"'`][^\"'`]*.*?[\"'`])", "[\"'`]([^\"'`]*).*?[\"'`]"]
-  ]
+  "[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/**"
+    ]
+  }
 }

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`.

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.

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-# Next UI Contributing Guide
+# HeroUI Contributing Guide
 
-Hello!, I am very excited that you are interested in contributing with Next UI. However, before submitting your contribution, be sure to take a moment and read the following guidelines.
+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/jrgarciadev/nextui/blob/main/CODE_OF_CONDUCT.md)
+- [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)
@@ -19,8 +19,8 @@ Hello!, I am very excited that you are interested in contributing with Next UI.
   testing
 - [Testing Library](https://testing-library.com/) for testing components and
   hooks
-- [Changeset](https://github.com/atlassian/changesets) for changes
-  documentation, changelog generation, and release management.
+- [bumpp](https://github.com/antfu/bumpp) for version bumping and release
+  management.
 
 
 ### Commit Convention
@@ -71,7 +71,7 @@ https://www.conventionalcommits.org/ or check out the
 
 ### Steps to PR
 
-1. Fork of the nextui repository and clone your fork
+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`
@@ -79,24 +79,15 @@ https://www.conventionalcommits.org/ or check out the
    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/nextui-org/nextui/blob/main/CONTRIBUTING.md#commit-convention).
+   [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. Run `pnpm changeset` to create a detailed description of your changes. This
-   will be used to generate a changelog when we publish an update.
-   [Learn more about Changeset](https://github.com/atlassian/changesets/tree/master/packages/cli).
-   Please note that you might have to run `git fetch origin main:master` (where
-   origin will be your fork on GitHub) before `pnpm changeset` works.
-5. Also, if you provide `jsx` snippets to the changeset, please turn off the
-   live preview by doing the following at the beginning of the snippet:
-   ` ```jsx live=false`
-
-> If you made minor changes like CI config, prettier, etc, you can run
-> `pnpm changeset add --empty` to generate an empty changeset file to document
-> your changes.
+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
 
@@ -117,7 +108,7 @@ 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 NextUI core components
+## Start the dev babel server of HeroUI core components
 pnpm dev
 
 ## optional
@@ -128,10 +119,10 @@ pnpm dev:docs ## this will start the documentation next.js server and it will au
 ```
 
 - If you will be working just on the documentation source code / mdx, you can use the following commands to build
-  NextUI components and then start the next.js dev server:
+  HeroUI components and then start the next.js dev server:
 
 ```bash
-## Build NextUI source components
+## Build HeroUI source components
 pnpm build
 
 ## Start the next.js documentation dev server
@@ -210,13 +201,13 @@ 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 NextUI has a stable release new components will be created only for the core team.
+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 `NextUI` are already imported.
+The main documentation lives in the `apps/docs/content` folder, the project uses MDX and all `HeroUI` are already imported.
 
 ## Breaking changes
 
@@ -224,7 +215,7 @@ Breaking changes should be accompanied with deprecations of removed functionalit
 
 ## Becoming a maintainer
 
-If you are interested in becoming a NextUI maintainer, start by
+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.
@@ -235,7 +226,7 @@ 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/nextui-org/people) page.
+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.

LICENSE

@@ -1,21 +1,199 @@
-MIT License
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright (c) 2020 Next UI
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   1. Definitions.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+      "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.

README.md

@@ -1 +1 @@
-packages/core/react/README.md
+packages/react/README.md

apps/docs/.env.example

@@ -1,23 +1,11 @@
-## use cache for Github requests like "tags"
-USE_CACHE=true/false
-## Algolia client app id
-NEXT_PUBLIC_ALGOLIA_APP_ID=
-## Algolia client search only api key
-NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY=
-
-
-# Vercel Env (is used for skipping typescript check)
-IS_VERCEL_ENV=true/false
-IS_PREVIEW=true/false
-ANALYZE_BUNDLE=true/false
-
-# Vercel preview env (is used for taking the docs directly from the project files)
-NEXT_PUBLIC_PREVIEW=true/false
-
-## Featurebase
-NEXT_PUBLIC_FB_FEEDBACK_ORG=
-NEXT_PUBLIC_FB_FEEDBACK_URL=
-
-# PostHog
-NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
-NEXT_PUBLIC_POSTHOG_HOST=your-posthog-host
+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>"

apps/docs/.eslintrc.json

@@ -1,31 +0,0 @@
-{
-  "extends": ["../../.eslintrc.json"],
-  "ignorePatterns": ["!**/*"],
-  "overrides": [
-    {
-      "files": ["*.ts", "*.tsx"],
-      "parserOptions": {
-        "project": ["apps/docs/tsconfig(.*)?.json"],
-        "ecmaFeatures": {
-          "jsx": true
-        }
-      },
-      "rules": {
-        "react/no-unknown-property": [
-          2,
-          {
-            "ignore": ["jsx", "global"]
-          }
-        ]
-      }
-    },
-    {
-      "files": ["*.ts", "*.tsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.js", "*.jsx"],
-      "rules": {}
-    }
-  ]
-}

apps/docs/.gitignore

@@ -1,37 +0,0 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-sitemap.xml
-
-# dependencies
-/node_modules
-/.pnp
-.pnp.js
-
-# testing
-/coverage
-
-# next.js
-/.next/
-/out/
-
-# production
-/build
-
-# misc
-.DS_Store
-*.pem
-
-# debug
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-# local env files
-.env
-.env*.local
-
-# vercel
-.vercel
-
-# typescript
-*.tsbuildinfo
-next-env.d.ts

apps/docs/.npmrc

@@ -0,0 +1 @@
+enable-pre-post-scripts=true

apps/docs/.sponsorsrc

@@ -1,332 +0,0 @@
-[
-  {
-    "MemberId": 275354,
-    "createdAt": "2022-02-18 11:57",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 5,
-    "currency": "USD",
-    "lastTransactionAt": "2022-02-18 11:57",
-    "lastTransactionAmount": 5,
-    "profile": "https://opencollective.com/guest-7dc076fb",
-    "name": "jorge",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/undefined",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 277819,
-    "createdAt": "2022-03-01 09:13",
-    "type": "USER",
-    "role": "BACKER",
-    "isActive": true,
-    "totalAmountDonated": 10,
-    "currency": "USD",
-    "lastTransactionAt": "2022-03-01 09:13",
-    "lastTransactionAmount": 10,
-    "profile": "https://opencollective.com/dhananjay-senday",
-    "name": "Dhananjay Senday",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/undefined",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 292380,
-    "createdAt": "2022-04-22 07:47",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 10,
-    "currency": "USD",
-    "lastTransactionAt": "2022-04-22 07:47",
-    "lastTransactionAmount": 10,
-    "profile": "https://opencollective.com/manuel5",
-    "name": "manuel-rw",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/292380.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 327844,
-    "createdAt": "2022-08-26 21:32",
-    "type": "ORGANIZATION",
-    "role": "BACKER",
-    "tier": "Gold Sponsor 🥇",
-    "isActive": true,
-    "totalAmountDonated": 200,
-    "currency": "USD",
-    "lastTransactionAt": "2022-12-22 07:19",
-    "lastTransactionAmount": 100,
-    "profile": "https://opencollective.com/lowdefy",
-    "name": "Lowdefy",
-    "company": null,
-    "description": "Create custom web apps in minutes",
-    "image": "/sponsors/327844.jpg",
-    "twitter": "https://twitter.com/lowdefy",
-    "github": "https://github.com/lowdefy",
-    "website": "https://lowdefy.com"
-  },
-  {
-    "MemberId": 347048,
-    "createdAt": "2022-10-30 06:25",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 1,
-    "currency": "USD",
-    "lastTransactionAt": "2022-10-30 06:25",
-    "lastTransactionAmount": 1,
-    "profile": "https://opencollective.com/william-frank-monroy-mamani",
-    "name": "William Frank Monroy Mamani",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/347048.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 374896,
-    "createdAt": "2022-12-22 05:28",
-    "type": "ORGANIZATION",
-    "role": "BACKER",
-    "tier": "bronze sponsor 🥉",
-    "isActive": true,
-    "totalAmountDonated": 70,
-    "currency": "USD",
-    "lastTransactionAt": "2023-07-02 09:04",
-    "lastTransactionAmount": 10,
-    "profile": "https://opencollective.com/chartbrew",
-    "name": "Chartbrew",
-    "company": null,
-    "description": "Open source visualization and reporting platform",
-    "image": "/sponsors/374896.jpg",
-    "twitter": null,
-    "github": null,
-    "website": "https://chartbrew.com"
-  },
-  {
-    "MemberId": 375034,
-    "createdAt": "2022-12-22 13:16",
-    "type": "USER",
-    "role": "BACKER",
-    "isActive": true,
-    "totalAmountDonated": 50,
-    "currency": "USD",
-    "lastTransactionAt": "2022-12-22 13:16",
-    "lastTransactionAmount": 50,
-    "profile": "https://opencollective.com/jan-wagebach",
-    "name": "PRISMA European Capacity Platform GmbH",
-    "company": "PRISMA European Capacity Platform GmbH",
-    "description": null,
-    "image": "/sponsors/375034.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 395990,
-    "createdAt": "2023-02-11 13:12",
-    "type": "ORGANIZATION",
-    "role": "BACKER",
-    "tier": "Gold Sponsor 🥇",
-    "isActive": true,
-    "totalAmountDonated": 100,
-    "currency": "USD",
-    "lastTransactionAt": "2023-02-11 13:12",
-    "lastTransactionAmount": 100,
-    "profile": "https://opencollective.com/likn",
-    "name": "LIKN",
-    "company": null,
-    "description": "LIKN is a powerful, but simple Web3 component and protocol. Connect Web2 content to Web3, and solely mint content NFTs by URL. Share and Trade in different platforms and marketplaces. OpenAI empowers LIKN which can automatically generate NFT metadata. ",
-    "image": "/sponsors/395990.jpg",
-    "twitter": "https://twitter.com/oxlikn",
-    "github": "https://github.com/0xLIKN",
-    "website": "https://www.likn.co/?ref=opencollective"
-  },
-  {
-    "MemberId": 404415,
-    "createdAt": "2023-03-01 16:22",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 1,
-    "currency": "USD",
-    "lastTransactionAt": "2023-03-01 16:22",
-    "lastTransactionAmount": 1,
-    "profile": "https://opencollective.com/rharison-lucas-moreira-abreu",
-    "name": "Rharison Lucas Moreira Abreu",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/404415.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 407510,
-    "createdAt": "2023-03-07 22:27",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 1,
-    "currency": "USD",
-    "lastTransactionAt": "2023-03-07 22:27",
-    "lastTransactionAmount": 1,
-    "profile": "https://opencollective.com/higherror",
-    "name": "HighError",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/407510.jpg",
-    "email": null,
-    "twitter": null,
-    "github": "https://github.com/HighError",
-    "website": null
-  },
-  {
-    "MemberId": 409558,
-    "createdAt": "2023-03-12 21:41",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 1,
-    "currency": "USD",
-    "lastTransactionAt": "2023-03-12 21:41",
-    "lastTransactionAmount": 1,
-    "profile": "https://opencollective.com/guest-6133a45c",
-    "name": "Kristof",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/undefined",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 438158,
-    "createdAt": "2023-05-31 22:44",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 5,
-    "currency": "USD",
-    "lastTransactionAt": "2023-05-31 22:44",
-    "lastTransactionAmount": 5,
-    "profile": "https://opencollective.com/elektrnik",
-    "name": "ELEKTRNIK",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/438158.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 438877,
-    "createdAt": "2023-06-02 17:56",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 1,
-    "currency": "USD",
-    "lastTransactionAt": "2023-06-02 17:56",
-    "lastTransactionAmount": 1,
-    "profile": "https://opencollective.com/guest-425370ea",
-    "name": "Gabriel Jiménez",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/undefined",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 439182,
-    "createdAt": "2023-06-03 15:15",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 1,
-    "currency": "USD",
-    "lastTransactionAt": "2023-06-03 15:15",
-    "lastTransactionAmount": 1,
-    "profile": "https://opencollective.com/jay-thanawut1",
-    "name": "Jay Thanawut",
-    "company": null,
-    "description": null,
-    "image": "/sponsors/439182.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": null
-  },
-  {
-    "MemberId": 442878,
-    "createdAt": "2023-06-13 13:51",
-    "type": "USER",
-    "role": "BACKER",
-    "tier": "Backer 🖤",
-    "isActive": true,
-    "totalAmountDonated": 5,
-    "currency": "USD",
-    "lastTransactionAt": "2023-06-13 13:51",
-    "lastTransactionAmount": 5,
-    "profile": "https://opencollective.com/encurme",
-    "name": "EncurMe",
-    "company": "EncurMe",
-    "description": null,
-    "image": "/sponsors/442878.jpg",
-    "email": null,
-    "twitter": null,
-    "github": null,
-    "website": "https://encur.me/"
-  },
-  {
-    "MemberId": 571230,
-    "createdAt": "2024-06-01 18:47",
-    "type": "ORGANIZATION",
-    "role": "BACKER",
-    "tier": "Gold Sponsor 🥇",
-    "isActive": true,
-    "totalAmountDonated": 100,
-    "currency": "USD",
-    "lastTransactionAt": "2024-06-01 18:47",
-    "lastTransactionAmount": 100,
-    "profile": "https://opencollective.com/coderabbit",
-    "name": "CodeRabbit",
-    "company": null,
-    "description": "CodeRabbit is an AI-driven context-aware code reviewer that provides line-by-line feedback and smart chat. ",
-    "image": "/sponsors/571230.jpg",
-    "twitter": null,
-    "github": null,
-    "website": "https://coderabbit.ai"
-  }
-]

apps/docs/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2020 Next UI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

apps/docs/README.md

@@ -1,36 +0,0 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
-
-## Getting Started
-
-First, run the development server:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
-
-[http://localhost:3000/api/hello](http://localhost:3000/api/hello) is an endpoint that uses [Route Handlers](https://beta.nextjs.org/docs/routing/route-handlers). This endpoint can be edited in `app/api/hello/route.ts`.
-
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.

apps/docs/app/blog/[slug]/page.tsx

@@ -1,132 +0,0 @@
-import type {Metadata} from "next";
-
-import {notFound} from "next/navigation";
-import {allBlogPosts} from "contentlayer2/generated";
-import {Link, User} from "@nextui-org/react";
-import {format, parseISO} from "date-fns";
-import NextLink from "next/link";
-import {Balancer} from "react-wrap-balancer";
-
-import {__DEV__, __PREVIEW__} from "@/utils";
-import {MDXContent} from "@/components/mdx-content";
-import {siteConfig} from "@/config/site";
-import {Route} from "@/libs/docs/page";
-import {ChevronRightLinearIcon} from "@/components/icons";
-
-interface BlogPostProps {
-  params: {
-    slug: string;
-  };
-}
-
-const isDraftVisible = __DEV__ || __PREVIEW__;
-
-async function getBlogPostFromParams({params}: BlogPostProps) {
-  const slug = params.slug || "";
-  const post = allBlogPosts.find((post) => post.slugAsParams === slug);
-
-  if (!post) {
-    null;
-  }
-
-  const currentRoute: Route = {
-    key: post?._id,
-    title: post?.title,
-    path: `/${post?._raw?.sourceFilePath}`,
-  };
-
-  return {post, currentRoute};
-}
-
-export async function generateMetadata({params}: BlogPostProps): Promise<Metadata> {
-  const {post} = await getBlogPostFromParams({params});
-
-  if (!post) {
-    return {};
-  }
-
-  return {
-    title: post.title,
-    description: post.description,
-    openGraph: {
-      title: post.title,
-      description: post.description,
-      type: "article",
-      url: post.url,
-      images: [
-        {
-          url: post.imageAsParams || siteConfig.ogImage,
-          width: 1200,
-          height: 630,
-          alt: post.title || siteConfig.name,
-        },
-      ],
-    },
-    twitter: {
-      card: "summary_large_image",
-      title: post.title,
-      description: post.description,
-      images: [siteConfig.ogImage],
-      creator: siteConfig.creator,
-    },
-  };
-}
-
-export async function generateStaticParams(): Promise<BlogPostProps["params"][]> {
-  return allBlogPosts.map((doc) => ({
-    slug: doc.slugAsParams,
-  }));
-}
-
-export default async function DocPage({params}: BlogPostProps) {
-  const {post} = await getBlogPostFromParams({params});
-
-  if (!post || (post.draft && !isDraftVisible)) {
-    notFound();
-  }
-
-  return (
-    <div className="w-full mt-12 flex flex-col justify-start items-center prose prose-neutral">
-      <div className="w-full max-w-4xl">
-        <Link
-          isBlock
-          as={NextLink}
-          className="mb-8 -ml-3 text-default-500 hover:text-default-900"
-          color="foreground"
-          href="/blog"
-          size="sm"
-        >
-          <ChevronRightLinearIcon className="rotate-180 inline-block mr-1" size={15} />
-          Back to blog
-        </Link>
-
-        <time className="block text-small mb-2 text-default-500" dateTime={post.date}>
-          {format(parseISO(post.date), "LLLL d, yyyy")}
-        </time>
-        <div className="mb-3 flex w-full flex-col items-start">
-          <User
-            isExternal
-            as={Link}
-            avatarProps={{
-              className: "w-9 h-9 text-large",
-              src: post.author?.avatar,
-            }}
-            className="hover:opacity-100"
-            classNames={{
-              base: "-ml-2 px-2 py-1.5 hover:bg-default-100 dark:hover:bg-default-50 cursor-pointer transition-colors",
-              name: "text-foreground",
-            }}
-            description={post.author?.username}
-            href={post.author?.link}
-            name={post.author?.name}
-          />
-        </div>
-        <h1 className="mb-2 font-bold text-4xl">
-          <Balancer>{post.title}</Balancer>
-          <strong className="text-default-300">{post?.draft && " (Draft)"}</strong>
-        </h1>
-        <MDXContent code={post.body.code} />
-      </div>
-    </div>
-  );
-}

apps/docs/app/blog/layout.tsx

@@ -1,31 +0,0 @@
-import {Image} from "@nextui-org/react";
-
-import {ScriptProviders} from "@/components/scripts/script-providers";
-
-interface DocsLayoutProps {
-  children: React.ReactNode;
-}
-
-export default function DocsLayout({children}: DocsLayoutProps) {
-  return (
-    <>
-      <main className="relative container mx-auto max-w-7xl z-10 px-6 min-h-[calc(100vh_-_64px_-_108px)] mb-12 flex-grow">
-        {children}
-      </main>
-      <div
-        aria-hidden="true"
-        className="fixed hidden dark:md:block dark:opacity-70 -bottom-[40%] -left-[20%] z-0"
-      >
-        <Image removeWrapper alt="docs left background" src="/gradients/docs-left.png" />
-      </div>
-      <div
-        aria-hidden="true"
-        className="fixed hidden dark:md:block dark:opacity-70 -top-[80%] -right-[60%] 2xl:-top-[60%] 2xl:-right-[45%] z-0 rotate-12"
-      >
-        <Image removeWrapper alt="docs right background" src="/gradients/docs-right.png" />
-      </div>
-
-      <ScriptProviders />
-    </>
-  );
-}

apps/docs/app/blog/page.tsx

@@ -1,29 +0,0 @@
-import {allBlogPosts} from "contentlayer2/generated";
-import {compareDesc} from "date-fns";
-
-import {BlogPostList} from "@/components/blog-post";
-import {__DEV__, __PREVIEW__} from "@/utils";
-
-const isDraftVisible = __DEV__ || __PREVIEW__;
-
-export default function Blog() {
-  const posts = allBlogPosts
-    .sort((a, b) => compareDesc(new Date(a.date), new Date(b.date)))
-    ?.filter((post) => {
-      if (post.draft && !isDraftVisible) {
-        return false;
-      }
-
-      return true;
-    });
-
-  return (
-    <div className="w-full lg:px-16 mt-12">
-      <div className="text-center">
-        <h1 className="mb-2 font-bold text-4xl">NextUI Latest Updates</h1>
-        <h5 className="text-default-500 text-lg">All the latest news about NextUI.</h5>
-      </div>
-      <BlogPostList posts={posts} />
-    </div>
-  );
-}

apps/docs/app/docs/[[...slug]]/page.tsx

@@ -1,108 +0,0 @@
-import type {Metadata} from "next";
-
-import {notFound} from "next/navigation";
-import {allDocs} from "contentlayer2/generated";
-import {Link} from "@nextui-org/react";
-
-import {MDXContent} from "@/components/mdx-content";
-import {siteConfig} from "@/config/site";
-import {DocsPager, DocsToc} from "@/components/docs";
-import {Route} from "@/libs/docs/page";
-import {GITHUB_URL, REPO_NAME} from "@/libs/github/constants";
-import {CONTENT_PATH, TAG} from "@/libs/docs/config";
-import {getHeadings} from "@/libs/docs/utils";
-
-interface DocPageProps {
-  params: {
-    slug: string[];
-  };
-}
-
-async function getDocFromParams({params}: DocPageProps) {
-  const slug = params.slug?.join("/") || "";
-  const doc = allDocs.find((doc) => doc.slugAsParams === slug);
-
-  if (!doc) {
-    null;
-  }
-
-  const headings = getHeadings(doc?.body.raw);
-
-  const currentRoute: Route = {
-    key: doc?._id,
-    title: doc?.title,
-    path: `/${doc?._raw?.sourceFilePath}`,
-  };
-
-  return {doc, headings, currentRoute};
-}
-
-export async function generateMetadata({params}: DocPageProps): Promise<Metadata> {
-  const {doc} = await getDocFromParams({params});
-
-  if (!doc) {
-    return {};
-  }
-
-  return {
-    title: doc.title,
-    description: doc.description,
-    openGraph: {
-      title: doc.title,
-      description: doc.description,
-      type: "article",
-      url: doc.url,
-      images: [
-        {
-          url: siteConfig.ogImage,
-          width: 1200,
-          height: 630,
-          alt: siteConfig.name,
-        },
-      ],
-    },
-    twitter: {
-      card: "summary_large_image",
-      title: doc.title,
-      description: doc.description,
-      images: [siteConfig.ogImage],
-      creator: siteConfig.creator,
-    },
-  };
-}
-
-export async function generateStaticParams(): Promise<DocPageProps["params"][]> {
-  return allDocs.map((doc) => ({
-    slug: doc.slugAsParams.split("/"),
-  }));
-}
-
-export default async function DocPage({params}: DocPageProps) {
-  const {doc, headings, currentRoute} = await getDocFromParams({params});
-
-  if (!doc) {
-    notFound();
-  }
-  const editUrl = `${GITHUB_URL}/${REPO_NAME}/edit/${TAG}${CONTENT_PATH}${currentRoute?.path}`;
-
-  return (
-    <>
-      <div className="col-span-12 lg:col-span-10 xl:col-span-8 lg:px-16 mt-10">
-        <div className="w-full prose prose-neutral">
-          <MDXContent code={doc.body.code} />
-        </div>
-        {currentRoute && <DocsPager currentRoute={currentRoute} />}
-        <footer>
-          <Link isExternal showAnchorIcon href={editUrl} size="sm">
-            Edit this page on GitHub
-          </Link>
-        </footer>
-      </div>
-      {headings && headings.length > 0 && (
-        <div className="hidden z-10 xl:flex xl:col-span-2 mt-8 pl-4">
-          <DocsToc headings={headings} />
-        </div>
-      )}
-    </>
-  );
-}

apps/docs/app/docs/layout.tsx

@@ -1,38 +0,0 @@
-import {Image} from "@nextui-org/react";
-
-import manifest from "@/config/routes.json";
-import {DocsSidebar} from "@/components/docs/sidebar";
-import {ScriptProviders} from "@/components/scripts/script-providers";
-
-interface DocsLayoutProps {
-  children: React.ReactNode;
-}
-
-export default function DocsLayout({children}: DocsLayoutProps) {
-  return (
-    <>
-      <main className="relative container mx-auto max-w-7xl z-10 px-6 min-h-[calc(100vh_-_64px_-_108px)] mb-12 flex-grow">
-        <div className="grid grid-cols-12">
-          <div className="hidden overflow-visible relative z-10 lg:block lg:col-span-2 mt-8 pr-4">
-            <DocsSidebar routes={manifest.routes} />
-          </div>
-          {children}
-        </div>
-      </main>
-      <div
-        aria-hidden="true"
-        className="fixed hidden dark:md:block dark:opacity-70 -bottom-[40%] -left-[20%] z-0"
-      >
-        <Image removeWrapper alt="docs left background" src="/gradients/docs-left.png" />
-      </div>
-      <div
-        aria-hidden="true"
-        className="fixed hidden dark:md:block dark:opacity-70 -top-[80%] -right-[60%] 2xl:-top-[60%] 2xl:-right-[45%] z-0 rotate-12"
-      >
-        <Image removeWrapper alt="docs right background" src="/gradients/docs-right.png" />
-      </div>
-
-      <ScriptProviders />
-    </>
-  );
-}

apps/docs/app/examples/autocomplete/async-filtering/page.tsx

@@ -1,47 +0,0 @@
-/* eslint-disable no-console */
-"use client";
-
-import * as React from "react";
-import {Autocomplete, AutocompleteItem} from "@nextui-org/react";
-import {useAsyncList} from "@react-stately/data";
-
-type SWCharacter = {
-  name: string;
-  height: string;
-  mass: string;
-  birth_year: string;
-};
-
-export default function Page() {
-  let list = useAsyncList<SWCharacter>({
-    async load({signal, filterText}) {
-      let res = await fetch(`https://swapi.py4e.com/api/people/?search=${filterText}`, {signal});
-      let json = await res.json();
-
-      return {
-        items: json.results,
-      };
-    },
-  });
-
-  return (
-    <div className="p-6">
-      <Autocomplete
-        className="max-w-xs"
-        inputValue={list.filterText}
-        isLoading={list.isLoading}
-        items={list.items}
-        label="Select a character"
-        placeholder="Type to search..."
-        variant="bordered"
-        onInputChange={list.setFilterText}
-      >
-        {(item) => (
-          <AutocompleteItem key={item.name} className="capitalize">
-            {item.name}
-          </AutocompleteItem>
-        )}
-      </Autocomplete>
-    </div>
-  );
-}

apps/docs/app/examples/autocomplete/async-items-loading/page.tsx

@@ -1,113 +0,0 @@
-/* eslint-disable no-console */
-"use client";
-
-import * as React from "react";
-import {Autocomplete, AutocompleteItem} from "@nextui-org/react";
-import {useInfiniteScroll} from "@nextui-org/use-infinite-scroll";
-
-type Pokemon = {
-  name: string;
-  url: string;
-};
-
-type UsePokemonListProps = {
-  /** Delay to wait before fetching more items */
-  fetchDelay?: number;
-};
-
-function usePokemonList({fetchDelay = 0}: UsePokemonListProps = {}) {
-  const [items, setItems] = React.useState<Pokemon[]>([]);
-  const [hasMore, setHasMore] = React.useState(true);
-  const [isLoading, setIsLoading] = React.useState(false);
-  const [offset, setOffset] = React.useState(0);
-  const limit = 10; // Number of items per page, adjust as necessary
-
-  const loadPokemon = async (currentOffset: number) => {
-    const controller = new AbortController();
-    const {signal} = controller;
-
-    try {
-      setIsLoading(true);
-
-      if (offset > 0) {
-        // Delay to simulate network latency
-        await new Promise((resolve) => setTimeout(resolve, fetchDelay));
-      }
-
-      let res = await fetch(
-        `https://pokeapi.co/api/v2/pokemon?offset=${currentOffset}&limit=${limit}`,
-        {signal},
-      );
-
-      if (!res.ok) {
-        throw new Error("Network response was not ok");
-      }
-
-      let json = await res.json();
-
-      setHasMore(json.next !== null);
-      // Append new results to existing ones
-      setItems((prevItems) => [...prevItems, ...json.results]);
-    } catch (error) {
-      // @ts-ignore
-      if (error.name === "AbortError") {
-        console.log("Fetch aborted");
-      } else {
-        console.error("There was an error with the fetch operation:", error);
-      }
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  React.useEffect(() => {
-    loadPokemon(offset);
-  }, []);
-
-  const onLoadMore = () => {
-    const newOffset = offset + limit;
-
-    setOffset(newOffset);
-    loadPokemon(newOffset);
-  };
-
-  return {
-    items,
-    hasMore,
-    isLoading,
-    onLoadMore,
-  };
-}
-
-export default function Page() {
-  const [isOpen, setIsOpen] = React.useState(false);
-  const {items, hasMore, isLoading, onLoadMore} = usePokemonList({fetchDelay: 1500});
-
-  const [, scrollerRef] = useInfiniteScroll({
-    hasMore,
-    isEnabled: isOpen,
-    shouldUseLoader: false, // We don't want to show the loader at the bottom of the list
-    onLoadMore,
-  });
-
-  return (
-    <div className="p-6">
-      <Autocomplete
-        className="max-w-xs"
-        defaultItems={items}
-        isLoading={isLoading}
-        label="Pick a Pokemon"
-        placeholder="Select a Pokemon"
-        scrollRef={scrollerRef}
-        variant="bordered"
-        onOpenChange={setIsOpen}
-      >
-        {(item) => (
-          <AutocompleteItem key={item.name} className="capitalize">
-            {item.name}
-          </AutocompleteItem>
-        )}
-      </Autocomplete>
-    </div>
-  );
-}

apps/docs/app/examples/autocomplete/fully-controlled/page.tsx

@@ -1,107 +0,0 @@
-"use client";
-
-import * as React from "react";
-import {Autocomplete, AutocompleteItem, MenuTriggerAction} from "@nextui-org/react";
-import {useFilter} from "@react-aria/i18n";
-
-const animals = [
-  {label: "Cat", value: "cat", description: "The second most popular pet in the world"},
-  {label: "Dog", value: "dog", description: "The most popular pet in the world"},
-  {label: "Elephant", value: "elephant", description: "The largest land animal"},
-  {label: "Lion", value: "lion", description: "The king of the jungle"},
-  {label: "Tiger", value: "tiger", description: "The largest cat species"},
-  {label: "Giraffe", value: "giraffe", description: "The tallest land animal"},
-  {
-    label: "Dolphin",
-    value: "dolphin",
-    description: "A widely distributed and diverse group of aquatic mammals",
-  },
-  {label: "Penguin", value: "penguin", description: "A group of aquatic flightless birds"},
-  {label: "Zebra", value: "zebra", description: "A several species of African equids"},
-  {
-    label: "Shark",
-    value: "shark",
-    description: "A group of elasmobranch fish characterized by a cartilaginous skeleton",
-  },
-  {
-    label: "Whale",
-    value: "whale",
-    description: "Diverse group of fully aquatic placental marine mammals",
-  },
-  {label: "Otter", value: "otter", description: "A carnivorous mammal in the subfamily Lutrinae"},
-  {label: "Crocodile", value: "crocodile", description: "A large semiaquatic reptile"},
-];
-
-type FieldState = {
-  selectedKey: React.Key | null;
-  inputValue: string;
-  items: typeof animals;
-};
-
-export default function Page() {
-  // Store ComboBox input value, selected option, open state, and items
-  // in a state tracker
-  const [fieldState, setFieldState] = React.useState<FieldState>({
-    selectedKey: "",
-    inputValue: "",
-    items: animals,
-  });
-
-  // Implement custom filtering logic and control what items are
-  // available to the Autocomplete.
-  const {startsWith} = useFilter({sensitivity: "base"});
-
-  // Specify how each of the Autocomplete values should change when an
-  // option is selected from the list box
-  const onSelectionChange = (key: React.Key | null) => {
-    setFieldState((prevState) => {
-      let selectedItem = prevState.items.find((option) => option.value === key);
-
-      return {
-        inputValue: selectedItem?.label || "",
-        selectedKey: key,
-        items: animals.filter((item) => startsWith(item.label, selectedItem?.label || "")),
-      };
-    });
-  };
-
-  // Specify how each of the Autocomplete values should change when the input
-  // field is altered by the user
-  const onInputChange = (value: string) => {
-    setFieldState((prevState) => ({
-      inputValue: value,
-      selectedKey: value === "" ? null : prevState.selectedKey,
-      items: animals.filter((item) => startsWith(item.label, value)),
-    }));
-  };
-
-  // Show entire list if user opens the menu manually
-  const onOpenChange = (isOpen: boolean, menuTrigger: MenuTriggerAction) => {
-    if (menuTrigger === "manual" && isOpen) {
-      setFieldState((prevState) => ({
-        inputValue: prevState.inputValue,
-        selectedKey: prevState.selectedKey,
-        items: animals,
-      }));
-    }
-  };
-
-  return (
-    <div className="p-6">
-      <Autocomplete
-        className="max-w-xs"
-        inputValue={fieldState.inputValue}
-        items={fieldState.items}
-        label="Favorite Animal"
-        placeholder="Select an animal"
-        selectedKey={fieldState.selectedKey}
-        variant="bordered"
-        onInputChange={onInputChange}
-        onOpenChange={onOpenChange}
-        onSelectionChange={onSelectionChange}
-      >
-        {(item) => <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>}
-      </Autocomplete>
-    </div>
-  );
-}

apps/docs/app/examples/demo/page.tsx

@@ -1,27 +0,0 @@
-"use client";
-
-import {Card, CardBody, CircularProgress} from "@nextui-org/react";
-
-export default function ButtonDemo() {
-  return (
-    <main className="dark bg-background text-foreground">
-      <div className="flex w-screen h-screen items-center justify-center">
-        <Card className="w-[240px] h-[240px] bg-default-200 dark:bg-default-50">
-          <CardBody className="justify-center items-center py-0">
-            <CircularProgress
-              classNames={{
-                svg: "w-36 h-36 drop-shadow-md",
-                indicator: "stroke-foreground",
-                track: "stroke-foreground/10",
-                value: "text-3xl font-semibold text-foreground",
-              }}
-              showValueLabel={true}
-              strokeWidth={4}
-              value={70}
-            />
-          </CardBody>
-        </Card>
-      </div>
-    </main>
-  );
-}

apps/docs/app/examples/modal/placement/page.tsx

@@ -1,74 +0,0 @@
-"use client";
-
-import {
-  Modal,
-  ModalContent,
-  ModalHeader,
-  ModalBody,
-  ModalFooter,
-  Button,
-  useDisclosure,
-  RadioGroup,
-  Radio,
-  ModalProps,
-} from "@nextui-org/react";
-import {useState} from "react";
-
-export default function Page() {
-  const {isOpen, onOpen, onOpenChange} = useDisclosure();
-  const [modalPlacement, setModalPlacement] = useState("auto");
-
-  return (
-    <div className="flex px-10 min-h-[80vh] justify-center items-center flex-col gap-4">
-      <Button className="max-w-fit" onPress={onOpen}>
-        Open Modal
-      </Button>
-      <RadioGroup
-        label="Select modal placement"
-        orientation="horizontal"
-        value={modalPlacement}
-        onValueChange={setModalPlacement}
-      >
-        <Radio value="auto">auto</Radio>
-        <Radio value="top">top</Radio>
-        <Radio value="bottom">bottom</Radio>
-        <Radio value="center">center</Radio>
-        <Radio value="top-center">top-center</Radio>
-        <Radio value="bottom-center">bottom-center</Radio>
-      </RadioGroup>
-      <Modal
-        isOpen={isOpen}
-        placement={modalPlacement as ModalProps["placement"]}
-        onOpenChange={onOpenChange}
-      >
-        <ModalContent>
-          {(onClose) => (
-            <>
-              <ModalHeader className="flex flex-col gap-1">Modal Title</ModalHeader>
-              <ModalBody>
-                <p>
-                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
-                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
-                  quam.
-                </p>
-                <p>
-                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
-                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
-                  quam.
-                </p>
-              </ModalBody>
-              <ModalFooter>
-                <Button color="danger" variant="light" onClick={onClose}>
-                  Close
-                </Button>
-                <Button color="primary" onPress={onClose}>
-                  Action
-                </Button>
-              </ModalFooter>
-            </>
-          )}
-        </ModalContent>
-      </Modal>
-    </div>
-  );
-}

apps/docs/app/examples/navbar/bordered/page.tsx

@@ -1,62 +0,0 @@
-"use client";
-
-import {
-  Navbar,
-  NavbarBrand,
-  NavbarContent,
-  NavbarItem,
-  Link as NextUiLink,
-  LinkProps,
-  Button,
-} from "@nextui-org/react";
-
-const Link = (props: LinkProps) => <NextUiLink {...props} onClick={(e) => e.preventDefault()} />;
-
-const AcmeLogo = () => (
-  <svg fill="none" height="36" viewBox="0 0 32 32" width="36">
-    <path
-      clipRule="evenodd"
-      d="M17.6482 10.1305L15.8785 7.02583L7.02979 22.5499H10.5278L17.6482 10.1305ZM19.8798 14.0457L18.11 17.1983L19.394 19.4511H16.8453L15.1056 22.5499H24.7272L19.8798 14.0457Z"
-      fill="currentColor"
-      fillRule="evenodd"
-    />
-  </svg>
-);
-
-export default function Page() {
-  return (
-    <Navbar isBordered>
-      <NavbarBrand>
-        <AcmeLogo />
-        <p className="font-bold text-inherit">ACME</p>
-      </NavbarBrand>
-      <NavbarContent className="hidden sm:flex gap-4" justify="center">
-        <NavbarItem>
-          <Link color="foreground" href="#">
-            Features
-          </Link>
-        </NavbarItem>
-        <NavbarItem isActive>
-          <Link aria-current="page" href="#">
-            Customers
-          </Link>
-        </NavbarItem>
-        <NavbarItem>
-          <Link color="foreground" href="#">
-            Integrations
-          </Link>
-        </NavbarItem>
-      </NavbarContent>
-      <NavbarContent justify="end">
-        <NavbarItem className="hidden lg:flex">
-          <Link href="#">Login</Link>
-        </NavbarItem>
-        <NavbarItem>
-          <Button as={Link} color="primary" href="#" variant="flat">
-            Sign Up
-          </Button>
-        </NavbarItem>
-      </NavbarContent>
-    </Navbar>
-  );
-}

apps/docs/app/examples/navbar/controlled-menu/page.tsx

@@ -1,104 +0,0 @@
-"use client";
-
-import {
-  Navbar,
-  NavbarBrand,
-  NavbarContent,
-  NavbarItem,
-  NavbarMenu,
-  NavbarMenuItem,
-  NavbarMenuToggle,
-  Button,
-  Link as NextUiLink,
-  LinkProps,
-} from "@nextui-org/react";
-import React from "react";
-
-const Link = (props: LinkProps) => <NextUiLink {...props} onClick={(e) => e.preventDefault()} />;
-
-const AcmeLogo = () => (
-  <svg fill="none" height="36" viewBox="0 0 32 32" width="36">
-    <path
-      clipRule="evenodd"
-      d="M17.6482 10.1305L15.8785 7.02583L7.02979 22.5499H10.5278L17.6482 10.1305ZM19.8798 14.0457L18.11 17.1983L19.394 19.4511H16.8453L15.1056 22.5499H24.7272L19.8798 14.0457Z"
-      fill="currentColor"
-      fillRule="evenodd"
-    />
-  </svg>
-);
-
-export default function Page() {
-  const [isMenuOpen, setIsMenuOpen] = React.useState<boolean | undefined>(false);
-
-  const menuItems = [
-    "Profile",
-    "Dashboard",
-    "Activity",
-    "Analytics",
-    "System",
-    "Deployments",
-    "My Settings",
-    "Team Settings",
-    "Help & Feedback",
-    "Log Out",
-  ];
-
-  return (
-    <Navbar onMenuOpenChange={setIsMenuOpen}>
-      <NavbarContent>
-        <NavbarMenuToggle
-          aria-label={isMenuOpen ? "Close menu" : "Open menu"}
-          className="sm:hidden"
-        />
-        <NavbarBrand>
-          <AcmeLogo />
-          <p className="font-bold text-inherit">ACME</p>
-        </NavbarBrand>
-      </NavbarContent>
-
-      <NavbarContent className="hidden sm:flex gap-4" justify="center">
-        <NavbarItem>
-          <Link color="foreground" href="#">
-            Features
-          </Link>
-        </NavbarItem>
-        <NavbarItem isActive>
-          <Link aria-current="page" href="#">
-            Customers
-          </Link>
-        </NavbarItem>
-        <NavbarItem>
-          <Link color="foreground" href="#">
-            Integrations
-          </Link>
-        </NavbarItem>
-      </NavbarContent>
-      <NavbarContent justify="end">
-        <NavbarItem className="hidden lg:flex">
-          <Link href="#">Login</Link>
-        </NavbarItem>
-        <NavbarItem>
-          <Button as={Link} color="primary" href="#" variant="flat">
-            Sign Up
-          </Button>
-        </NavbarItem>
-      </NavbarContent>
-      <NavbarMenu>
-        {menuItems.map((item, index) => (
-          <NavbarMenuItem key={`${item}-${index}`}>
-            <Link
-              className="w-full"
-              color={
-                index === 2 ? "primary" : index === menuItems.length - 1 ? "danger" : "foreground"
-              }
-              href="#"
-              size="lg"
-            >
-              {item}
-            </Link>
-          </NavbarMenuItem>
-        ))}
-      </NavbarMenu>
-    </Navbar>
-  );
-}