V3 Redesign

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