siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/DropdownItemHeading/README.md

@@ -1,573 +1,573 @@
-# DropdownItemHeading
-
-Componente de encabezado especializado para menús dropdown del sistema de diseño Siesa. Muestra un icono, label principal, descripción opcional y acción opcional con soporte completo para dark mode.
-
-## 📋 Tabla de Contenidos
-
-1. [Descripción](#descripción)
-2. [Especificaciones](#especificaciones)
-3. [Instalación & Uso](#instalación--uso)
-4. [Props](#props)
-5. [Ejemplos](#ejemplos)
-6. [Guía de Componentes Relacionados](#guía-de-componentes-relacionados)
-7. [Mejores Prácticas](#mejores-prácticas)
-8. [Dark Mode](#dark-mode)
-9. [Accesibilidad](#accesibilidad)
-
----
-
-## Descripción
-
-El componente `DropdownItemHeading` es un encabezado especializado para menús dropdown que proporciona una forma consistente de mostrar encabezados con icono, label, descripción y acciones.
-
-### Casos de Uso
-
-- Encabezados de secciones en dropdowns
-- Información de usuario con opciones de acción (Clear, Reset)
-- Configuraciones rápidas en menús
-- Menús contextuales con información descriptiva
-
-### Características Principales
-
-✅ Icono opcional de 16x16px
-✅ Label principal (14px Bold)
-✅ Descripción opcional (12px Regular)
-✅ Acción opcional en la derecha (10px Regular)
-✅ Soporte completo para dark mode
-✅ Focus rings adaptativos
-✅ Tipografía del sistema (Label/Small, Paragraph/Tiny)
-✅ Espaciado consistente (12px gaps)
-✅ Diseño flexible y responsivo
-
----
-
-## Especificaciones
-
-### Dimensiones
-
-| Elemento | Valor |
-|----------|-------|
-| Altura | Flexible (contenido) |
-| Ancho mínimo | 224px / 56 (Tailwind: w-56) |
-| Padding H | 16px (px-4) |
-| Padding V | 8px (py-2) |
-| Border radius | 8px (rounded-lg) |
-
-### Tipografía
-
-| Elemento | Estilo | Tamaño | Peso | Altura de Línea | Color (Light) | Color (Dark) |
-|----------|--------|--------|------|-----------------|---------------|-------------|
-| Label | Label/Small | 14px | Bold (700) | 20px | #18181b | #bfe2fe |
-| Description | Paragraph/Tiny | 12px | Regular (400) | 16px | #a1a1aa | #93d1fd |
-| Action | Paragraph/XXSmall | 10px | Regular (400) | 12px | #a1a1aa | #93d1fd |
-
-### Espaciado
-
-| Elemento | Valor |
-|----------|-------|
-| Gap general (icon-content-action) | 12px (gap-3) |
-| Gap entre label y description | 2px (gap-0.5) |
-| Icon wrapper | 16x16px (w-4 h-4) |
-| Content wrapper | flex-1 (flexible) |
-
-### Icono
-
-| Propiedad | Valor |
-|-----------|-------|
-| Tamaño | 16x16px |
-| Color (Light) | primary-custom-600 (#0e79fd) |
-| Color (Dark) | dark-content-inverse (#bfe2fe) |
-| Icono por defecto | Cog (heroicons/cog-8-tooth) |
-
----
-
-## Instalación & Uso
-
-### Importación
-
-```tsx
-import { DropdownItemHeading } from '@/components/DropdownItemHeading';
-```
-
-### Uso Básico
-
-```tsx
-<DropdownItemHeading
-  label="My Account"
-  description="user@example.com"
-  showDescription={true}
-  showIcon={true}
-  actionLabel="Clear"
-  showAction={true}
-/>
-```
-
----
-
-## Props
-
-### Interface `DropdownItemHeadingProps`
-
-```typescript
-interface DropdownItemHeadingProps {
-  label?: string;
-  description?: string;
-  showDescription?: boolean;
-  icon?: ReactNode;
-  showIcon?: boolean;
-  actionLabel?: string;
-  showAction?: boolean;
-  onActionClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
-  className?: string;
-  [key: string]: unknown;
-}
-```
-
-### Detalle de Props
-
-#### `label`
-- **Tipo**: `string`
-- **Default**: `'Label'`
-- **Descripción**: Texto del label principal
-- **Tipografía**: Label/Small (14px Bold)
-- **Dark Mode**: #18181b (light) → #bfe2fe (dark)
-
-#### `description`
-- **Tipo**: `string`
-- **Default**: `undefined`
-- **Descripción**: Texto de descripción secundaria
-- **Tipografía**: Paragraph/Tiny (12px Regular)
-- **Dark Mode**: #a1a1aa (light) → #93d1fd (dark)
-
-#### `showDescription`
-- **Tipo**: `boolean`
-- **Default**: `true`
-- **Descripción**: Si se debe mostrar la descripción
-
-#### `iconType`
-- **Tipo**: `'cog' | 'custom' | null`
-- **Default**: `'cog'`
-- **Descripción**: Tipo de icono a mostrar
-  - `'cog'`: Icono de engranaje (heroicons-micro/cog-6-tooth)
-  - `'custom'`: Icono personalizado (proporcionar en `icon`)
-  - `null`: Sin icono
-
-#### `icon`
-- **Tipo**: `ReactNode`
-- **Default**: `undefined`
-- **Descripción**: Icono personalizado a mostrar
-- **Solo se usa**: Cuando `iconType` es `'custom'`
-- **Tamaño recomendado**: 16x16px
-
-#### `showIcon`
-- **Tipo**: `boolean`
-- **Default**: `true`
-- **Descripción**: Si se debe mostrar el icono
-
-#### `actionLabel`
-- **Tipo**: `string`
-- **Default**: `undefined`
-- **Descripción**: Texto de la acción (derecha)
-- **Tipografía**: Paragraph/XXSmall (10px Regular)
-- **Ejemplos**: "Clear", "Reset", "Manage"
-
-#### `showAction`
-- **Tipo**: `boolean`
-- **Default**: `false`
-- **Descripción**: Si se debe mostrar la acción
-
-#### `onActionClick`
-- **Tipo**: `(event: React.MouseEvent<HTMLDivElement>) => void`
-- **Default**: `undefined`
-- **Descripción**: Callback ejecutado al hacer click en la acción
-
-#### `className`
-- **Tipo**: `string`
-- **Default**: `''`
-- **Descripción**: Clases CSS adicionales para personalización
-
----
-
-## Ejemplos
-
-### Ejemplo 1: Información de Usuario
-
-```tsx
-<DropdownItemHeading
-  label="John Doe"
-  description="john@example.com"
-  showDescription={true}
-  iconType="cog"
-  showIcon={true}
-  actionLabel="Logout"
-  showAction={true}
-  onActionClick={() => {
-    console.log('User logged out');
-    // Handle logout logic
-  }}
-/>
-```
-
-### Ejemplo 2: Configuración Rápida
-
-```tsx
-<DropdownItemHeading
-  label="Preferences"
-  description="Customize your experience"
-  showDescription={true}
-  iconType="cog"
-  showIcon={true}
-  actionLabel="Reset"
-  showAction={true}
-  onActionClick={handleResetPreferences}
-/>
-```
-
-### Ejemplo 3: Solo Label
-
-```tsx
-<DropdownItemHeading
-  label="Quick Actions"
-  showDescription={false}
-  iconType="cog"
-  showIcon={true}
-/>
-```
-
-### Ejemplo 4: Sin Icono
-
-```tsx
-<DropdownItemHeading
-  label="Recent Searches"
-  description="Last 5 searches"
-  showDescription={true}
-  iconType={null}
-  showIcon={false}
-  actionLabel="Clear"
-  showAction={true}
-  onActionClick={handleClearSearches}
-/>
-```
-
-### Ejemplo 5: Icono Personalizado
-
-```tsx
-import UserIcon from '@/assets/icons/user.svg';
-import { DropdownItemHeading } from '@/components/DropdownItemHeading';
-
-<DropdownItemHeading
-  label="Profile"
-  description="user@example.com"
-  showDescription={true}
-  iconType="custom"
-  icon={<UserIcon className="w-4 h-4" />}
-  showIcon={true}
-  actionLabel="Edit"
-  showAction={true}
-  onActionClick={handleEditProfile}
-/>
-```
-
-### Ejemplo 6: En Contexto de Dropdown
-
-```tsx
-<Dropdown items={[
-  {
-    isHeading: true,
-    children: (
-      <DropdownItemHeading
-        label="My Account"
-        description="user@example.com"
-        iconType="cog"
-        actionLabel="Logout"
-        showAction={true}
-        onActionClick={handleLogout}
-      />
-    ),
-  },
-  { isDivider: true },
-  { children: 'Settings', icon: <SettingsIcon /> },
-  { children: 'Help', icon: <HelpIcon /> },
-]} />
-```
-
----
-
-## Guía de Componentes Relacionados
-
-### Dropdown
-El componente padre que utiliza `DropdownItemHeading` como encabezado de menú.
-
-```tsx
-import { Dropdown, DropdownItemHeading } from '@/components';
-
-<Dropdown items={[
-  {
-    isHeading: true,
-    children: <DropdownItemHeading label="Account" description="user@example.com" />,
-  },
-]} />
-```
-
-### Button
-Componente de botón principal del sistema. Usado en acciones secundarias.
-
-### Badge
-Para mostrar notificaciones o estados junto a la información.
-
----
-
-## Mejores Prácticas
-
-### 1. Mantén Labels Concisos
-```tsx
-// ✅ Bien
-<DropdownItemHeading label="My Account" />
-
-// ❌ Evitar
-<DropdownItemHeading label="Your Current Account Information and Settings" />
-```
-
-### 2. Proporciona Descripción Contextual
-```tsx
-// ✅ Bien
-<DropdownItemHeading
-  label="Settings"
-  description="Manage your preferences"
-/>
-
-// ❌ Evitar
-<DropdownItemHeading
-  label="Settings"
-  description="This is a menu item"
-/>
-```
-
-### 3. Usa Acciones Claras
-```tsx
-// ✅ Bien
-actionLabel="Clear"
-actionLabel="Reset"
-actionLabel="Edit"
-
-// ❌ Evitar
-actionLabel="Go"
-actionLabel="Do Something"
-```
-
-### 4. Maneja Errores en Callbacks
-
-```tsx
-<DropdownItemHeading
-  actionLabel="Delete"
-  onActionClick={async (e) => {
-    try {
-      await deleteItem();
-      console.log('Item deleted');
-    } catch (error) {
-      console.error('Delete failed:', error);
-    }
-  }}
-/>
-```
-
-### 5. Respeta la Jerarquía Visual
-
-```tsx
-// ✅ Bien: Información relevante en descripción
-<DropdownItemHeading
-  label="Documents"
-  description="3 items, 5.2 MB"
-  showDescription={true}
-/>
-
-// ❌ Evitar: Información no importante
-<DropdownItemHeading
-  label="Documents"
-  description="This is a folder location"
-  showDescription={true}
-/>
-```
-
-### 6. Gestiona Textos Largos
-
-```tsx
-// Para textos muy largos, considera truncar en el parent
-<div className="max-w-xs">
-  <DropdownItemHeading
-    label="Very Long Label That Might Overflow"
-    description="Truncated with ellipsis"
-  />
-</div>
-```
-
----
-
-## Dark Mode
-
-El componente tiene soporte completo para dark mode con la estrategia `class` de Tailwind.
-
-### Colores en Dark Mode
-
-```css
-/* Label */
-.dark .dropdown-item-heading {
-  color: #bfe2fe; /* dark-content-inverse */
-}
-
-/* Description & Action */
-.dark .dropdown-item-description,
-.dark .dropdown-item-action {
-  color: #93d1fd; /* dark-border-inverse */
-}
-
-/* Icon */
-.dark .dropdown-item-icon {
-  color: #bfe2fe; /* dark-content-inverse */
-}
-```
-
-### Activar Dark Mode
-
-```tsx
-// En el elemento raíz de tu aplicación
-<div className="dark">
-  <DropdownItemHeading label="Dark mode enabled" />
-</div>
-```
-
----
-
-## Accesibilidad
-
-### ARIA
-
-El componente usa etiquetas semánticas y atributos ARIA:
-
-```tsx
-// Acción con keyboard support
-<div
-  role="button"
-  tabIndex={0}
-  onClick={onActionClick}
-  onKeyDown={(e) => {
-    if (e.key === 'Enter' || e.key === ' ') {
-      onActionClick?.(e as any);
-    }
-  }}
->
-  {actionLabel}
-</div>
-```
-
-### Keyboard Navigation
-
-- **Tab**: Navega a la acción (si está visible)
-- **Enter / Space**: Activa la acción
-- **Escape**: Cierra el dropdown parent (manejo en Dropdown)
-
-### Screen Readers
-
-```tsx
-// Íconos son hidden para screen readers
-<svg className="w-4 h-4" aria-hidden="true">
-  {/* ... */}
-</svg>
-
-// Acciones tienen soporte de keyboard
-<div role="button" tabIndex={0}>
-  Clear
-</div>
-```
-
-### Colores y Contraste
-
-- **Light Mode**: WCAG AAA compliant
-- **Dark Mode**: WCAG AAA compliant
-- Ratio de contraste mínimo: 4.5:1 para texto normal
-- Ratio de contraste mínimo: 3:1 para texto grande
-
----
-
-## Especificaciones de Figma
-
-**Figma Node**: `6135:32539`
-**Figma File**: [Siesa UI Kit - DropdownItemHeading](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-32539)
-
-### Componentes Relacionados en Figma
-
-- **Dropdown Item**: `6135:32529`
-- **Dropdown**: `6135:31234`
-- **Button**: `4001:17240`
-
----
-
-## Troubleshooting
-
-### El texto se corta sin mostrar ellipsis
-
-Asegúrate de que el contenedor padre tenga un ancho definido:
-
-```tsx
-// ✅ Bien
-<div className="w-56">
-  <DropdownItemHeading label="Long label" />
-</div>
-
-// ❌ Evitar
-<DropdownItemHeading label="Long label" />
-```
-
-### El icono no se muestra en dark mode
-
-Verifica que el icono heredar colores correctamente:
-
-```tsx
-// ✅ Bien
-<MyIcon className="text-primary-custom-600 dark:text-dark-content-inverse" />
-
-// ❌ Evitar
-<MyIcon style={{ color: '#0e79fd' }} />
-```
-
-### La acción no responde al click
-
-Asegúrate de proporcionar el callback:
-
-```tsx
-<DropdownItemHeading
-  showAction={true}
-  actionLabel="Clear"
-  onActionClick={(e) => {
-    console.log('Action clicked');
-    // Handle action
-  }}
-/>
-```
-
----
-
-## Referencia de Documentación del Sistema
-
-- [Sistema de Colores](../../../docs/colors.md)
-- [Sistema de Tipografía](../../../docs/typography.md)
-- [Sistema de Espaciado](../../../docs/spacing.md)
-- [Sistema de Sombras](../../../docs/shadows.md)
-
----
-
-## Cambios Recientes
-
-### v1.0.0 (Inicial)
-- ✨ Componente inicial creado
-- ✅ Soporte completo para dark mode
-- ✅ Props opcionales para mostrar/ocultar elementos
-- ✅ Callback de acción
-- ✅ Typografía del sistema
-- ✅ Accesibilidad mejorada
-
----
-
-## Licencia
-
-Part of Siesa UI Kit - Todos los derechos reservados © Siesa 2024
+# DropdownItemHeading
+
+Componente de encabezado especializado para menús dropdown del sistema de diseño Siesa. Muestra un icono, label principal, descripción opcional y acción opcional con soporte completo para dark mode.
+
+## 📋 Tabla de Contenidos
+
+1. [Descripción](#descripción)
+2. [Especificaciones](#especificaciones)
+3. [Instalación & Uso](#instalación--uso)
+4. [Props](#props)
+5. [Ejemplos](#ejemplos)
+6. [Guía de Componentes Relacionados](#guía-de-componentes-relacionados)
+7. [Mejores Prácticas](#mejores-prácticas)
+8. [Dark Mode](#dark-mode)
+9. [Accesibilidad](#accesibilidad)
+
+---
+
+## Descripción
+
+El componente `DropdownItemHeading` es un encabezado especializado para menús dropdown que proporciona una forma consistente de mostrar encabezados con icono, label, descripción y acciones.
+
+### Casos de Uso
+
+- Encabezados de secciones en dropdowns
+- Información de usuario con opciones de acción (Clear, Reset)
+- Configuraciones rápidas en menús
+- Menús contextuales con información descriptiva
+
+### Características Principales
+
+✅ Icono opcional de 16x16px
+✅ Label principal (14px Bold)
+✅ Descripción opcional (12px Regular)
+✅ Acción opcional en la derecha (10px Regular)
+✅ Soporte completo para dark mode
+✅ Focus rings adaptativos
+✅ Tipografía del sistema (Label/Small, Paragraph/Tiny)
+✅ Espaciado consistente (12px gaps)
+✅ Diseño flexible y responsivo
+
+---
+
+## Especificaciones
+
+### Dimensiones
+
+| Elemento | Valor |
+|----------|-------|
+| Altura | Flexible (contenido) |
+| Ancho mínimo | 224px / 56 (Tailwind: w-56) |
+| Padding H | 16px (px-4) |
+| Padding V | 8px (py-2) |
+| Border radius | 8px (rounded-lg) |
+
+### Tipografía
+
+| Elemento | Estilo | Tamaño | Peso | Altura de Línea | Color (Light) | Color (Dark) |
+|----------|--------|--------|------|-----------------|---------------|-------------|
+| Label | Label/Small | 14px | Bold (700) | 20px | #18181b | #bfe2fe |
+| Description | Paragraph/Tiny | 12px | Regular (400) | 16px | #a1a1aa | #93d1fd |
+| Action | Paragraph/XXSmall | 10px | Regular (400) | 12px | #a1a1aa | #93d1fd |
+
+### Espaciado
+
+| Elemento | Valor |
+|----------|-------|
+| Gap general (icon-content-action) | 12px (gap-3) |
+| Gap entre label y description | 2px (gap-0.5) |
+| Icon wrapper | 16x16px (w-4 h-4) |
+| Content wrapper | flex-1 (flexible) |
+
+### Icono
+
+| Propiedad | Valor |
+|-----------|-------|
+| Tamaño | 16x16px |
+| Color (Light) | primary-custom-600 (#0e79fd) |
+| Color (Dark) | dark-content-inverse (#bfe2fe) |
+| Icono por defecto | Cog (heroicons/cog-8-tooth) |
+
+---
+
+## Instalación & Uso
+
+### Importación
+
+```tsx
+import { DropdownItemHeading } from '@/components/DropdownItemHeading';
+```
+
+### Uso Básico
+
+```tsx
+<DropdownItemHeading
+  label="My Account"
+  description="user@example.com"
+  showDescription={true}
+  showIcon={true}
+  actionLabel="Clear"
+  showAction={true}
+/>
+```
+
+---
+
+## Props
+
+### Interface `DropdownItemHeadingProps`
+
+```typescript
+interface DropdownItemHeadingProps {
+  label?: string;
+  description?: string;
+  showDescription?: boolean;
+  icon?: ReactNode;
+  showIcon?: boolean;
+  actionLabel?: string;
+  showAction?: boolean;
+  onActionClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+  className?: string;
+  [key: string]: unknown;
+}
+```
+
+### Detalle de Props
+
+#### `label`
+- **Tipo**: `string`
+- **Default**: `'Label'`
+- **Descripción**: Texto del label principal
+- **Tipografía**: Label/Small (14px Bold)
+- **Dark Mode**: #18181b (light) → #bfe2fe (dark)
+
+#### `description`
+- **Tipo**: `string`
+- **Default**: `undefined`
+- **Descripción**: Texto de descripción secundaria
+- **Tipografía**: Paragraph/Tiny (12px Regular)
+- **Dark Mode**: #a1a1aa (light) → #93d1fd (dark)
+
+#### `showDescription`
+- **Tipo**: `boolean`
+- **Default**: `true`
+- **Descripción**: Si se debe mostrar la descripción
+
+#### `iconType`
+- **Tipo**: `'cog' | 'custom' | null`
+- **Default**: `'cog'`
+- **Descripción**: Tipo de icono a mostrar
+  - `'cog'`: Icono de engranaje (heroicons-micro/cog-6-tooth)
+  - `'custom'`: Icono personalizado (proporcionar en `icon`)
+  - `null`: Sin icono
+
+#### `icon`
+- **Tipo**: `ReactNode`
+- **Default**: `undefined`
+- **Descripción**: Icono personalizado a mostrar
+- **Solo se usa**: Cuando `iconType` es `'custom'`
+- **Tamaño recomendado**: 16x16px
+
+#### `showIcon`
+- **Tipo**: `boolean`
+- **Default**: `true`
+- **Descripción**: Si se debe mostrar el icono
+
+#### `actionLabel`
+- **Tipo**: `string`
+- **Default**: `undefined`
+- **Descripción**: Texto de la acción (derecha)
+- **Tipografía**: Paragraph/XXSmall (10px Regular)
+- **Ejemplos**: "Clear", "Reset", "Manage"
+
+#### `showAction`
+- **Tipo**: `boolean`
+- **Default**: `false`
+- **Descripción**: Si se debe mostrar la acción
+
+#### `onActionClick`
+- **Tipo**: `(event: React.MouseEvent<HTMLDivElement>) => void`
+- **Default**: `undefined`
+- **Descripción**: Callback ejecutado al hacer click en la acción
+
+#### `className`
+- **Tipo**: `string`
+- **Default**: `''`
+- **Descripción**: Clases CSS adicionales para personalización
+
+---
+
+## Ejemplos
+
+### Ejemplo 1: Información de Usuario
+
+```tsx
+<DropdownItemHeading
+  label="John Doe"
+  description="john@example.com"
+  showDescription={true}
+  iconType="cog"
+  showIcon={true}
+  actionLabel="Logout"
+  showAction={true}
+  onActionClick={() => {
+    console.log('User logged out');
+    // Handle logout logic
+  }}
+/>
+```
+
+### Ejemplo 2: Configuración Rápida
+
+```tsx
+<DropdownItemHeading
+  label="Preferences"
+  description="Customize your experience"
+  showDescription={true}
+  iconType="cog"
+  showIcon={true}
+  actionLabel="Reset"
+  showAction={true}
+  onActionClick={handleResetPreferences}
+/>
+```
+
+### Ejemplo 3: Solo Label
+
+```tsx
+<DropdownItemHeading
+  label="Quick Actions"
+  showDescription={false}
+  iconType="cog"
+  showIcon={true}
+/>
+```
+
+### Ejemplo 4: Sin Icono
+
+```tsx
+<DropdownItemHeading
+  label="Recent Searches"
+  description="Last 5 searches"
+  showDescription={true}
+  iconType={null}
+  showIcon={false}
+  actionLabel="Clear"
+  showAction={true}
+  onActionClick={handleClearSearches}
+/>
+```
+
+### Ejemplo 5: Icono Personalizado
+
+```tsx
+import UserIcon from '@/assets/icons/user.svg';
+import { DropdownItemHeading } from '@/components/DropdownItemHeading';
+
+<DropdownItemHeading
+  label="Profile"
+  description="user@example.com"
+  showDescription={true}
+  iconType="custom"
+  icon={<UserIcon className="w-4 h-4" />}
+  showIcon={true}
+  actionLabel="Edit"
+  showAction={true}
+  onActionClick={handleEditProfile}
+/>
+```
+
+### Ejemplo 6: En Contexto de Dropdown
+
+```tsx
+<Dropdown items={[
+  {
+    isHeading: true,
+    children: (
+      <DropdownItemHeading
+        label="My Account"
+        description="user@example.com"
+        iconType="cog"
+        actionLabel="Logout"
+        showAction={true}
+        onActionClick={handleLogout}
+      />
+    ),
+  },
+  { isDivider: true },
+  { children: 'Settings', icon: <SettingsIcon /> },
+  { children: 'Help', icon: <HelpIcon /> },
+]} />
+```
+
+---
+
+## Guía de Componentes Relacionados
+
+### Dropdown
+El componente padre que utiliza `DropdownItemHeading` como encabezado de menú.
+
+```tsx
+import { Dropdown, DropdownItemHeading } from '@/components';
+
+<Dropdown items={[
+  {
+    isHeading: true,
+    children: <DropdownItemHeading label="Account" description="user@example.com" />,
+  },
+]} />
+```
+
+### Button
+Componente de botón principal del sistema. Usado en acciones secundarias.
+
+### Badge
+Para mostrar notificaciones o estados junto a la información.
+
+---
+
+## Mejores Prácticas
+
+### 1. Mantén Labels Concisos
+```tsx
+// ✅ Bien
+<DropdownItemHeading label="My Account" />
+
+// ❌ Evitar
+<DropdownItemHeading label="Your Current Account Information and Settings" />
+```
+
+### 2. Proporciona Descripción Contextual
+```tsx
+// ✅ Bien
+<DropdownItemHeading
+  label="Settings"
+  description="Manage your preferences"
+/>
+
+// ❌ Evitar
+<DropdownItemHeading
+  label="Settings"
+  description="This is a menu item"
+/>
+```
+
+### 3. Usa Acciones Claras
+```tsx
+// ✅ Bien
+actionLabel="Clear"
+actionLabel="Reset"
+actionLabel="Edit"
+
+// ❌ Evitar
+actionLabel="Go"
+actionLabel="Do Something"
+```
+
+### 4. Maneja Errores en Callbacks
+
+```tsx
+<DropdownItemHeading
+  actionLabel="Delete"
+  onActionClick={async (e) => {
+    try {
+      await deleteItem();
+      console.log('Item deleted');
+    } catch (error) {
+      console.error('Delete failed:', error);
+    }
+  }}
+/>
+```
+
+### 5. Respeta la Jerarquía Visual
+
+```tsx
+// ✅ Bien: Información relevante en descripción
+<DropdownItemHeading
+  label="Documents"
+  description="3 items, 5.2 MB"
+  showDescription={true}
+/>
+
+// ❌ Evitar: Información no importante
+<DropdownItemHeading
+  label="Documents"
+  description="This is a folder location"
+  showDescription={true}
+/>
+```
+
+### 6. Gestiona Textos Largos
+
+```tsx
+// Para textos muy largos, considera truncar en el parent
+<div className="max-w-xs">
+  <DropdownItemHeading
+    label="Very Long Label That Might Overflow"
+    description="Truncated with ellipsis"
+  />
+</div>
+```
+
+---
+
+## Dark Mode
+
+El componente tiene soporte completo para dark mode con la estrategia `class` de Tailwind.
+
+### Colores en Dark Mode
+
+```css
+/* Label */
+.dark .dropdown-item-heading {
+  color: #bfe2fe; /* dark-content-inverse */
+}
+
+/* Description & Action */
+.dark .dropdown-item-description,
+.dark .dropdown-item-action {
+  color: #93d1fd; /* dark-border-inverse */
+}
+
+/* Icon */
+.dark .dropdown-item-icon {
+  color: #bfe2fe; /* dark-content-inverse */
+}
+```
+
+### Activar Dark Mode
+
+```tsx
+// En el elemento raíz de tu aplicación
+<div className="dark">
+  <DropdownItemHeading label="Dark mode enabled" />
+</div>
+```
+
+---
+
+## Accesibilidad
+
+### ARIA
+
+El componente usa etiquetas semánticas y atributos ARIA:
+
+```tsx
+// Acción con keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={onActionClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      onActionClick?.(e as any);
+    }
+  }}
+>
+  {actionLabel}
+</div>
+```
+
+### Keyboard Navigation
+
+- **Tab**: Navega a la acción (si está visible)
+- **Enter / Space**: Activa la acción
+- **Escape**: Cierra el dropdown parent (manejo en Dropdown)
+
+### Screen Readers
+
+```tsx
+// Íconos son hidden para screen readers
+<svg className="w-4 h-4" aria-hidden="true">
+  {/* ... */}
+</svg>
+
+// Acciones tienen soporte de keyboard
+<div role="button" tabIndex={0}>
+  Clear
+</div>
+```
+
+### Colores y Contraste
+
+- **Light Mode**: WCAG AAA compliant
+- **Dark Mode**: WCAG AAA compliant
+- Ratio de contraste mínimo: 4.5:1 para texto normal
+- Ratio de contraste mínimo: 3:1 para texto grande
+
+---
+
+## Especificaciones de Figma
+
+**Figma Node**: `6135:32539`
+**Figma File**: [Siesa UI Kit - DropdownItemHeading](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-32539)
+
+### Componentes Relacionados en Figma
+
+- **Dropdown Item**: `6135:32529`
+- **Dropdown**: `6135:31234`
+- **Button**: `4001:17240`
+
+---
+
+## Troubleshooting
+
+### El texto se corta sin mostrar ellipsis
+
+Asegúrate de que el contenedor padre tenga un ancho definido:
+
+```tsx
+// ✅ Bien
+<div className="w-56">
+  <DropdownItemHeading label="Long label" />
+</div>
+
+// ❌ Evitar
+<DropdownItemHeading label="Long label" />
+```
+
+### El icono no se muestra en dark mode
+
+Verifica que el icono heredar colores correctamente:
+
+```tsx
+// ✅ Bien
+<MyIcon className="text-primary-custom-600 dark:text-dark-content-inverse" />
+
+// ❌ Evitar
+<MyIcon style={{ color: '#0e79fd' }} />
+```
+
+### La acción no responde al click
+
+Asegúrate de proporcionar el callback:
+
+```tsx
+<DropdownItemHeading
+  showAction={true}
+  actionLabel="Clear"
+  onActionClick={(e) => {
+    console.log('Action clicked');
+    // Handle action
+  }}
+/>
+```
+
+---
+
+## Referencia de Documentación del Sistema
+
+- [Sistema de Colores](../../../docs/colors.md)
+- [Sistema de Tipografía](../../../docs/typography.md)
+- [Sistema de Espaciado](../../../docs/spacing.md)
+- [Sistema de Sombras](../../../docs/shadows.md)
+
+---
+
+## Cambios Recientes
+
+### v1.0.0 (Inicial)
+- ✨ Componente inicial creado
+- ✅ Soporte completo para dark mode
+- ✅ Props opcionales para mostrar/ocultar elementos
+- ✅ Callback de acción
+- ✅ Typografía del sistema
+- ✅ Accesibilidad mejorada
+
+---
+
+## Licencia
+
+Part of Siesa UI Kit - Todos los derechos reservados © Siesa 2024