@axzydev/axzy_ui_system 1.2.6 → 1.2.8

package/src/components/navbar/navbar.tsx

@@ -3,7 +3,35 @@ import { useRef, useState } from "react";
 import { FaChevronDown, FaChevronRight, FaUserCircle } from "react-icons/fa";
 import { ITNavbarProps, ITNavigationItem } from "./navbar.props";
 import ITText from "@/components/text/text";
+import { theme } from "@/theme/theme";
 
+/**
+ * Full sidebar navigation shell with collapsible submenus, user menu dropdown, and themed styling.
+ *
+ * @example
+ * ```tsx
+ * <ITNavbar
+ *   logo={<LogoIcon />}
+ *   logoText="My App"
+ *   navigationItems={[
+ *     { id: 'home', label: 'Home', icon: <FaHome />, isActive: true },
+ *     {
+ *       id: 'settings',
+ *       label: 'Settings',
+ *       icon: <FaCog />,
+ *       subitems: [{ id: 'profile', label: 'Profile', action: () => {} }],
+ *     },
+ *   ]}
+ *   userMenu={{
+ *     userName: 'John Doe',
+ *     userEmail: 'john@example.com',
+ *     menuItems: [{ label: 'Logout', onClick: () => {} }],
+ *   }}
+ * >
+ *   <ITPage title="Dashboard">...</ITPage>
+ * </ITNavbar>
+ * ```
+ */
 export default function ITNavbar({
   logo,
   logoText,
@@ -139,15 +167,21 @@ export default function ITNavbar({
   }
 
   // New sidebar design
+  const sidebar = theme.sidebar;
+  const topbar = theme.topbar;
+
   return (
-    <div className="flex h-screen font-sans" style={{ backgroundColor: "var(--layout-bg, #f8fafc)" }}>
+    <div className="flex h-screen font-sans" style={{ backgroundColor: theme.layout.backgroundColor }}>
       {/* Sidebar */}
-      <aside className="w-72 shadow-xl flex flex-col transition-all duration-300 ease-in-out" style={{ backgroundColor: "var(--sidebar-bg, #0f172a)", borderRight: "1px solid var(--sidebar-border, #1e293b)" }}>
+      <aside
+        className="w-72 shadow-xl flex flex-col transition-all duration-300 ease-in-out"
+        style={{ backgroundColor: sidebar.backgroundColor, borderRight: `1px solid ${sidebar.borderColor}` }}
+      >
         {/* Logo Section */}
-        <div className="p-6 flex items-center gap-3" style={{ borderBottom: "1px solid var(--sidebar-border, #1e293b)" }}>
+        <div className="p-6 flex items-center gap-3" style={{ borderBottom: `1px solid ${sidebar.borderColor}` }}>
           {logo && <div className="h-8 w-auto object-contain transition-transform hover:scale-105">{logo}</div>}
           {logoText && (
-            <ITText as="span" className="text-lg font-bold tracking-wide" style={{ color: "var(--sidebar-active-color, #ffffff)" }}>
+            <ITText as="span" className="text-lg font-bold tracking-wide" style={{ color: sidebar.active.color }}>
               {logoText}
             </ITText>
           )}
@@ -160,46 +194,42 @@ export default function ITNavbar({
               <li key={item.id}>
                 <div
                   className={`group flex items-center justify-between px-4 py-3 rounded-xl cursor-pointer transition-all duration-200 border-l-4 ${
-                    item.isActive 
-                      ? 'shadow-sm' 
+                    item.isActive
+                      ? 'shadow-sm'
                       : 'hover:shadow-sm'
                   }`}
                   onClick={() => handleItemClick(item)}
                   style={{
-                    backgroundColor: item.isActive ? "var(--sidebar-active-bg, rgba(255,255,255,0.1))" : "transparent",
-                    borderColor: item.isActive ? "var(--sidebar-active-icon, #3b82f6)" : "transparent",
-                    color: item.isActive ? "var(--sidebar-active-color, #ffffff)" : "var(--sidebar-label-color, #94a3b8)"
+                    backgroundColor: item.isActive ? sidebar.active.backgroundColor : "transparent",
+                    borderColor: item.isActive ? sidebar.active.iconColor : "transparent",
+                    color: item.isActive ? sidebar.active.color : sidebar.label.color
                   }}
                   onMouseEnter={(e) => {
                     if (!item.isActive) {
-                      e.currentTarget.style.backgroundColor = "var(--sidebar-hover-bg, rgba(255,255,255,0.05))";
-                      e.currentTarget.style.color = "var(--sidebar-active-color, #ffffff)";
+                      e.currentTarget.style.backgroundColor = sidebar.hover.backgroundColor;
+                      e.currentTarget.style.color = sidebar.active.color;
                     }
                   }}
                   onMouseLeave={(e) => {
                     if (!item.isActive) {
                       e.currentTarget.style.backgroundColor = "transparent";
-                      e.currentTarget.style.color = "var(--sidebar-label-color, #94a3b8)";
+                      e.currentTarget.style.color = sidebar.label.color;
                     }
                   }}
                 >
                   <div className="flex items-center gap-3">
-                    {/* Icon */}
                     {item.icon && (
                       <div className="text-xl transition-colors" style={{
-                        color: item.isActive ? "var(--sidebar-active-icon, #3b82f6)" : "var(--sidebar-icon-color, #64748b)"
+                        color: item.isActive ? sidebar.active.iconColor : sidebar.icon.color
                       }}>
                         {item.icon}
                       </div>
                     )}
-                    
-                    {/* Label */}
                     <ITText as="span" className={`font-medium text-sm ${item.isActive ? 'font-semibold' : ''}`}>{item.label}</ITText>
                   </div>
 
-                  {/* Chevron for expandable items */}
                   {item.subitems && item.subitems.length > 0 && (
-                    <div className="transition-transform" style={{ color: "var(--sidebar-icon-color, #64748b)" }}>
+                    <div className="transition-transform" style={{ color: sidebar.icon.color }}>
                       {expandedItems.has(item.id) ? (
                         <FaChevronDown className="w-3 h-3" />
                       ) : (
@@ -209,23 +239,22 @@ export default function ITNavbar({
                   )}
                 </div>
 
-                {/* Submenu */}
-                {item.subitems && 
-                 item.subitems.length > 0 && 
+                {item.subitems &&
+                 item.subitems.length > 0 &&
                  expandedItems.has(item.id) && (
-                  <ul className="mt-1 ml-4 pl-4 space-y-1" style={{ borderLeft: "1px solid var(--sidebar-border, #1e293b)" }}>
+                  <ul className="mt-1 ml-4 pl-4 space-y-1" style={{ borderLeft: `1px solid ${sidebar.borderColor}` }}>
                     {item.subitems.map((subitem) => (
                       <li key={subitem.id}>
                         <button
                           onClick={subitem.action}
                           className="block w-full text-left px-4 py-2.5 rounded-lg text-sm transition-all duration-200"
                           style={{
-                            color: subitem.isActive ? "var(--sidebar-active-color, #ffffff)" : "var(--sidebar-label-color, #94a3b8)",
-                            backgroundColor: subitem.isActive ? "var(--sidebar-active-bg, rgba(255,255,255,0.1))" : "transparent"
+                            color: subitem.isActive ? sidebar.active.color : sidebar.label.color,
+                            backgroundColor: subitem.isActive ? sidebar.active.backgroundColor : "transparent"
                           }}
                           onMouseEnter={(e) => {
                             if (!subitem.isActive) {
-                              e.currentTarget.style.backgroundColor = "var(--sidebar-hover-bg, rgba(255,255,255,0.05))";
+                              e.currentTarget.style.backgroundColor = sidebar.hover.backgroundColor;
                             }
                           }}
                           onMouseLeave={(e) => {
@@ -247,14 +276,14 @@ export default function ITNavbar({
 
         {/* User Menu */}
         {userMenu && (
-          <div className="p-4" style={{ borderTop: "1px solid var(--sidebar-border, #1e293b)" }}>
+          <div className="p-4" style={{ borderTop: `1px solid ${sidebar.borderColor}` }}>
             <div className="relative">
               <button
                 type="button"
                 className="flex items-center gap-3 w-full p-3 rounded-xl transition-colors duration-200 group"
-                style={{ color: "var(--sidebar-label-color, #94a3b8)" }}
-                onMouseEnter={(e) => { e.currentTarget.style.backgroundColor = "var(--sidebar-hover-bg, rgba(255,255,255,0.05))"; e.currentTarget.style.color = "var(--sidebar-active-color, #ffffff)"; }}
-                onMouseLeave={(e) => { e.currentTarget.style.backgroundColor = "transparent"; e.currentTarget.style.color = "var(--sidebar-label-color, #94a3b8)"; }}
+                style={{ color: sidebar.label.color }}
+                onMouseEnter={(e) => { e.currentTarget.style.backgroundColor = sidebar.hover.backgroundColor; e.currentTarget.style.color = sidebar.active.color; }}
+                onMouseLeave={(e) => { e.currentTarget.style.backgroundColor = "transparent"; e.currentTarget.style.color = sidebar.label.color; }}
                 onClick={toggleUserMenu}
               >
                 {userMenu.userImage ? (
@@ -262,37 +291,40 @@ export default function ITNavbar({
                     className="w-10 h-10 rounded-full border-2 transition-colors"
                     src={userMenu.userImage}
                     alt="user photo"
-                    style={{ borderColor: "var(--sidebar-border, #1e293b)" }}
+                    style={{ borderColor: sidebar.borderColor }}
                   />
                 ) : (
-                  <div className="w-10 h-10 rounded-full flex items-center justify-center transition-colors" style={{ backgroundColor: "var(--sidebar-hover-bg, rgba(255,255,255,0.1))", color: "var(--sidebar-icon-color, #64748b)" }}>
-                      <FaUserCircle className="w-6 h-6" />
+                  <div
+                    className="w-10 h-10 rounded-full flex items-center justify-center transition-colors"
+                    style={{ backgroundColor: sidebar.hover.backgroundColor, color: sidebar.icon.color }}
+                  >
+                    <FaUserCircle className="w-6 h-6" />
                   </div>
                 )}
                 <div className="flex-1 text-left overflow-hidden">
-                  <ITText as="div" className="font-medium text-sm truncate" style={{ color: "var(--sidebar-active-color, #ffffff)" }}>
+                  <ITText as="div" className="font-medium text-sm truncate" style={{ color: sidebar.active.color }}>
                     {userMenu.userName}
                   </ITText>
-                  <ITText as="div" className="text-xs truncate" style={{ color: "var(--sidebar-label-color, #94a3b8)" }}>
+                  <ITText as="div" className="text-xs truncate" style={{ color: sidebar.label.color }}>
                     {userMenu.userEmail}
                   </ITText>
                 </div>
-                <FaChevronRight className="w-3 h-3" style={{ color: "var(--sidebar-icon-color, #64748b)" }} />
+                <FaChevronRight className="w-3 h-3" style={{ color: sidebar.icon.color }} />
               </button>
 
               {isUserMenuOpen && (
                 <div
                   ref={userMenuRef}
                   className="absolute bottom-full left-0 mb-3 w-full rounded-xl shadow-2xl overflow-hidden transform transition-all duration-200 origin-bottom"
-                  style={{ backgroundColor: "var(--topbar-user-dropdown-bg, #ffffff)", border: "1px solid var(--topbar-user-dropdown-border, #e2e8f0)" }}
+                  style={{ backgroundColor: topbar.userMenu.dropdown.backgroundColor, border: `1px solid ${topbar.userMenu.dropdown.borderColor}` }}
                 >
-                  <div className="px-4 py-3" style={{ backgroundColor: "var(--topbar-user-bg, #f8fafc)", borderBottom: "1px solid var(--topbar-user-dropdown-border, #e2e8f0)" }}>
-                      <ITText as="span" className="block text-sm font-semibold" style={{ color: "var(--topbar-user-text, #0f172a)" }}>
-                        {userMenu.userName}
-                      </ITText>
-                      <ITText as="span" className="block text-xs truncate" style={{ color: "var(--topbar-user-subtitle, #64748b)" }}>
-                        {userMenu.userEmail}
-                      </ITText>
+                  <div className="px-4 py-3" style={{ backgroundColor: topbar.userMenu.backgroundColor, borderBottom: `1px solid ${topbar.userMenu.dropdown.borderColor}` }}>
+                    <ITText as="span" className="block text-sm font-semibold" style={{ color: topbar.userMenu.textColor }}>
+                      {userMenu.userName}
+                    </ITText>
+                    <ITText as="span" className="block text-xs truncate" style={{ color: topbar.userMenu.subtitleColor }}>
+                      {userMenu.userEmail}
+                    </ITText>
                   </div>
                   <ul className="py-1">
                     {userMenu.menuItems.map((item, index) => (
@@ -303,8 +335,8 @@ export default function ITNavbar({
                             setIsUserMenuOpen(false);
                           }}
                           className="flex items-center w-full px-4 py-2.5 text-sm transition-colors"
-                          style={{ color: "var(--topbar-user-text, #334155)" }}
-                          onMouseEnter={(e) => { e.currentTarget.style.backgroundColor = "var(--topbar-user-item-hover, #f8fafc)"; }}
+                          style={{ color: topbar.userMenu.textColor }}
+                          onMouseEnter={(e) => { e.currentTarget.style.backgroundColor = topbar.userMenu.dropdown.itemHoverBackground; }}
                           onMouseLeave={(e) => { e.currentTarget.style.backgroundColor = "transparent"; }}
                         >
                           <ITText as="span">{item.label}</ITText>
@@ -320,7 +352,7 @@ export default function ITNavbar({
       </aside>
 
       {/* Main Content */}
-      <main className="flex-1 overflow-y-auto relative" style={{ backgroundColor: "var(--layout-bg, #f8fafc)" }}>
+      <main className="flex-1 overflow-y-auto relative" style={{ backgroundColor: theme.layout.backgroundColor }}>
         {children}
       </main>
     </div>

package/src/components/page/page.doc.mdx

@@ -0,0 +1,80 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './page.stories';
+
+<Meta of={Stories} />
+
+# ITPage
+
+A page template component that wraps an ITPageHeader with content area and built-in state handling for loading, error, and empty states. Provides automatic skeleton placeholders during loading, an error boundary with retry action, and a customizable empty state with action.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `undefined` | Page title passed to the header. |
+| `description` | `string` | `undefined` | Description text shown below the title. |
+| `breadcrumbs` | `ITBreadcrumbItem[]` | `undefined` | Breadcrumb navigation items. |
+| `actions` | `ReactNode` | `undefined` | Action buttons rendered in the header. |
+| `backAction` | `() => void` | `undefined` | Callback for the back button. |
+| `icon` | `ReactNode` | `undefined` | Icon displayed next to the title. |
+| `iconColor` | `string` | `undefined` | Custom color for the icon. |
+| `loading` | `boolean` | `false` | When true, shows skeleton placeholders instead of content. |
+| `error` | `string \| null` | `null` | Error message. When provided, shows an error state with retry button. |
+| `errorTitle` | `string` | `'Error'` | Custom title for the error state. |
+| `errorActionLabel` | `string` | `'Reintentar'` | Label for the retry button in the error state. |
+| `onRetry` | `() => void` | `undefined` | Callback when the retry button is clicked. |
+| `empty` | `boolean` | `false` | When true, shows an empty state placeholder. |
+| `emptyTitle` | `string` | `'Sin datos'` | Custom title for the empty state. |
+| `emptyDescription` | `string` | `undefined` | Custom description for the empty state. |
+| `emptyAction` | `ReactNode` | `undefined` | Custom action element for the empty state. |
+| `children` | `ReactNode` | required | Content rendered when no special state (loading/error/empty) is active. |
+| `maxWidth` | `'2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl' \| '7xl'` | `'7xl'` | Maximum width of the page content container. |
+| `noPadding` | `boolean` | `false` | When true, removes default padding from the page wrapper. |
+| `className` | `string` | `undefined` | Additional CSS classes for the page wrapper. |
+
+## Usage
+
+```tsx
+import { ITPage } from '@axzydev/axzy_ui_system';
+
+<ITPage title="Users" description="Manage system users" actions={<ITButton label="Add" />}>
+  <p>Your page content</p>
+</ITPage>
+
+<ITPage title="Dashboard" loading>
+  <p>Content not shown while loading</p>
+</ITPage>
+
+<ITPage
+  title="Orders"
+  error="Failed to load orders"
+  onRetry={() => refetch()}
+>
+  <p>Content not shown while error</p>
+</ITPage>
+
+<ITPage
+  title="Notifications"
+  empty
+  emptyTitle="No notifications"
+  emptyAction={<ITButton label="Refresh" />}
+>
+  <p>Content not shown while empty</p>
+</ITPage>
+```
+
+## Notes
+
+- State priority: `error` > `loading` > `empty` > `children`.
+- The loading state renders animated skeleton blocks matching common page patterns.
+- The error state renders a centered error icon, message, and a retry button.
+- The empty state renders a centered placeholder with optional title, description, and action.
+- All header props (`title`, `description`, `breadcrumbs`, `actions`, `backAction`, `icon`) are forwarded to ITPageHeader.
+- Content maximum width is controlled by Tailwind max-width classes via `maxWidth`.
+- `noPadding` is useful for full-bleed layouts like dashboards.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/page/page.props.ts

@@ -1,21 +1,46 @@
 import { ReactNode } from "react";
 import { ITBreadcrumbItem } from "../breadcrumbs/breadcrumbs.props";
 
+/** Props for the ITPage component. */
 export interface ITPageProps {
+  /** Page title passed to the header. */
   title?: string;
+  /** Description text shown below the title. */
   description?: string;
+  /** Array of breadcrumb items for navigation context. */
   breadcrumbs?: ITBreadcrumbItem[];
+  /** Action buttons rendered in the header. */
   actions?: ReactNode;
+  /** Callback fired when the back button is clicked. */
   backAction?: () => void;
+  /** Optional icon displayed next to the title. */
+  icon?: ReactNode;
+  /** Custom color for the icon. Accepts any valid CSS color value. */
+  iconColor?: string;
+  /** Whether the page is in a loading state. Shows skeleton placeholders when true. */
   loading?: boolean;
+  /** Error message to display. Shows an error state with retry button when provided. */
   error?: string | null;
+  /** Custom title for the error state. Default: "Error". */
   errorTitle?: string;
+  /** Label for the retry button in the error state. Default: "Reintentar". */
   errorActionLabel?: string;
+  /** Callback fired when the retry button is clicked in the error state. */
   onRetry?: () => void;
+  /** Whether the page is in an empty state. Shows a placeholder when true. */
   empty?: boolean;
+  /** Custom title for the empty state. Default: "Sin datos". */
   emptyTitle?: string;
+  /** Custom description for the empty state. */
   emptyDescription?: string;
+  /** Custom action element for the empty state. */
   emptyAction?: ReactNode;
+  /** Additional CSS classes for the page wrapper. */
   className?: string;
+  /** Content rendered inside the page wrapper. */
   children: ReactNode;
+  /** Maximum width of the page content. Options: "2xl", "3xl", "4xl", "5xl", "6xl", "7xl". Default: "7xl". */
+  maxWidth?: "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl";
+  /** Whether to remove default padding from the page wrapper. */
+  noPadding?: boolean;
 }

package/src/components/page/page.tsx

@@ -7,7 +7,7 @@ import ITButton from "../button/button";
 import ITStack from "../stack/stack";
 
 const hasHeader = (props: ITPageProps) =>
-  !!(props.title || props.description || props.breadcrumbs || props.actions || props.backAction);
+  !!(props.title || props.description || props.breadcrumbs || props.actions || props.backAction || props.icon);
 
 const renderHeader = (props: ITPageProps) => {
   if (!hasHeader(props)) return null;
@@ -18,10 +18,30 @@ const renderHeader = (props: ITPageProps) => {
       breadcrumbs={props.breadcrumbs}
       actions={props.actions}
       backAction={props.backAction}
+      icon={props.icon}
+      iconColor={props.iconColor}
     />
   );
 };
 
+/**
+ * Page template combining a page header and content area with built-in states for loading, error, and empty.
+ *
+ * @example
+ * ```tsx
+ * <ITPage
+ *   title="Dashboard"
+ *   description="Overview of your account"
+ *   breadcrumbs={[{ label: 'Home' }, { label: 'Dashboard' }]}
+ *   actions={<ITButton label="Refresh" />}
+ *   loading={isLoading}
+ *   error={errorMessage}
+ *   onRetry={fetchData}
+ * >
+ *   <ITCard>Dashboard content</ITCard>
+ * </ITPage>
+ * ```
+ */
 export default function ITPage(props: ITPageProps) {
   const {
     loading = false,
@@ -35,18 +55,26 @@ export default function ITPage(props: ITPageProps) {
     emptyAction,
     className,
     children,
+    maxWidth = "7xl",
+    noPadding = false,
   } = props;
 
-  const wrapperClass = clsx("space-y-6", className);
+  const wrapperClass = clsx(
+    "mx-auto w-full",
+    !noPadding && "px-4 sm:px-6 lg:px-8 py-6",
+    `max-w-${maxWidth}`,
+    "space-y-8",
+    className
+  );
 
   if (loading) {
     return (
       <div className={wrapperClass}>
         {renderHeader(props)}
-        <ITStack spacing={4}>
-          <ITSkeleton variant="rectangular" height={40} width="40%" />
-          <ITSkeleton variant="rectangular" height={200} />
-          <ITSkeleton variant="rectangular" height={200} />
+        <ITStack spacing={6}>
+          <ITSkeleton variant="rectangular" height={40} width="40%" className="rounded-lg" />
+          <ITSkeleton variant="rectangular" height={200} className="rounded-lg" />
+          <ITSkeleton variant="rectangular" height={200} className="rounded-lg" />
         </ITStack>
       </div>
     );
@@ -92,4 +120,4 @@ export default function ITPage(props: ITPageProps) {
       {children}
     </div>
   );
-}
+}

package/src/components/page-header/page-header.doc.mdx

@@ -0,0 +1,54 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './page-header.stories';
+
+<Meta of={Stories} />
+
+# ITPageHeader
+
+A page title bar component that displays a heading with optional breadcrumbs, description text, action buttons, and a back navigation button. Designed to sit at the top of page content for consistent page-level navigation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | required | Page title displayed as the main heading. |
+| `description` | `string` | `undefined` | Optional description text shown below the title. |
+| `breadcrumbs` | `ITBreadcrumbItem[]` | `undefined` | Breadcrumb navigation items above the title. |
+| `actions` | `ReactNode` | `undefined` | Action buttons or elements rendered on the right side. |
+| `backAction` | `() => void` | `undefined` | Callback fired when the back button is clicked. |
+| `icon` | `ReactNode` | `undefined` | Optional icon displayed next to the title. |
+| `iconColor` | `string` | `undefined` | Custom CSS color value for the icon. |
+| `className` | `string` | `undefined` | Additional CSS classes for the container. |
+
+## Usage
+
+```tsx
+import { ITPageHeader } from '@axzydev/axzy_ui_system';
+import { FaUsers } from 'react-icons/fa';
+
+<ITPageHeader
+  title="Users"
+  description="Manage system users"
+  breadcrumbs={[{ label: 'Dashboard', href: '#' }, { label: 'Users' }]}
+  actions={<ITButton label="Add User" />}
+/>
+<ITPageHeader
+  title="Edit User"
+  backAction={() => navigate(-1)}
+  breadcrumbs={[{ label: 'Users', href: '/users' }, { label: 'Edit' }]}
+/>
+```
+
+## Notes
+
+- Breadcrumbs render above the title using the ITBreadcrumbs component.
+- `backAction` renders a left-arrow button before the content; breadcrumbs shift to the right of the back button.
+- The `icon` slot places an icon beside the title, colored by `iconColor` or the primary theme color.
+- Actions area accepts any React nodes; typically ITButton components with `small` sizing.
+- The component uses a flex layout: breadcrumbs + back button on the left, actions on the right.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/page-header/page-header.props.ts

@@ -1,11 +1,22 @@
 import { ReactNode } from "react";
 import { ITBreadcrumbItem } from "../breadcrumbs/breadcrumbs.props";
 
+/** Props for the ITPageHeader component. */
 export interface ITPageHeaderProps {
+  /** Page title displayed as the main heading. */
   title: string;
+  /** Optional description text shown below the title. */
   description?: string;
+  /** Array of breadcrumb items for navigation context. */
   breadcrumbs?: ITBreadcrumbItem[];
+  /** Action buttons or elements rendered on the right side. */
   actions?: ReactNode;
+  /** Callback fired when the back button is clicked. */
   backAction?: () => void;
+  /** Optional icon displayed next to the title. */
+  icon?: ReactNode;
+  /** Custom color for the icon. Accepts any valid CSS color value. */
+  iconColor?: string;
+  /** Additional CSS classes for the container. */
   className?: string;
 }

package/src/components/page-header/page-header.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { FaUsers } from "react-icons/fa";
 import ITPageHeader from "./page-header";
 import ITButton from "../button/button";
 
@@ -59,3 +60,16 @@ export const WithBackAction: Story = {
     actions: <ITButton label="Editar" size="small" />,
   },
 };
+
+export const WithIcon: Story = {
+  args: {
+    title: "Usuarios",
+    description: "Gestiona los usuarios del sistema",
+    icon: <FaUsers size={20} />,
+    iconColor: "#6366f1",
+    breadcrumbs: [
+      { label: "Inicio", href: "#" },
+      { label: "Usuarios" },
+    ],
+  },
+};