V3 Redesign (#5851)

* fix(docs): update Link component to use Link.Root for consistency with new component structure

* feat: light theme in progress, button, spearator & accordion adjusted to new default theme

* feat: button and chip done

* feat: enhance Skeleton component with new Grid and Single Shimmer previews; update card and disclosure styles for consistency

* feat: update Kbd component styles and add Abbr support in stories

* feat: avatar and chip updated

* fix(accordion): adjust separator styling for consistency in accordion items

* refactor: close button adjsuted

* feat(link): add underline variants and offset options to Link component documentation and implementation

* feat(link): enhance link component with hover state and transition effects for icon opacity

* refactor: surfaces variables are now calculated by default, card, button, disclosures updated

* refactor: update styles for various components to improve consistency and reduce motion effects

* feat(storybook): add welcome story and update story order; feat(styles): include variants in package config and copy script

* refactor: update accordion, card, and kbd components to enhance styling and introduce new variants

* refactor(link): update hover underline effect to use opacity transition instead of scale transformation

* refactor(styles): update background color variables and remove gradient backgrounds from layout components

* refactor(storybook): enhance color stories by adding calculated color variants and removing deprecated soft colors

* refactor(styles): introduce background quaternary color and update shadow variables for popover and tooltip components

* feat: alert component created

* refactor(alert-demo, x-profile-demo): simplify button usage and enhance layout alignment

* feat: input otp

* feat: inpuit otp docs

* refactor(switch): enhance styling with improved transition timings and add box-shadow for active states

* feat: home page design in progress

* feat: add Surface component with context-based on-surface styling

- Add Surface component with four variants (default, secondary, tertiary, quaternary)
- Implement SurfaceContext to provide variant to child components
- Update Input, TextArea, InputOTP, and RadioGroup to automatically detect Surface context
- Components now apply on-surface styling when wrapped in Surface component
- Add OnSurface stories for all affected components
- Create comprehensive Surface documentation with examples
- Add OnSurface demo examples to all component documentation pages
- Update CSS classes to support on-surface modifier variants

* feat: add Surface component documentation and update meta.json

* feat(card): implement form handling in WithForm story using Form, Input, and Label components

* feat(card): refactor WithForm to use Form component for improved form handling and submission

* refactor(accordion): remove background class from stories and enhance AccordionRoot with SurfaceContext for elevated variant

* refactor(accordion): update variant from elevated to surface across components and documentation

* feat: add checkbox-group component and checkbox enhancements

* feat(demo): add UIComponentsDemo to the DemoComponents

* refactor: migrate Component.Root to Component in docs and demos

- Update all component documentation files to use Component instead of Component.Root
- Update all demo files to use simplified component syntax
- Update API reference headers from Component.Root Props to Component Props
- Exclude changelog files from migration as requested

This change promotes the simpler and more elegant Component syntax while
maintaining backward compatibility (both patterns are still supported).

* style: update global styles and card component

* feat(storybook): enhance color stories with new "On Surface" color variants and remove obsolete field color states

* feat(demos): update chip component props from 'type' to 'color' and add "use client" directive in multiple demo files

* feat(demos): add "use client" directive to basic button demo

* refactor: theme variables update background color in dark mode

* feat(demos): add "use client" directive to multiple demo files

* feat(demos): add FieldError component to TextfieldDemo for improved validation feedback

* fix(demo): update avatar images and names in avatar-group-demo for consistency

* feat: listbox component preview created and documented

* feat: selecte component created

* feat: export React Aria components from rac module

* feat: slider component created, documentation styles and content updated. Home page completed

* fix(demo): correct spelling of "credits" in AlertDemo component

* refactor(docs): simplify component usage by using compound pattern (#5870)

* fix(component): checkbox build errors

* refactor(docs): simplify component usage by using compound pattern

* fix(component): checkbox build errors

* chore(docs): correct pattern description

* feat(docs): enhance component preview with intersection observer for lazy loading

* feat(docs): enhance code block styling and functionality with isolated rendering option

* chore(root): upgrade package manager

* fix(docs): update image sources and enhance styling across various components

---------

Co-authored-by: Tianen Pang <[email protected]>

Author: jrgarciadev

.claude/agents/tailwind-v4-css-expert.md

@@ -52,7 +52,7 @@ You communicate technical concepts clearly and can assist both human developers
 
    ```css
    /* Good */
-   @apply bg-panel rounded-lg border p-4 shadow-md;
+   @apply bg-surface rounded-lg border p-4 shadow-md;
    ```
 
 2. **Keep custom CSS properties**: Don't convert properties without Tailwind utilities

.claude/guides/tailwindcss-v4-css-guide.md

@@ -343,7 +343,7 @@ Tailwind CSS v4 embraces CSS custom properties for theming and dynamic values:
    ```css
    .component {
      /* Good: Use @apply for Tailwind utilities */
-     @apply bg-panel rounded-lg border p-4 shadow-md;
+     @apply bg-surface rounded-lg border p-4 shadow-md;
 
      /* Keep custom CSS for non-utility properties */
      cursor: var(--cursor-interactive);

apps/docs/content/docs/components/accordion.mdx

@@ -1,7 +1,6 @@
 ---
 title: Accordion
 description: A collapsible content panel for organizing information in a compact space
-icon: updated
 links:
   rac: Disclosure
   source: accordion/accordion.tsx
@@ -31,7 +30,7 @@ Import the Accordion component and access all parts using dot notation.
 import { Accordion } from '@heroui/react';
 
 export default () => (
-  <Accordion.Root>
+  <Accordion>
     <Accordion.Item>
       <Accordion.Heading>
         <Accordion.Trigger>
@@ -42,7 +41,7 @@ export default () => (
         <Accordion.Body/>
       </Accordion.Panel>
     </Accordion.Item>
-  </Accordion.Root>
+  </Accordion>
 )
 ```
 
@@ -120,7 +119,7 @@ const items = [
 
 export function CustomStyles() {
   return (
-    <Accordion.Root className="bg-surface-1 w-full max-w-md rounded-2xl" variant="outline">
+    <Accordion className="bg-surface-secondary w-full max-w-md rounded-2xl" variant="surface">
       {items.map((item, index) => (
         <Accordion.Item
           key={index}
@@ -131,7 +130,7 @@ export function CustomStyles() {
           )}
         >
           <Accordion.Heading>
-            <Accordion.Trigger className="hover:bg-surface-2 group flex items-center gap-2">
+            <Accordion.Trigger className="hover:bg-surface-tertiary group flex items-center gap-2">
               {item.iconUrl ? (
                 <img
                   alt={item.title}
@@ -153,7 +152,7 @@ export function CustomStyles() {
           </Accordion.Panel>
         </Accordion.Item>
       ))}
-    </Accordion.Root>
+    </Accordion>
   );
 }`} />
 
@@ -211,7 +210,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 
 ## API Reference
 
-### Accordion.Root Props
+### Accordion Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -220,7 +219,7 @@ The component supports both CSS pseudo-classes and data attributes for flexibili
 | `expandedKeys` | `Iterable<Key>` | - | The controlled expanded keys |
 | `onExpandedChange` | `(keys: Set<Key>) => void` | - | Handler called when expanded keys change |
 | `isDisabled` | `boolean` | `false` | Whether the entire accordion is disabled |
-| `variant` | `"default" \| "outline"` | `"default"` | The visual variant of the accordion |
+| `variant` | `"default" \| "surface"` | `"default"` | The visual variant of the accordion |
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `ReactNode` | - | The accordion items |
 

apps/docs/content/docs/components/alert.mdx

@@ -0,0 +1,153 @@
+---
+title: Alert
+description: Display important messages and notifications to users with status indicators
+icon: new
+links:
+  source: alert/alert.tsx
+  styles: alert.css
+  storybook: alert
+  figma: true
+---
+
+## Import
+
+```tsx
+import { Alert } from '@heroui/react';
+```
+
+### Usage
+
+<ComponentPreview
+  name="alert-basic"
+/>
+
+
+### Anatomy
+
+Import the Alert component and access all parts using dot notation.
+
+```tsx
+import { Alert } from '@heroui/react';
+
+export default () => (
+  <Alert>
+    <Alert.Indicator />
+    <Alert.Content>
+      <Alert.Title />
+      <Alert.Description />
+    </Alert.Content>
+  </Alert>
+)
+```
+
+<RelatedComponents component="alert" />
+
+## Styling
+
+### Passing Tailwind CSS classes
+
+```tsx
+import { Alert } from "@heroui/react";
+
+function CustomAlert() {
+  return (
+    <Alert className="border-2 border-blue-500 rounded-xl" status="accent">
+      <Alert.Indicator className="text-blue-600" />
+      <Alert.Content className="gap-1">
+        <Alert.Title className="font-bold text-lg">Custom Alert</Alert.Title>
+        <Alert.Description className="text-sm opacity-80">
+          This alert has custom styling applied
+        </Alert.Description>
+      </Alert.Content>
+    </Alert>
+  );
+}
+```
+
+### Customizing the component classes
+
+To customize the Alert component classes, you can use the `@layer components` directive.
+<br/>[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
+
+```css
+@layer components {
+  .alert {
+    @apply rounded-2xl shadow-lg;
+  }
+
+  .alert__title {
+    @apply font-bold text-lg;
+  }
+
+  .alert--danger {
+    @apply border-l-4 border-red-600;
+  }
+}
+```
+
+HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
+
+### CSS Classes
+
+The Alert component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)):
+
+#### Base Classes
+- `.alert` - Base alert container
+- `.alert__indicator` - Icon/indicator container
+- `.alert__content` - Content wrapper for title and description
+- `.alert__title` - Alert title text
+- `.alert__description` - Alert description text
+
+#### Status Variant Classes
+- `.alert--default` - Default gray status
+- `.alert--accent` - Accent blue status
+- `.alert--success` - Success green status
+- `.alert--warning` - Warning yellow/orange status
+- `.alert--danger` - Danger red status
+
+### Interactive States
+
+The Alert component is primarily informational and doesn't have interactive states on the base component. However, it can contain interactive elements like buttons or close buttons.
+
+## API Reference
+
+### Alert Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | The visual status of the alert |
+| `asChild` | `boolean` | `false` | Merge props onto the child element |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The alert content |
+
+### Alert.Indicator Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `asChild` | `boolean` | `false` | Merge props onto the child element |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Custom indicator icon (defaults to status icon) |
+
+### Alert.Content Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `asChild` | `boolean` | `false` | Merge props onto the child element |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | Content (typically Title and Description) |
+
+### Alert.Title Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `asChild` | `boolean` | `false` | Merge props onto the child element |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The alert title text |
+
+### Alert.Description Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `asChild` | `boolean` | `false` | Merge props onto the child element |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `ReactNode` | - | The alert description text |

apps/docs/content/docs/components/avatar.mdx

@@ -1,7 +1,6 @@
 ---
 title: Avatar
 description: Display user profile images with customizable fallback content
-icon: updated
 links:
   radix: avatar
   source: avatar/avatar.tsx
@@ -28,10 +27,10 @@ Import the Avatar component and access all parts using dot notation.
 import { Avatar } from '@heroui/react';
 
 export default () => (
-  <Avatar.Root>
+  <Avatar>
     <Avatar.Image/>
     <Avatar.Fallback/>
-  </Avatar.Root>
+  </Avatar>
 )
 ```
 
@@ -43,6 +42,10 @@ export default () => (
 
 <ComponentPreview name="avatar-colors" />
 
+### Variants
+
+<ComponentPreview name="avatar-variants" />
+
 ### Fallback Content
 
 <ComponentPreview name="avatar-fallback" />
@@ -64,10 +67,10 @@ import { Avatar } from '@heroui/react';
 
 function CustomAvatar() {
   return (
-    <Avatar.Root className="size-20">
+    <Avatar className="size-20">
       <Avatar.Image src="..." alt="..." />
       <Avatar.Fallback>XL</Avatar.Fallback>
-    </Avatar.Root>
+    </Avatar>
   );
 }
 ```
@@ -105,6 +108,9 @@ The Avatar component uses these CSS classes ([View source styles](https://github
 - `.avatar--md` - Medium avatar (default, no additional styles)
 - `.avatar--lg` - Large avatar (size-12)
 
+#### Variant Modifiers
+- `.avatar--soft` - Soft variant with lighter background
+
 #### Color Modifiers
 - `.avatar__fallback--default` - Default text color
 - `.avatar__fallback--accent` - Accent text color
@@ -114,12 +120,13 @@ The Avatar component uses these CSS classes ([View source styles](https://github
 
 ## API Reference
 
-### Avatar.Root Props
+### Avatar Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size |
 | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback color theme |
+| `variant` | `'default' \| 'soft'` | `'default'` | Visual style variant |
 | `className` | `string` | - | Additional CSS classes |
 | `asChild` | `boolean` | `false` | Render as child element |