xertica-ui 2.5.3 → 2.6.0

package/components/assistant/modern-chat-input/modern-chat-input.mdx

@@ -1,71 +1,71 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ModernChatInputStories from './modern-chat-input.stories';
-
-<Meta of={ModernChatInputStories} />
-
-<Title />
-<Subtitle>An advanced, high-performance chat input for the Xertica Assistant.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage Patterns
-
-### Standard Floating Input
-Optimized for chat interfaces with multi-line support, voice recording, and action chips.
-
-<Canvas>
-  <ModernChatInputStories.Default />
-</Canvas>
-
-### Full-Page Variant
-Adjusts maximum width and alignment for use in standalone chat pages.
-
-<Canvas>
-  <ModernChatInputStories.FullPage />
-</Canvas>
-
----
-
-## Feature Flags
-
-Each input capability can be individually toggled via boolean props.
-All flags default to `true` for full backward compatibility.
-
-| Prop | Controls | Default |
-|---|---|---|
-| `enableAudioInput` | Voice recording button | `true` |
-| `enableFileAttachment` | File attachment (paperclip) button | `true` |
-| `enableDocumentCreation` | "Create document" menu item | `true` |
-| `enablePodcastGeneration` | "Generate podcast" menu item | `true` |
-| `enableSearch` | "Search" menu item | `true` |
-
-> [!NOTE]
-> When all three action types (`enableDocumentCreation`, `enablePodcastGeneration`, `enableSearch`) are set to `false`, the "+" menu button is completely hidden.
-
-### Text Only
-All action buttons disabled — only the text input and send button remain.
-
-<Canvas>
-  <ModernChatInputStories.TextOnly />
-</Canvas>
-
-### Selective Actions
-Only document creation and search are enabled for a focused workflow.
-
-<Canvas>
-  <ModernChatInputStories.SelectiveActions />
-</Canvas>
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Action Workflow** — Handle the `onSubmit` callback's optional `action` parameter to distinguish between standard text messages and intent-driven generations (Documents, Podcasts, Search).
-> - **State Sync** — Always maintain the `value` in a parent state and update it via `onChange` and `onVoiceRecording` to ensure consistent data binding.
-> - **Dynamic Sizing** — The input automatically expands up to 100px based on content; ensure the parent container can accommodate these height changes without layout shift.
-> - **Feature Flags** — Pass flags like `enableSearch={false}` or `enableAudioInput={false}` to tailor input capabilities per use-case. Flags are independent and can be combined freely.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ModernChatInputStories from './modern-chat-input.stories';
+
+<Meta of={ModernChatInputStories} />
+
+<Title />
+<Subtitle>An advanced, high-performance chat input for the Xertica Assistant.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage Patterns
+
+### Standard Floating Input
+Optimized for chat interfaces with multi-line support, voice recording, and action chips.
+
+<Canvas>
+  <ModernChatInputStories.Default />
+</Canvas>
+
+### Full-Page Variant
+Adjusts maximum width and alignment for use in standalone chat pages.
+
+<Canvas>
+  <ModernChatInputStories.FullPage />
+</Canvas>
+
+---
+
+## Feature Flags
+
+Each input capability can be individually toggled via boolean props.
+All flags default to `true` for full backward compatibility.
+
+| Prop | Controls | Default |
+|---|---|---|
+| `enableAudioInput` | Voice recording button | `true` |
+| `enableFileAttachment` | File attachment (paperclip) button | `true` |
+| `enableDocumentCreation` | "Create document" menu item | `true` |
+| `enablePodcastGeneration` | "Generate podcast" menu item | `true` |
+| `enableSearch` | "Search" menu item | `true` |
+
+> [!NOTE]
+> When all three action types (`enableDocumentCreation`, `enablePodcastGeneration`, `enableSearch`) are set to `false`, the "+" menu button is completely hidden.
+
+### Text Only
+All action buttons disabled — only the text input and send button remain.
+
+<Canvas>
+  <ModernChatInputStories.TextOnly />
+</Canvas>
+
+### Selective Actions
+Only document creation and search are enabled for a focused workflow.
+
+<Canvas>
+  <ModernChatInputStories.SelectiveActions />
+</Canvas>
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Action Workflow** — Handle the `onSubmit` callback's optional `action` parameter to distinguish between standard text messages and intent-driven generations (Documents, Podcasts, Search).
+> - **State Sync** — Always maintain the `value` in a parent state and update it via `onChange` and `onVoiceRecording` to ensure consistent data binding.
+> - **Dynamic Sizing** — The input automatically expands up to 100px based on content; ensure the parent container can accommodate these height changes without layout shift.
+> - **Feature Flags** — Pass flags like `enableSearch={false}` or `enableAudioInput={false}` to tailor input capabilities per use-case. Flags are independent and can be combined freely.

