@axzydev/axzy_ui_system 1.2.6 → 1.2.8

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "type": "module",
   "sideEffects": [
     "*.css"

package/src/App.tsx

@@ -1,4 +1,4 @@
-import React, { useMemo, useState } from "react";
+import React, { useEffect, useMemo, useState } from "react";
 import {
   FaCreditCard,
 FaHome,
@@ -24,7 +24,6 @@ import {
   GridShowcase,
   ScreenDashboardShowcase,
   ScreenFormShowcase,
-  ScreenCardGridShowcase,
 } from "./showcases/LayoutPrimitivesShowcases";
 import {
   PageHeaderShowcase,
@@ -62,12 +61,27 @@ import {
 } from "./showcases/FeedbackShowcases";
 
 function App() {
-  const [activeComponentId, setActiveComponentId] = useState("home");
+  const [activeComponentId, setActiveComponentId] = useState(
+    () => window.location.hash.replace("#", "") || "home"
+  );
   const [searchTerm, setSearchTerm] = useState("");
   const [subitemConnector, setSubitemConnector] = useState<
     "dot" | "|" | "none"
   >("dot");
 
+  useEffect(() => {
+    const onHashChange = () => {
+      const id = window.location.hash.replace("#", "") || "home";
+      setActiveComponentId(id);
+    };
+    window.addEventListener("hashchange", onHashChange);
+    return () => window.removeEventListener("hashchange", onHashChange);
+  }, []);
+
+  useEffect(() => {
+    window.location.hash = activeComponentId;
+  }, [activeComponentId]);
+
   // Group definitions for the sidebar
   const categories = [
     {
@@ -90,7 +104,6 @@ function App() {
         { id: "page", label: "ITPage" },
         { id: "screen-dashboard", label: "Dashboard Ejemplo" },
         { id: "screen-form", label: "Formulario Ejemplo" },
-        { id: "screen-cardgrid", label: "Grid Tarjetas Ejemplo" },
       ],
     },
     {
@@ -239,8 +252,6 @@ function App() {
         return <ScreenDashboardShowcase />;
       case "screen-form":
         return <ScreenFormShowcase />;
-      case "screen-cardgrid":
-        return <ScreenCardGridShowcase />;
       // Forms
       case "button":
         return <ButtonShowcase />;
@@ -297,54 +308,8 @@ function App() {
   return (
     <ITThemeProvider showFab={true}>
       <ITLayout sidebar={sidebarProps} topBar={topBarProps}>
-        <div className="max-w-7xl mx-auto space-y-6">
-          {/* Glassmorphic Search Bar Header */}
-          <div className="relative p-6 rounded-2xl bg-white/70 dark:bg-slate-900/60 border border-slate-100 dark:border-slate-800 backdrop-blur-md shadow-sm flex flex-col md:flex-row md:items-center justify-between gap-4">
-            <div>
-              <h2 className="text-xl font-bold text-slate-800 dark:text-white">
-                Explorador de Componentes
-              </h2>
-              <p className="text-xs text-slate-500">
-                Selecciona o filtra en la lista lateral para inspeccionar e
-                interactuar.
-              </p>
-            </div>
-            <div className="flex flex-wrap items-center gap-3">
-              {/* Connector selection */}
-              <div className="flex items-center gap-1 bg-slate-100/80 dark:bg-slate-950/40 p-1 rounded-xl border border-slate-200/50 dark:border-slate-800/80">
-                {(["dot", "|", "none"] as const).map((style) => (
-                  <button
-                    key={style}
-                    onClick={() => setSubitemConnector(style)}
-                    className={`px-3 py-1 text-xs font-semibold rounded-lg transition-all ${
-                      subitemConnector === style
-                        ? "bg-white dark:bg-slate-800 text-indigo-600 dark:text-indigo-400 shadow-sm border border-slate-100 dark:border-slate-700/50"
-                        : "text-slate-500 hover:text-slate-800 dark:hover:text-slate-200"
-                    }`}
-                  >
-                    {style === "dot" ? "Punto" : style === "|" ? "Vertical" : "Normal"}
-                  </button>
-                ))}
-              </div>
-
-              <div className="relative w-full md:w-80">
-                <input
-                  type="text"
-                  placeholder="Buscar componente..."
-                  value={searchTerm}
-                  onChange={(e) => setSearchTerm(e.target.value)}
-                  className="w-full bg-slate-100/80 dark:bg-slate-950/40 text-slate-800 dark:text-white pl-10 pr-4 py-2 text-sm rounded-xl outline-none focus:ring-2 focus:ring-primary-500 border border-transparent focus:border-transparent transition-all"
-                />
-                <FaSearch
-                  className="absolute left-3 top-3 text-slate-400"
-                  size={14}
-                />
-              </div>
-            </div>
-          </div>
-          <div className="bg-white/50 dark:bg-slate-950/10 border border-slate-100 dark:border-slate-900 rounded-3xl p-6 md:p-8 backdrop-blur-sm min-h-[500px]">
-            {renderShowcase()}
-          </div>
+        <div className="max-w-7xl mx-auto">
+          {renderShowcase()}
         </div>
       </ITLayout>
     </ITThemeProvider>

package/src/components/alert/alert.doc.mdx

@@ -0,0 +1,48 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './alert.stories';
+
+<Meta of={Stories} />
+
+# ITAlert
+
+Dismissible alert banners that provide contextual feedback messages to users. Supports four semantic variants — info, success, warning, and error — each with a distinct icon and color scheme. Alerts can optionally include a bold title, a custom icon override, and a dismiss button for user-dismissible notifications.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Visual style with corresponding icon and color scheme. |
+| `title` | `string` | — | Bold heading text displayed above the message. |
+| `children` | `ReactNode` | — | Alert message content. |
+| `dismissible` | `boolean` | `false` | Whether the alert can be dismissed by the user. |
+| `onDismiss` | `() => void` | — | Callback fired when the dismiss button is clicked. |
+| `icon` | `ReactNode` | — | Custom icon element that overrides the default variant icon. |
+| `className` | `string` | — | Additional CSS class names for the alert container. |
+
+## Usage
+
+```tsx
+import { ITAlert } from '@axzydev/axzy_ui_system';
+
+<ITAlert variant="success" title="Guardado" dismissible onDismiss={() => {}}>
+  Los cambios se guardaron correctamente.
+</ITAlert>
+
+<ITAlert variant="error">Ocurrió un error inesperado.</ITAlert>
+```
+
+## Variants / Notes
+
+- **info** — Neutral blue style for general informational messages.
+- **success** — Green style for positive confirmation and completion messages.
+- **warning** — Amber/yellow style for cautionary messages.
+- **error** — Red style for critical errors and failures.
+- All variants render with `role="alert"` for accessibility.
+- Supports dark mode with appropriate color adjustments.
+- The dismiss button only renders when both `dismissible` and `onDismiss` are set.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/alert/alert.props.ts

@@ -3,11 +3,18 @@ import { ReactNode } from "react";
 export type AlertVariant = "info" | "success" | "warning" | "error";
 
 export interface ITAlertProps {
+  /** Alert visual style. Valid values: `"info"`, `"success"`, `"warning"`, `"error"`. @default "info" */
   variant?: AlertVariant;
+  /** Optional bold title text displayed above the message. */
   title?: string;
+  /** Alert message content. */
   children?: ReactNode;
+  /** Whether the alert can be dismissed by the user. @default false */
   dismissible?: boolean;
+  /** Callback fired when the dismiss button is clicked. */
   onDismiss?: () => void;
+  /** Custom icon element. Overrides the default variant icon. */
   icon?: ReactNode;
+  /** Additional CSS class names for the alert container. */
   className?: string;
 }

package/src/components/alert/alert.tsx

@@ -23,6 +23,14 @@ const config: Record<AlertVariant, { icon: React.ReactNode; classes: string }> =
   },
 };
 
+/**
+ * Dismissible alert banner with 4 visual variants and optional custom icon.
+ *
+ * @example
+ * <ITAlert variant="success" title="Success" dismissible onDismiss={() => {}}>
+ *   Operation completed successfully.
+ * </ITAlert>
+ */
 export default function ITAlert({
   variant = "info",
   title,

package/src/components/avatar/avatar.doc.mdx

@@ -0,0 +1,48 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './avatar.stories';
+
+<Meta of={Stories} />
+
+# ITAvatar
+
+Circular avatar component for displaying user profile pictures, initials, or generic placeholder content. Falls back to displaying initials when the image fails to load or is not provided. Supports five sizes and an optional badge overlay for status indicators.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Image source URL for the avatar. |
+| `alt` | `string` | — | Alt text for the image. Also used as fallback initial when no `initials` or `src` is provided. |
+| `initials` | `string` | — | Initials to display when no image is available (max 2 characters recommended). |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Avatar dimensions. |
+| `color` | `string` | `"bg-primary-500"` | Background color class for the initials fallback. |
+| `className` | `string` | — | Additional CSS class names for the avatar container. |
+| `badge` | `ReactNode` | — | React node rendered as a badge overlay at the bottom-right corner. |
+| `onClick` | `() => void` | — | Click handler. When provided, the avatar becomes interactive (`role="button"`). |
+
+## Usage
+
+```tsx
+import { ITAvatar } from '@axzydev/axzy_ui_system';
+
+<ITAvatar src="https://i.pravatar.cc/150" alt="User" size="md" />
+
+<ITAvatar initials="JD" size="lg" badge={<FaCircle className="text-emerald-500" />} />
+```
+
+## Variants / Notes
+
+- **xs** — Extra small (ideal for inline lists or compact UIs).
+- **sm** — Small (useful in table rows or sidebars).
+- **md** — Medium, the default size suitable for most use cases.
+- **lg** — Large (prominent display or profile pages).
+- **xl** — Extra large (hero sections or standalone profile views).
+- Shows initials text fallback when `src` is missing or the image fails (`onError`).
+- Badge slot positioned at bottom-right using absolute positioning.
+- Becomes interactive with click handler and hover cursor when `onClick` is provided.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/avatar/avatar.props.ts

@@ -3,12 +3,20 @@ import { ReactNode } from "react";
 export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 
 export interface ITAvatarProps {
+  /** Image source URL for the avatar. When provided, displays an `<img>` element. */
   src?: string;
+  /** Alt text for the avatar image. Also used as fallback initial when no `initials` or `src` is provided. */
   alt?: string;
+  /** Initials to display when no image is available (max 2 characters recommended). */
   initials?: string;
+  /** Avatar dimensions. Valid values: `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`. @default "md" */
   size?: AvatarSize;
+  /** Background color class for the initials fallback. @default "bg-primary-600" */
   color?: string;
+  /** Additional CSS class names for the avatar container. */
   className?: string;
+  /** React node rendered as a badge overlay at the bottom-right corner. */
   badge?: ReactNode;
+  /** Click handler. When provided, the avatar becomes interactive (role="button"). */
   onClick?: () => void;
 }

package/src/components/avatar/avatar.tsx

@@ -10,21 +10,41 @@ const sizeMap: Record<AvatarSize, { container: string; text: string }> = {
   xl: { container: "w-16 h-16", text: "text-xl" },
 };
 
+const DEFAULT_COLOR = "bg-primary-600";
+const DEFAULT_BG = "var(--color-primary-600)";
+const DEFAULT_SHADOW = "0 4px 14px 0 rgba(37, 99, 235, 0.35)";
+
+/**
+ * Circular avatar component with image, initials fallback, and optional badge overlay.
+ *
+ * @example
+ * <ITAvatar src="/avatar.jpg" alt="John Doe" size="lg" badge={<span className="w-2.5 h-2.5 bg-success-500 rounded-full" />} />
+ *
+ * @example
+ * <ITAvatar initials="JD" size="md" color="bg-purple-600" />
+ */
 export default function ITAvatar({
   src,
   alt = "",
   initials,
   size = "md",
-  color = "bg-primary-500",
+  color = DEFAULT_COLOR,
   className,
   badge,
   onClick,
 }: ITAvatarProps) {
   const { container, text } = sizeMap[size];
+  const useInlineStyle = !color || color === DEFAULT_COLOR;
 
   return (
     <div
-      className={clsx("relative inline-flex items-center justify-center rounded-full flex-shrink-0", container, className)}
+      className={clsx(
+        "relative inline-flex items-center justify-center rounded-full flex-shrink-0 overflow-hidden text-white font-bold tracking-wide",
+        container,
+        !useInlineStyle && color,
+        className,
+      )}
+      style={useInlineStyle ? { backgroundColor: DEFAULT_BG, boxShadow: DEFAULT_SHADOW } : undefined}
       onClick={onClick}
       role={onClick ? "button" : undefined}
       tabIndex={onClick ? 0 : undefined}
@@ -39,9 +59,9 @@ export default function ITAvatar({
           }}
         />
       ) : (
-        <div className={clsx("w-full h-full rounded-full flex items-center justify-center text-white font-semibold", text, color)}>
-          <ITText as="span">{initials || alt.charAt(0).toUpperCase() || "?"}</ITText>
-        </div>
+        <span className={clsx("flex items-center justify-center w-full h-full", text)}>
+          <ITText as="span" className="text-white">{initials || alt.charAt(0).toUpperCase() || "?"}</ITText>
+        </span>
       )}
       {badge && (
         <div className="absolute -bottom-0.5 -right-0.5">

package/src/components/badget/badget.doc.mdx

@@ -0,0 +1,46 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './badget.stories';
+
+<Meta of={Stories} />
+
+# ITBadget
+
+Small status tags and labels for highlighting metadata, categories, or states. Offers filled and outlined visual variants across all semantic color themes. Accepts either a simple label string or custom React children for complex content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Text label displayed inside the badge. Overridden if `children` is provided. |
+| `children` | `ReactNode` | — | Custom content rendered inside the badge. Takes precedence over `label`. |
+| `color` | `ColorsTypes` | `"primary"` | Color theme key (`"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"purple"`, `"info"`). |
+| `size` | `SizesTypes` | `"medium"` | Badge size (`"small"`, `"medium"`, `"large"`). |
+| `variant` | `"filled" \| "outlined"` | `"filled"` | Visual style — solid background or transparent with colored border. |
+| `className` | `string` | — | Additional CSS class names for the badge element. |
+
+## Usage
+
+```tsx
+import { ITBadget } from '@axzydev/axzy_ui_system';
+
+<ITBadget label="Active" color="success" variant="filled" />
+
+<ITBadget color="danger" variant="outlined" size="small">
+  <span className="flex items-center gap-1">3 new</span>
+</ITBadget>
+```
+
+## Variants / Notes
+
+- **filled** — Solid background with contrasting text (default for most theme colors).
+- **outlined** — Transparent background with a colored border and darker text.
+- Colors include `primary`, `secondary`, `success`, `danger`, `warning`, `purple`, and `info`.
+- Border radius defaults to fully rounded (`borderRadius: 9999px`), giving a pill shape.
+- Styles are fully theme-driven via the centralized theme configuration.
+- Custom children override the `label` prop entirely.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/badget/badget.props.ts

@@ -3,10 +3,16 @@ import { ColorsTypes } from "@/types/colors.types";
 import { SizesTypes } from "@/types/sizes.types";
 
 export interface ITBadgetProps {
+  /** Text label displayed inside the badge. Overridden if `children` is provided. */
   label?: string;
+  /** Custom content to render inside the badge. Takes precedence over `label`. */
   children?: React.ReactNode;
+  /** Color theme key. Values come from the semantic color palette (e.g. `"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"info"`, `"purple"`, `"error"`, `"gray"`). @default "primary" */
   color?: ColorsTypes;
+  /** Badge size. Valid values: `"small"`, `"medium"`, `"large"`. @default "medium" */
   size?: SizesTypes;
+  /** Badge visual style. Valid values: `"filled"`, `"outlined"`. @default "filled" */
   variant?: keyof typeof badgeVariants;
+  /** Additional CSS class names for the badge element. */
   className?: string;
 }

package/src/components/badget/badget.tsx

@@ -7,6 +7,17 @@ import {
 import { theme } from "@/theme/theme";
 import ITText from "@/components/text/text";
 
+/**
+ * Small status tag or label with theme-based colors and filled/outlined variants.
+ *
+ * @example
+ * <ITBadget label="Active" color="success" variant="filled" />
+ *
+ * @example
+ * <ITBadget color="danger" variant="outlined" size="small">
+ *   <span className="flex items-center gap-1">3 new</span>
+ * </ITBadget>
+ */
 export default function ITBadget({
   children,
   label,

package/src/components/breadcrumbs/breadcrumbs.doc.mdx

@@ -0,0 +1,57 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './breadcrumbs.stories';
+
+<Meta of={Stories} />
+
+# ITBreadcrumbs
+
+Navigation breadcrumb trail component that displays the user's current location within a site hierarchy. Each item can be a link (`href`) or a button (`onClick`), with the last item automatically rendered as plain inactive text. Supports a custom separator between segments.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `ITBreadcrumbItem[]` | required | Ordered array of breadcrumb segments. The last item is rendered as plain text. |
+| `separator` | `ReactNode` | `<FaChevronRight size={10} />` | Custom separator element rendered between items. |
+| `className` | `string` | — | Additional CSS class names for the `<nav>` container. |
+
+### ITBreadcrumbItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | required | Display text for the breadcrumb segment. |
+| `href` | `string` | — | URL for the breadcrumb link. Renders an `<a>` tag. |
+| `onClick` | `() => void` | — | Click handler. Renders a `<button>` when no `href` is set. |
+
+## Usage
+
+```tsx
+import { ITBreadcrumbs } from '@axzydev/axzy_ui_system';
+
+<ITBreadcrumbs
+  items={[
+    { label: "Inicio", href: "#" },
+    { label: "Usuarios", href: "#" },
+    { label: "Editar Perfil" },
+  ]}
+/>
+
+<ITBreadcrumbs
+  items={[...]}
+  separator={<FaArrowRight size={10} />}
+/>
+```
+
+## Variants / Notes
+
+- The last item in the `items` array is always rendered as plain, non-interactive text representing the current page.
+- Items with an `href` render as anchor tags (`<a>`), while items with only `onClick` render as buttons (`<button>`).
+- Default separator is a chevron-right icon from FontAwesome (`FaChevronRight`).
+- Wrapped in a semantic `<nav>` element for accessibility.
+- The component is purely presentational — routing/navigation logic is handled by `href` or `onClick` props.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/breadcrumbs/breadcrumbs.props.ts

@@ -1,13 +1,19 @@
 import { ReactNode } from "react";
 
 export interface ITBreadcrumbItem {
+  /** Display text for the breadcrumb segment. */
   label: string;
+  /** URL for the breadcrumb link. Renders an `<a>` tag. */
   href?: string;
+  /** Click handler for the breadcrumb. Renders a `<button>` when no `href` is set. */
   onClick?: () => void;
 }
 
 export interface ITBreadcrumbsProps {
+  /** Ordered array of breadcrumb items. The last item is rendered as plain text (current page). */
   items: ITBreadcrumbItem[];
+  /** Custom separator element rendered between items. @default <FaChevronRight size={10} /> */
   separator?: ReactNode;
+  /** Additional CSS class names for the `<nav>` container. */
   className?: string;
 }

package/src/components/breadcrumbs/breadcrumbs.tsx

@@ -3,6 +3,18 @@ import { ITBreadcrumbsProps } from "./breadcrumbs.props";
 import { FaChevronRight } from "react-icons/fa";
 import ITText from "@/components/text/text";
 
+/**
+ * Navigation breadcrumb trail with automatic link/button rendering and custom separator.
+ *
+ * @example
+ * <ITBreadcrumbs
+ *   items={[
+ *     { label: "Home", href: "/" },
+ *     { label: "Products", href: "/products" },
+ *     { label: "Details" },
+ *   ]}
+ * />
+ */
 export default function ITBreadcrumbs({
   items,
   separator = <FaChevronRight size={10} />,

package/src/components/button/button.doc.mdx

@@ -0,0 +1,59 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './button.stories';
+
+<Meta of={Stories} />
+
+# ITButton
+
+The primary action component for triggering user interactions. Supports 8 distinct visual variants, 7 semantic color themes, and 3 sizes. Can render with an icon alongside a label, as an icon-only control, as a text link, or with custom children for flexible content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Button text label. Overridden if `children` is provided. |
+| `children` | `ReactNode` | — | Custom content rendered inside the button. Takes precedence over `label`. |
+| `icon` | `ReactNode` | — | Icon element rendered before the label. |
+| `onClick` | `() => void` | — | Click handler for the button. |
+| `color` | `ColorsTypes` | `"primary"` | Color theme key (`"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"purple"`, `"info"`). |
+| `size` | `SizesTypes` | `"medium"` | Button size (`"small"`, `"medium"`, `"large"`). |
+| `variant` | `"filled" \| "outlined" \| "raised" \| "rounded" \| "text" \| "raised-text" \| "icon-only" \| "link"` | `"filled"` | Visual style variant. |
+| `disabled` | `boolean` | `false` | Disables interaction and applies reduced opacity. |
+| `className` | `string` | — | Additional CSS class names for the button element. |
+| `type` | `"submit" \| "reset" \| "button"` | `"button"` | HTML button type attribute. |
+| `ariaLabel` | `string` | — | Accessible label for screen readers. Falls back to `label`. |
+| `title` | `string` | — | HTML title attribute for native tooltip. |
+
+## Usage
+
+```tsx
+import { ITButton } from '@axzydev/axzy_ui_system';
+
+<ITButton label="Guardar" color="primary" variant="filled" />
+
+<ITButton label="Descargar" color="success" variant="outlined" icon={<FaDownload />} />
+
+<ITButton color="danger" variant="icon-only" ariaLabel="Eliminar">
+  <FaTrash />
+</ITButton>
+```
+
+## Variants / Notes
+
+- **filled** — Solid background with shadow, the default and most prominent variant.
+- **outlined** — Transparent background with a colored border.
+- **raised** — Solid background with a pronounced box shadow for depth.
+- **rounded** — Like filled but with fully rounded (`rounded-full`) corners.
+- **text** — Minimal transparent background with hover highlight, suitable for toolbars.
+- **raised-text** — White background with subtle border and shadow, elevated appearance.
+- **icon-only** — Square aspect ratio with centered icon, no text label.
+- **link** — Renders as an inline text link with underline on hover.
+- Seven color themes: `primary`, `secondary`, `success`, `danger`, `warning`, `purple`, `info`.
+- When `disabled`, the button becomes non-interactive with reduced opacity.
+- Set `type="submit"` for form submission behavior.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/button/button.props.ts

@@ -3,16 +3,28 @@ import { ColorsTypes } from "@app/types/colors.types";
 import { SizesTypes } from "@app/types/sizes.types";
 
 export interface ITButtonProps {
+  /** Button text label. Overridden if `children` is provided. */
   label?: string
+  /** Custom content to render inside the button. Takes precedence over `label`. */
   children?: React.ReactNode;
+  /** Icon element rendered before the label. */
   icon?: React.ReactNode;
+  /** Click handler for the button. */
   onClick?: () => void;
+  /** Color theme key. Values come from the semantic color palette (e.g. `"primary"`, `"secondary"`, `"success"`, `"danger"`, `"warning"`, `"info"`, `"purple"`, `"error"`, `"gray"`). @default "primary" */
   color?: ColorsTypes;
+  /** Button size. Valid values: `"small"`, `"medium"`, `"large"`. @default "medium" */
   size?: SizesTypes;
+  /** Button visual style. Valid values: `"filled"`, `"outlined"`, `"raised"`, `"rounded"`, `"text"`, `"raised-text"`, `"icon-only"`, `"link"`. @default "filled" */
   variant?: keyof typeof buttonVariants;
+  /** Disables the button interaction and applies reduced opacity. @default false */
   disabled?: boolean;
+  /** Additional CSS class names for the button element. */
   className?: string;
+  /** HTML button type attribute. Valid values: `"submit"`, `"reset"`, `"button"`. @default "button" */
   type?: "submit" | "reset" | "button" | undefined;
+  /** Accessible label for screen readers. Falls back to `label` if not set. */
   ariaLabel?: string;
+  /** HTML title attribute for native tooltip. Falls back to `ariaLabel` or `label`. */
   title?: string;
 }

package/src/components/button/button.tsx

@@ -8,6 +8,17 @@ import { theme } from "@/theme/theme";
 import { ITButtonProps } from "./button.props";
 import ITText from "@/components/text/text";
 
+/**
+ * Highly configurable action button supporting 8 visual variants, theme colors, 3 sizes, icons, and hover/focus states.
+ *
+ * @example
+ * <ITButton label="Submit" color="primary" variant="filled" onClick={() => {}} />
+ *
+ * @example
+ * <ITButton color="danger" variant="outlined" size="small" icon={<FaTrash />}>
+ *   Delete
+ * </ITButton>
+ */
 export default function ITButton({
   children,
   label,