package/components/assistant/modern-chat-input/modern-chat-input.test.tsx

@@ -1,4 +1,5 @@
-import { render, screen, fireEvent, act, waitFor } from '@testing-library/react';
+import { screen, fireEvent, act, waitFor } from '@testing-library/react';
+import { renderWithProviders as render } from '../../../test/render';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { ModernChatInput } from './ModernChatInput';
 import React from 'react';
@@ -19,7 +20,7 @@ describe('ModernChatInput', () => {
     const onChange = vi.fn();
     render(<ModernChatInput value="" onChange={onChange} onSubmit={vi.fn()} />);
 
-    const textarea = screen.getByPlaceholderText('Mande uma mensagem para o Xertica');
+    const textarea = screen.getByPlaceholderText('Envie uma mensagem');
     fireEvent.change(textarea, { target: { value: 'hello' } });
 
     expect(onChange).toHaveBeenCalledWith('hello');

package/components/assistant/xertica-assistant/parts/AssistantMessageBubble.tsx

@@ -238,7 +238,7 @@ export function AssistantMessageBubble({
 
           {/* Table Rendering */}
           {msg.tableData && (
-            <div className="mt-4 w-full max-w-full border rounded-[var(--radius)] overflow-x-auto custom-scrollbar relative">
+            <div className="mt-4 w-full max-w-full border rounded-[var(--radius)] overflow-x-auto scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent relative">
               <Table>
                 {msg.tableData.caption && <TableCaption>{msg.tableData.caption}</TableCaption>}
                 <TableHeader>

package/components/assistant/xertica-assistant/types.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { ChartConfig, DashboardChartDatum } from '../../ui/chart';
 
 /**
  * @file types.ts
@@ -88,8 +89,8 @@ export interface Message {
   searchResults?: SearchResult[];
   searchSources?: SearchSource[];
   searchCommands?: SearchCommand[];
-  chartData?: any[];
-  chartConfig?: any;
+  chartData?: DashboardChartDatum[];
+  chartConfig?: ChartConfig;
   tableData?: {
     caption?: string;
     headers: string[];

package/components/assistant/xertica-assistant/use-assistant.ts

@@ -183,7 +183,7 @@ export function useAssistant({
   onSendMessage,
   isProcessing = false,
   responseGenerator,
-  richSuggestions = [],
+  richSuggestions: _richSuggestions = [],
   onRichAction,
   onEvaluation,
 }: UseAssistantProps = {}): UseAssistantReturn {
@@ -381,10 +381,11 @@ export function useAssistant({
           await navigator.clipboard.writeText(content);
           setCopiedId(messageId);
           setTimeout(() => setCopiedId(null), 2000);
-        } catch (clipboardError: any) {
+        } catch (clipboardError) {
           if (
-            clipboardError.name === 'NotAllowedError' ||
-            clipboardError.message.includes('permissions policy')
+            clipboardError instanceof Error &&
+            (clipboardError.name === 'NotAllowedError' ||
+              clipboardError.message.includes('permissions policy'))
           ) {
             throw new Error('Clipboard permission denied, falling back');
           }

package/components/assistant/xertica-assistant/xertica-assistant.mdx

@@ -1,66 +1,66 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as AssistantStories from './xertica-assistant.stories';
-
-<Meta of={AssistantStories} />
-
-<Title />
-<Subtitle>An embedded AI-powered assistant panel for chat, document creation, and data analysis.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Feature Flags
-
-Each assistant capability can be individually toggled on or off via boolean props.
-All flags default to `true` for full backward compatibility.
-
-| Prop | Controls | Default |
-|---|---|---|
-| `showHistory` | Conversation history tab and collapsed icon | `true` |
-| `showFavorites` | Favorites tab and collapsed icon | `true` |
-| `enableAudioInput` | Voice recording and audio upload | `true` |
-| `enableFileAttachment` | File attachment button | `true` |
-| `enableDocumentCreation` | "Create document" action in the input menu | `true` |
-| `enablePodcastGeneration` | "Generate podcast" action and per-message button | `true` |
-| `enableSearch` | "Search" action in the input menu | `true` |
-
-### Chat Only
-
-All extra features disabled — the assistant provides only a basic text chat.
-
-<Canvas of={AssistantStories.ChatOnly} />
-
-### Minimal Input
-
-Only document creation and file attachment are enabled — ideal for document-focused workflows.
-
-<Canvas of={AssistantStories.MinimalInput} />
-
----
-
-## Workspace Integration
-
-The assistant features specialized workspaces for different content types.
-
-### Document Editing
-When the assistant generates a document, it opens a dedicated editing workspace using the `RichTextEditor` component.
-
-<Canvas of={AssistantStories.DocumentEditing} />
-
-### Full Page View
-For focused work, the assistant can be expanded into a centered full-page layout.
-
-<Canvas of={AssistantStories.FullPage} />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Layout Context** — Use `useLayout()` to toggle the assistant's visibility and track its state across the application.
-> - **Demo Mode** — Use `demoMode={true}` for prototyping; it provides rich mock responses for documents, charts, and media.
-> - **Custom Responses** — Leverage `responseGenerator` to bridge the assistant with your backend or custom LLM logic.
-> - **Feature Flags** — Pass individual flags like `showHistory={false}` or `enableSearch={false}` to tailor the assistant's capabilities per use-case. Flags can be combined freely.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as AssistantStories from './xertica-assistant.stories';
+
+<Meta of={AssistantStories} />
+
+<Title />
+<Subtitle>An embedded AI-powered assistant panel for chat, document creation, and data analysis.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Feature Flags
+
+Each assistant capability can be individually toggled on or off via boolean props.
+All flags default to `true` for full backward compatibility.
+
+| Prop | Controls | Default |
+|---|---|---|
+| `showHistory` | Conversation history tab and collapsed icon | `true` |
+| `showFavorites` | Favorites tab and collapsed icon | `true` |
+| `enableAudioInput` | Voice recording and audio upload | `true` |
+| `enableFileAttachment` | File attachment button | `true` |
+| `enableDocumentCreation` | "Create document" action in the input menu | `true` |
+| `enablePodcastGeneration` | "Generate podcast" action and per-message button | `true` |
+| `enableSearch` | "Search" action in the input menu | `true` |
+
+### Chat Only
+
+All extra features disabled — the assistant provides only a basic text chat.
+
+<Canvas of={AssistantStories.ChatOnly} />
+
+### Minimal Input
+
+Only document creation and file attachment are enabled — ideal for document-focused workflows.
+
+<Canvas of={AssistantStories.MinimalInput} />
+
+---
+
+## Workspace Integration
+
+The assistant features specialized workspaces for different content types.
+
+### Document Editing
+When the assistant generates a document, it opens a dedicated editing workspace using the `RichTextEditor` component.
+
+<Canvas of={AssistantStories.DocumentEditing} />
+
+### Full Page View
+For focused work, the assistant can be expanded into a centered full-page layout.
+
+<Canvas of={AssistantStories.FullPage} />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Layout Context** — Use `useLayout()` to toggle the assistant's visibility and track its state across the application.
+> - **Demo Mode** — Use `demoMode={true}` for prototyping; it provides rich mock responses for documents, charts, and media.
+> - **Custom Responses** — Leverage `responseGenerator` to bridge the assistant with your backend or custom LLM logic.
+> - **Feature Flags** — Pass individual flags like `showHistory={false}` or `enableSearch={false}` to tailor the assistant's capabilities per use-case. Flags can be combined freely.

package/components/assistant/xertica-assistant/xertica-assistant.test.tsx

@@ -1,4 +1,5 @@
-import { render, screen, fireEvent, act, waitFor } from '@testing-library/react';
+import { screen, fireEvent, act, waitFor } from '@testing-library/react';
+import { renderWithProviders as render } from '../../../test/render';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { XerticaAssistant } from './xertica-assistant';
 import React from 'react';

package/components/blocks/card-patterns/card-patterns.mdx

@@ -1,123 +1,123 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as CardPatternsStories from './card-patterns.stories';
-
-<Meta of={CardPatternsStories} />
-
-<Title />
-<Subtitle>Pre-composed card blocks for dashboards and feature pages — plus matching skeleton variants for loading states.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Overview
-
-Six composed card components built exclusively from `ui/` primitives — no external dependencies. Each card has a matching `*Skeleton` companion that mirrors its layout with pulsing placeholders for use while data is loading.
-
-| Card                | Skeleton companion         |
-| ------------------- | -------------------------- |
-| `ActivityCard`      | `ActivityCardSkeleton`     |
-| `ProfileCard`       | `ProfileCardSkeleton`      |
-| `ProjectCard`       | `ProjectCardSkeleton`      |
-| `NotificationCard`  | `NotificationCardSkeleton` |
-| `QuickActionCard`   | `QuickActionCardSkeleton`  |
-| `FeatureCard`       | `FeatureCardSkeleton`      |
-
-> A matching `StatsCardSkeleton` is also available from `xertica-ui` (lives in `ui/stats-card/`).
-
----
-
-## Import
-
-```tsx
-// All cards and skeletons are re-exported from the root barrel
-import {
-  ActivityCard, ActivityCardSkeleton,
-  ProfileCard, ProfileCardSkeleton,
-  ProjectCard, ProjectCardSkeleton,
-  NotificationCard, NotificationCardSkeleton,
-  QuickActionCard, QuickActionCardSkeleton,
-  FeatureCard, FeatureCardSkeleton,
-} from 'xertica-ui';
-```
-
----
-
-## When to Use Cards
-
-- You need a recurring dashboard pattern (activity feed, KPI, project status, notifications) and don't want to re-compose it from scratch in every feature.
-- The pattern is stable and reused across multiple pages.
-
-## When NOT to Use Cards
-
-- One-off layouts specific to a single page — compose directly from `Card` and `ui/` primitives instead.
-- When the pattern has significant data-fetching logic — keep the block as a pure presentational component and handle state in the feature layer.
-
----
-
-## Loading-state pattern
-
-Always pair each card with its matching `*Skeleton` for loading states — never render a spinner or empty container while data fetches. The skeleton variants mirror the final layout closely, preventing layout shift when data arrives.
-
-```tsx
-function ActivityFeed() {
-  const { data: items, isLoading } = useActivityItems();
-
-  if (isLoading) return <ActivityCardSkeleton rows={5} />;
-  return <ActivityCard items={items!} />;
-}
-```
-
-For grids, render one skeleton per expected card:
-
-```tsx
-{isLoading ? (
-  <>
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-  </>
-) : (
-  data.map(item => <FeatureCard key={item.id} {...item} />)
-)}
-```
-
----
-
-## Skeleton configuration
-
-Each skeleton accepts props that tune which layout regions are rendered, so the placeholder matches the loaded state exactly.
-
-| Skeleton                   | Props                                       |
-| -------------------------- | ------------------------------------------- |
-| `ActivityCardSkeleton`     | `rows` (default `5`)                        |
-| `ProfileCardSkeleton`      | `showStats`, `showActions`                  |
-| `ProjectCardSkeleton`      | `memberCount` (default `3`)                 |
-| `NotificationCardSkeleton` | `rows` (default `4`), `showViewAll`         |
-| `QuickActionCardSkeleton`  | —                                           |
-| `FeatureCardSkeleton`      | `showAction`                                |
-| `StatsCardSkeleton`        | `showIcon`, `showTrend`                     |
-
-Set `rows={maxItems}` on list-style skeletons to match the loaded state's row count.
-
----
-
-## Stories
-
-<Stories />
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Import block components from `xertica-ui`** — they are included in the root barrel.
-> - **Pass all data as props** — never embed fetch calls inside block components.
-> - **Keep `maxItems` at a sensible limit (4–6)** to avoid overflow in fixed-height containers.
-> - **Always pair each card with its matching `*Skeleton`** — do not render a spinner or empty container while data fetches.
-> - **Skeleton row counts should match the expected data count** — pass `rows={maxItems}` to `ActivityCardSkeleton`/`NotificationCardSkeleton`.
-> - **For chart panels**, use `ChartCard` from `xertica-ui/ui` (not a block component) with any dashboard-ready chart as `children`.
-> - **`FeatureCard` badge wraps to a new line** when title + badge don't fit — this is intentional; do not constrain the container width to force inline layout.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as CardPatternsStories from './card-patterns.stories';
+
+<Meta of={CardPatternsStories} />
+
+<Title />
+<Subtitle>Pre-composed card blocks for dashboards and feature pages — plus matching skeleton variants for loading states.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Overview
+
+Six composed card components built exclusively from `ui/` primitives — no external dependencies. Each card has a matching `*Skeleton` companion that mirrors its layout with pulsing placeholders for use while data is loading.
+
+| Card                | Skeleton companion         |
+| ------------------- | -------------------------- |
+| `ActivityCard`      | `ActivityCardSkeleton`     |
+| `ProfileCard`       | `ProfileCardSkeleton`      |
+| `ProjectCard`       | `ProjectCardSkeleton`      |
+| `NotificationCard`  | `NotificationCardSkeleton` |
+| `QuickActionCard`   | `QuickActionCardSkeleton`  |
+| `FeatureCard`       | `FeatureCardSkeleton`      |
+
+> A matching `StatsCardSkeleton` is also available from `xertica-ui` (lives in `ui/stats-card/`).
+
+---
+
+## Import
+
+```tsx
+// All cards and skeletons are re-exported from the root barrel
+import {
+  ActivityCard, ActivityCardSkeleton,
+  ProfileCard, ProfileCardSkeleton,
+  ProjectCard, ProjectCardSkeleton,
+  NotificationCard, NotificationCardSkeleton,
+  QuickActionCard, QuickActionCardSkeleton,
+  FeatureCard, FeatureCardSkeleton,
+} from 'xertica-ui';
+```
+
+---
+
+## When to Use Cards
+
+- You need a recurring dashboard pattern (activity feed, KPI, project status, notifications) and don't want to re-compose it from scratch in every feature.
+- The pattern is stable and reused across multiple pages.
+
+## When NOT to Use Cards
+
+- One-off layouts specific to a single page — compose directly from `Card` and `ui/` primitives instead.
+- When the pattern has significant data-fetching logic — keep the block as a pure presentational component and handle state in the feature layer.
+
+---
+
+## Loading-state pattern
+
+Always pair each card with its matching `*Skeleton` for loading states — never render a spinner or empty container while data fetches. The skeleton variants mirror the final layout closely, preventing layout shift when data arrives.
+
+```tsx
+function ActivityFeed() {
+  const { data: items, isLoading } = useActivityItems();
+
+  if (isLoading) return <ActivityCardSkeleton rows={5} />;
+  return <ActivityCard items={items!} />;
+}
+```
+
+For grids, render one skeleton per expected card:
+
+```tsx
+{isLoading ? (
+  <>
+    <FeatureCardSkeleton showAction />
+    <FeatureCardSkeleton showAction />
+    <FeatureCardSkeleton showAction />
+  </>
+) : (
+  data.map(item => <FeatureCard key={item.id} {...item} />)
+)}
+```
+
+---
+
+## Skeleton configuration
+
+Each skeleton accepts props that tune which layout regions are rendered, so the placeholder matches the loaded state exactly.
+
+| Skeleton                   | Props                                       |
+| -------------------------- | ------------------------------------------- |
+| `ActivityCardSkeleton`     | `rows` (default `5`)                        |
+| `ProfileCardSkeleton`      | `showStats`, `showActions`                  |
+| `ProjectCardSkeleton`      | `memberCount` (default `3`)                 |
+| `NotificationCardSkeleton` | `rows` (default `4`), `showViewAll`         |
+| `QuickActionCardSkeleton`  | —                                           |
+| `FeatureCardSkeleton`      | `showAction`                                |
+| `StatsCardSkeleton`        | `showIcon`, `showTrend`                     |
+
+Set `rows={maxItems}` on list-style skeletons to match the loaded state's row count.
+
+---
+
+## Stories
+
+<Stories />
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Import block components from `xertica-ui`** — they are included in the root barrel.
+> - **Pass all data as props** — never embed fetch calls inside block components.
+> - **Keep `maxItems` at a sensible limit (4–6)** to avoid overflow in fixed-height containers.
+> - **Always pair each card with its matching `*Skeleton`** — do not render a spinner or empty container while data fetches.
+> - **Skeleton row counts should match the expected data count** — pass `rows={maxItems}` to `ActivityCardSkeleton`/`NotificationCardSkeleton`.
+> - **For chart panels**, use `ChartCard` from `xertica-ui/ui` (not a block component) with any dashboard-ready chart as `children`.
+> - **`FeatureCard` badge wraps to a new line** when title + badge don't fit — this is intentional; do not constrain the container width to force inline layout.

package/components/brand/branding/branding.mdx

@@ -1,27 +1,27 @@
-import { Meta, Title, Subtitle, Description, Canvas } from '@storybook/addon-docs/blocks';
-import * as BrandingStories from './branding.stories';
-
-<Meta of={BrandingStories} />
-
-<Title>Branding</Title>
-<Subtitle>Visual identity components for Xertica.ai applications.</Subtitle>
-
-<Description>
-The Branding module contains the official logos and icons for Xertica.ai. These components are designed to be theme-aware and responsive, ensuring consistent brand representation across all parts of the design system.
-</Description>
-
-## Logos
-
-### Full Logo
-The standard Xertica.ai logo, available in multiple color variants to suit different backgrounds and themes.
-
-<Canvas>
-  <BrandingStories.Logos />
-</Canvas>
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Variants** — Use `default` on light/neutral backgrounds, `white` on dark or colored backgrounds, and `theme` to inherit the surrounding text color. There is no `brand` or `dark` variant.
-> - **Scaling** — Always specify a height (`h-*`) and use `w-auto` to maintain the correct aspect ratio.
-> - **Icon Usage** — Use `XerticaXLogo` for favicon-like placements, profile avatars, or collapsed sidebars where horizontal space is limited.
+import { Meta, Title, Subtitle, Description, Canvas } from '@storybook/addon-docs/blocks';
+import * as BrandingStories from './branding.stories';
+
+<Meta of={BrandingStories} />
+
+<Title>Branding</Title>
+<Subtitle>Visual identity components for Xertica.ai applications.</Subtitle>
+
+<Description>
+The Branding module contains the official logos and icons for Xertica.ai. These components are designed to be theme-aware and responsive, ensuring consistent brand representation across all parts of the design system.
+</Description>
+
+## Logos
+
+### Full Logo
+The standard Xertica.ai logo, available in multiple color variants to suit different backgrounds and themes.
+
+<Canvas>
+  <BrandingStories.Logos />
+</Canvas>
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Variants** — Use `default` on light/neutral backgrounds, `white` on dark or colored backgrounds, and `theme` to inherit the surrounding text color. There is no `brand` or `dark` variant.
+> - **Scaling** — Always specify a height (`h-*`) and use `w-auto` to maintain the correct aspect ratio.
+> - **Icon Usage** — Use `XerticaXLogo` for favicon-like placements, profile avatars, or collapsed sidebars where horizontal space is limited.