xertica-ui 1.9.4 → 1.9.5

package/assets/xertica-logo.svg

@@ -1,38 +1,38 @@
-<svg
-  fill="none"
-  preserveAspectRatio="xMidYMid meet"
-  viewBox="0 0 1543 289"
-  xmlns="http://www.w3.org/2000/svg"
->
-  <g id="Xertica.ai">
-    <path d="M1352.82 239.808V285.425H1304.73V239.808H1352.82Z" fill="#00BEFF" />
-    <path d="M814.8 284.848H766.711V77.4971H814.8V284.848Z" fill="#00BEFF" />
-    <path d="M1543 284.438H1514.2V160.28H1543V284.438Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M1432.83 157.796C1446.98 157.796 1459.14 162.515 1468.58 170.709V160.28H1497.38V284.438H1468.58V274.01C1459.14 282.451 1446.98 286.921 1432.83 286.921C1395.1 286.921 1368.29 260.352 1368.29 222.359C1368.29 184.616 1395.1 157.796 1432.83 157.796ZM1432.83 183.778C1410.79 183.778 1396.27 199.061 1396.27 222.359C1396.27 245.658 1410.79 260.94 1432.83 260.94C1454.63 260.94 1468.9 245.658 1468.9 222.359C1468.9 199.06 1454.63 183.778 1432.83 183.778Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M947.87 73.3516C1002.88 73.3516 1044.42 107.647 1053.57 159.234H1004.68C997.221 132.988 976.34 117.308 947.87 117.308C911.387 117.308 887.337 142.612 887.337 181.176C887.337 219.739 911.387 245.036 947.87 245.036C976.34 245.036 997.221 229.356 1004.68 203.109H1053.57C1044.47 254.701 1003.26 289 947.87 289C884.853 289 840.078 244.626 840.078 181.176C840.078 118.142 884.854 73.3516 947.87 73.3516Z" fill="#00BEFF" />
-    <path d="M88.4971 39.8242L157.353 142.191L83.5371 251.524L60.9277 284.854H0L96.3154 142.191L5.37695 7H66.3047L88.4971 39.8242Z" fill="#00BEFF" />
-    <path d="M254.314 284.855H193.387L151.914 223.71L182.548 178.551L254.314 284.855Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M1179.14 73.3477C1202.77 73.3477 1223.08 81.2286 1238.84 94.9121V77.4971H1286.94V284.847H1238.84V267.431C1223.09 281.528 1202.77 288.992 1179.14 288.992C1116.12 288.992 1071.35 244.622 1071.35 181.172C1071.35 118.139 1116.12 73.3478 1179.14 73.3477ZM1179.14 117.308C1142.66 117.308 1118.61 142.604 1118.61 181.172C1118.61 219.739 1142.66 245.035 1179.14 245.035C1215.21 245.035 1238.84 219.739 1238.84 181.172C1238.84 142.605 1215.21 117.308 1179.14 117.308Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M1543 145.383H1514.2V118.067H1543V145.383Z" fill="#00BEFF" />
-    <path d="M672.466 77.501H736.31V121.457H672.466V211.448C672.466 230.939 682.415 240.891 702.313 240.891H736.309V284.852H698.999C649.246 284.851 625.203 259.968 625.203 211.449V7H672.466V77.501Z" fill="#00BEFF" />
-    <path d="M814.8 52.6172H766.711V7H814.8V52.6172Z" fill="#00BEFF" />
-    <path 
-      clip-rule="evenodd"
-      d="M354.069 73.3516C417.086 73.3517 461.864 118.143 461.864 181.176C461.864 187.396 461.031 193.615 460.204 199.422H295.197C301.829 228.864 323.392 246.696 354.069 246.696C372.724 246.696 389.309 241.721 399.675 226.376H452.742C441.132 265.774 400.501 288.996 354.069 288.996C291.053 288.996 246.274 244.626 246.273 181.176C246.273 118.142 291.053 73.3516 354.069 73.3516ZM354.068 115.65C325.044 115.65 303.902 131.826 296.44 158.78H410.863C403.819 131.826 382.672 115.65 354.068 115.65Z"
-      fill="#00BEFF"
-      fill-rule="evenodd"
-    />
-    <path d="M596.957 121.453H562.962C543.064 121.453 533.114 131.409 533.114 150.899V284.847H485.852V150.899C485.852 102.38 509.894 77.4972 559.647 77.4971H596.957V121.453Z" fill="#00BEFF" />
-    <path d="M182.552 98.6992L151.922 53.3906L188.014 0H248.941L182.552 98.6992Z" fill="#00BEFF" />
-  </g>
+<svg
+  fill="none"
+  preserveAspectRatio="xMidYMid meet"
+  viewBox="0 0 1543 289"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <g id="Xertica.ai">
+    <path d="M1352.82 239.808V285.425H1304.73V239.808H1352.82Z" fill="#00BEFF" />
+    <path d="M814.8 284.848H766.711V77.4971H814.8V284.848Z" fill="#00BEFF" />
+    <path d="M1543 284.438H1514.2V160.28H1543V284.438Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M1432.83 157.796C1446.98 157.796 1459.14 162.515 1468.58 170.709V160.28H1497.38V284.438H1468.58V274.01C1459.14 282.451 1446.98 286.921 1432.83 286.921C1395.1 286.921 1368.29 260.352 1368.29 222.359C1368.29 184.616 1395.1 157.796 1432.83 157.796ZM1432.83 183.778C1410.79 183.778 1396.27 199.061 1396.27 222.359C1396.27 245.658 1410.79 260.94 1432.83 260.94C1454.63 260.94 1468.9 245.658 1468.9 222.359C1468.9 199.06 1454.63 183.778 1432.83 183.778Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M947.87 73.3516C1002.88 73.3516 1044.42 107.647 1053.57 159.234H1004.68C997.221 132.988 976.34 117.308 947.87 117.308C911.387 117.308 887.337 142.612 887.337 181.176C887.337 219.739 911.387 245.036 947.87 245.036C976.34 245.036 997.221 229.356 1004.68 203.109H1053.57C1044.47 254.701 1003.26 289 947.87 289C884.853 289 840.078 244.626 840.078 181.176C840.078 118.142 884.854 73.3516 947.87 73.3516Z" fill="#00BEFF" />
+    <path d="M88.4971 39.8242L157.353 142.191L83.5371 251.524L60.9277 284.854H0L96.3154 142.191L5.37695 7H66.3047L88.4971 39.8242Z" fill="#00BEFF" />
+    <path d="M254.314 284.855H193.387L151.914 223.71L182.548 178.551L254.314 284.855Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M1179.14 73.3477C1202.77 73.3477 1223.08 81.2286 1238.84 94.9121V77.4971H1286.94V284.847H1238.84V267.431C1223.09 281.528 1202.77 288.992 1179.14 288.992C1116.12 288.992 1071.35 244.622 1071.35 181.172C1071.35 118.139 1116.12 73.3478 1179.14 73.3477ZM1179.14 117.308C1142.66 117.308 1118.61 142.604 1118.61 181.172C1118.61 219.739 1142.66 245.035 1179.14 245.035C1215.21 245.035 1238.84 219.739 1238.84 181.172C1238.84 142.605 1215.21 117.308 1179.14 117.308Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M1543 145.383H1514.2V118.067H1543V145.383Z" fill="#00BEFF" />
+    <path d="M672.466 77.501H736.31V121.457H672.466V211.448C672.466 230.939 682.415 240.891 702.313 240.891H736.309V284.852H698.999C649.246 284.851 625.203 259.968 625.203 211.449V7H672.466V77.501Z" fill="#00BEFF" />
+    <path d="M814.8 52.6172H766.711V7H814.8V52.6172Z" fill="#00BEFF" />
+    <path 
+      clip-rule="evenodd"
+      d="M354.069 73.3516C417.086 73.3517 461.864 118.143 461.864 181.176C461.864 187.396 461.031 193.615 460.204 199.422H295.197C301.829 228.864 323.392 246.696 354.069 246.696C372.724 246.696 389.309 241.721 399.675 226.376H452.742C441.132 265.774 400.501 288.996 354.069 288.996C291.053 288.996 246.274 244.626 246.273 181.176C246.273 118.142 291.053 73.3516 354.069 73.3516ZM354.068 115.65C325.044 115.65 303.902 131.826 296.44 158.78H410.863C403.819 131.826 382.672 115.65 354.068 115.65Z"
+      fill="#00BEFF"
+      fill-rule="evenodd"
+    />
+    <path d="M596.957 121.453H562.962C543.064 121.453 533.114 131.409 533.114 150.899V284.847H485.852V150.899C485.852 102.38 509.894 77.4972 559.647 77.4971H596.957V121.453Z" fill="#00BEFF" />
+    <path d="M182.552 98.6992L151.922 53.3906L188.014 0H248.941L182.552 98.6992Z" fill="#00BEFF" />
+  </g>
 </svg>

package/assets/xertica-x-logo.svg

@@ -1,21 +1,21 @@
-<svg
-  fill="none"
-  preserveAspectRatio="xMidYMid meet"
-  viewBox="0 0 258 282"
-  xmlns="http://www.w3.org/2000/svg"
->
-  <g id="Xertica X">
-    <path 
-      d="M67.2666 0.0361328L89.7793 33.3447L159.63 137.228L84.7471 248.178L61.8115 282H0L97.7109 137.228L5.45508 0.0361328H67.2666Z" 
-      fill="#00BEFF" 
-    />
-    <path 
-      d="M258 282H196.185L154.114 219.951L185.192 174.123L258 282Z" 
-      fill="#00BEFF" 
-    />
-    <path 
-      d="M252.696 0.186523L185.042 100.142L154.106 54.0693L190.884 0L252.696 0.186523Z" 
-      fill="#00BEFF" 
-    />
-  </g>
+<svg
+  fill="none"
+  preserveAspectRatio="xMidYMid meet"
+  viewBox="0 0 258 282"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <g id="Xertica X">
+    <path 
+      d="M67.2666 0.0361328L89.7793 33.3447L159.63 137.228L84.7471 248.178L61.8115 282H0L97.7109 137.228L5.45508 0.0361328H67.2666Z" 
+      fill="#00BEFF" 
+    />
+    <path 
+      d="M258 282H196.185L154.114 219.951L185.192 174.123L258 282Z" 
+      fill="#00BEFF" 
+    />
+    <path 
+      d="M252.696 0.186523L185.042 100.142L154.106 54.0693L190.884 0L252.696 0.186523Z" 
+      fill="#00BEFF" 
+    />
+  </g>
 </svg>

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

@@ -211,11 +211,11 @@ export interface Message {
  */
 export interface Conversation {
   id: string;
-  titulo: string;
-  ultimaMensagem?: string;
+  title: string;
+  lastMessage?: string;
   timestamp: string;
-  favorita: boolean;
-  mensagens: Message[];
+  isFavorite: boolean;
+  messages: Message[];
 }
 
 /**
@@ -223,7 +223,7 @@ export interface Conversation {
  */
 export interface Suggestion {
   id: string;
-  texto: string;
+  text: string;
   icon?: React.ReactNode;
 }
 
@@ -550,10 +550,10 @@ export function XerticaAssistant({
   // ============================================================================
 
   const defaultSuggestions: Suggestion[] = [
-    { id: '1', texto: 'Me ajude a criar um documento profissional' },
-    { id: '2', texto: 'Buscar nos meus arquivos por "relatório"' },
-    { id: '3', texto: 'Resuma as conversas importantes desta semana' },
-    { id: '4', texto: 'Crie um podcast sobre o último projeto' },
+    { id: '1', text: 'Me ajude a criar um documento profissional' },
+    { id: '2', text: 'Buscar nos meus arquivos por "relatório"' },
+    { id: '3', text: 'Resuma as conversas importantes desta semana' },
+    { id: '4', text: 'Crie um podcast sobre o último projeto' },
   ];
 
   const sugestoes = propSuggestions ?? defaultSuggestions;
@@ -765,7 +765,7 @@ export function XerticaAssistant({
   const handleSelecionarConversa = (conversaId: string) => {
     const conversa = conversas.find(c => c.id === conversaId);
     if (conversa) {
-      setMensagens(conversa.mensagens);
+      setMensagens(conversa.messages);
       setConversaAtual(conversaId);
       setAbaSelecionada('chat');
     }
@@ -774,7 +774,7 @@ export function XerticaAssistant({
   const handleToggleFavoritaConversa = (conversaId: string) => {
     setConversas(prev =>
       prev.map(conv =>
-        conv.id === conversaId ? { ...conv, favorita: !conv.favorita } : conv
+        conv.id === conversaId ? { ...conv, isFavorite: !conv.isFavorite } : conv
       )
     );
   };
@@ -803,10 +803,10 @@ export function XerticaAssistant({
 
   const handleRichSuggestionClick = (suggestion: Suggestion) => {
     if (onRichAction) {
-      onRichAction(suggestion.id, suggestion.texto);
+      onRichAction(suggestion.id, suggestion.text);
     } else {
       // Fallback: send as message
-      handleEnviarMensagem(suggestion.texto);
+      handleEnviarMensagem(suggestion.text);
     }
     setShowMoreSuggestions(false);
   };
@@ -853,7 +853,7 @@ export function XerticaAssistant({
 
   const conversasFiltradas = conversas.filter(conversa => {
     if (abaSelecionada === 'favoritos') {
-      return conversa.favorita;
+      return conversa.isFavorite;
     }
     return true;
   });
@@ -1197,10 +1197,10 @@ export function XerticaAssistant({
                           {sugestoes.map((sugestao) => (
                             <button
                               key={sugestao.id}
-                              onClick={() => handleEnviarMensagem(sugestao.texto)}
+                              onClick={() => handleEnviarMensagem(sugestao.text)}
                               className="w-full p-3 text-left rounded-[var(--radius-card)] bg-muted text-foreground transition-colors duration-200 hover:bg-muted/80"
                             >
-                              {sugestao.texto}
+                              {sugestao.text}
                             </button>
                           ))}
 
@@ -1226,7 +1226,7 @@ export function XerticaAssistant({
                                     <div className="flex items-center gap-2">
                                       {sugestao.id.includes('chart') && <BarChart3 className="w-4 h-4 text-primary" />}
                                       {sugestao.id.includes('table') && <TableIcon className="w-4 h-4 text-primary" />}
-                                      <span className="font-medium">{sugestao.texto}</span>
+                                      <span className="font-medium">{sugestao.text}</span>
                                     </div>
                                   </button>
                                 ))
@@ -1767,7 +1767,7 @@ export function XerticaAssistant({
                             >
                               <div className="flex items-start justify-between mb-1">
                                 <h4 className="text-sm font-medium text-foreground truncate flex-1">
-                                  {conversa.titulo}
+                                  {conversa.title}
                                 </h4>
                                 <Button
                                   variant="ghost"
@@ -1781,14 +1781,14 @@ export function XerticaAssistant({
                                   <Heart
                                     className={cn(
                                       "w-3 h-3",
-                                      conversa.favorita ? "text-destructive fill-current" : "text-muted-foreground"
+                                      conversa.isFavorite ? "text-destructive fill-current" : "text-muted-foreground"
                                     )}
                                   />
                                 </Button>
                               </div>
-                              {conversa.ultimaMensagem && (
+                              {conversa.lastMessage && (
                                 <p className="text-sm text-muted-foreground truncate mb-1">
-                                  {conversa.ultimaMensagem}
+                                  {conversa.lastMessage}
                                 </p>
                               )}
                               <p className="text-sm text-muted-foreground">

package/components/brand/branding/branding.mdx

@@ -22,6 +22,6 @@ The standard Xertica.ai logo, available in multiple color variants to suit diffe
 ## AI Best Practices
 
 > [!IMPORTANT]
-> - **Variants** — Use the `white` variant on dark backgrounds and the `dark` or `brand` variant on light backgrounds. Use `theme` for automatic adjustment.
+> - **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.

package/components/brand/branding/branding.stories.tsx

@@ -19,12 +19,12 @@ export const Logos: StoryObj = {
         <h3 className="text-lg font-semibold text-muted-foreground border-b pb-2">Full Logo</h3>
         <div className="flex flex-wrap gap-8 items-center bg-muted/20 p-8 rounded-xl">
           <div className="space-y-2 text-center">
-            <XerticaLogo variant="brand" className="h-10 w-auto" />
-            <span className="text-xs text-muted-foreground">Brand</span>
+            <XerticaLogo variant="default" className="h-10 w-auto" />
+            <span className="text-xs text-muted-foreground">Default</span>
           </div>
           <div className="space-y-2 text-center">
-            <XerticaLogo variant="dark" className="h-10 w-auto" />
-            <span className="text-xs text-muted-foreground">Dark</span>
+            <XerticaLogo variant="theme" className="h-10 w-auto" />
+            <span className="text-xs text-muted-foreground">Theme</span>
           </div>
           <div className="space-y-2 text-center bg-slate-900 p-4 rounded-lg">
             <XerticaLogo variant="white" className="h-10 w-auto" />

package/components/brand/xertica-logo/XerticaLogo.stories.tsx

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { XerticaLogo } from './XerticaLogo';
+import React from 'react';
+
+const meta: Meta<typeof XerticaLogo> = {
+  title: 'Brand/XerticaLogo',
+  component: XerticaLogo,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'white', 'theme'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof XerticaLogo>;
+
+export const Default: Story = {
+  args: {
+    variant: 'default',
+    className: 'h-10 w-auto',
+  },
+};
+
+export const White: Story = {
+  args: {
+    variant: 'white',
+    className: 'h-10 w-auto',
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-slate-900 p-8 rounded-xl">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const Theme: Story = {
+  args: {
+    variant: 'theme',
+    className: 'h-10 w-auto text-blue-600',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8 p-6">
+      <div className="space-y-2">
+        <p className="text-xs text-muted-foreground font-mono">variant="default"</p>
+        <XerticaLogo variant="default" className="h-10 w-auto" />
+      </div>
+      <div className="space-y-2 bg-slate-900 p-6 rounded-xl">
+        <p className="text-xs text-slate-400 font-mono">variant="white"</p>
+        <XerticaLogo variant="white" className="h-10 w-auto" />
+      </div>
+      <div className="space-y-2">
+        <p className="text-xs text-muted-foreground font-mono">variant="theme" (text-blue-600)</p>
+        <XerticaLogo variant="theme" className="h-10 w-auto text-blue-600" />
+      </div>
+      <div className="space-y-2">
+        <p className="text-xs text-muted-foreground font-mono">color="#e11d48" (direct override)</p>
+        <XerticaLogo color="#e11d48" className="h-10 w-auto" />
+      </div>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 p-6 items-start">
+      <XerticaLogo className="h-6 w-auto" />
+      <XerticaLogo className="h-8 w-auto" />
+      <XerticaLogo className="h-10 w-auto" />
+      <XerticaLogo className="h-14 w-auto" />
+    </div>
+  ),
+};

package/components/brand/xertica-logo/xertica-logo.mdx

@@ -0,0 +1,56 @@
+import { Meta, Title, Subtitle, Description } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand/XerticaLogo" />
+
+<Title>XerticaLogo</Title>
+<Subtitle>Full Xertica.ai wordmark (X-symbol + text) as a responsive SVG.</Subtitle>
+
+---
+
+## Overview
+
+`XerticaLogo` renders the complete Xertica brand identity — the X symbol alongside the wordmark text. It adapts to different backgrounds through its `variant` prop and supports a direct `color` override for edge cases.
+
+```tsx
+import { XerticaLogo } from 'xertica-ui';
+
+<XerticaLogo className="h-8 w-auto" />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'white' \| 'theme'` | `'default'` | Color variant. `default` uses `var(--primary)`, `white` forces white fill, `theme` inherits `currentColor`. |
+| `color` | `string` | — | Direct color override (CSS color value). Overrides `variant`. |
+| `className` | `string` | `'w-auto h-8'` | Additional CSS classes applied to the SVG element. |
+
+---
+
+## Variants
+
+```tsx
+// Light background — primary brand color
+<XerticaLogo variant="default" className="h-8 w-auto" />
+
+// Dark background — white fill
+<XerticaLogo variant="white" className="h-8 w-auto" />
+
+// Inherits text color from parent (useful on colored backgrounds)
+<XerticaLogo variant="theme" className="h-8 w-auto" />
+
+// Direct color override
+<XerticaLogo color="#1D4ED8" className="h-8 w-auto" />
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Variant selection** — Use `default` on light/neutral backgrounds, `white` on dark or colored backgrounds, and `theme` when the logo should inherit the surrounding text color.
+> - **Sizing** — Always set a height (`h-*`) and use `w-auto` to preserve the correct aspect ratio. Never set both width and height to fixed values.
+> - **Icon-only contexts** — Use `XerticaXLogo` instead of `XerticaLogo` in compact spaces such as collapsed sidebars, favicons, or avatars.
+> - **No `dark` or `brand` variants** — These are not valid. Use `default` for brand-color rendering.

package/components/brand/xertica-logo/xertica-logo.test.tsx

@@ -20,7 +20,7 @@ describe('XerticaLogo', () => {
     // Verification depends on implementation (e.g. fill color)
     expect(container.querySelector('svg')).toBeInTheDocument();
     
-    rerender(<XerticaLogo variant="brand" />);
+    rerender(<XerticaLogo variant="theme" />);
     expect(container.querySelector('svg')).toBeInTheDocument();
   });
 });

package/components/brand/xertica-provider/XerticaProvider.tsx

@@ -31,11 +31,12 @@ interface XerticaProviderProps {
  * This component aggregates all necessary context providers. It should be placed at the 
  * root of your application, ideally inside the App component.
  */
-export function XerticaProvider({ 
-    children
+export function XerticaProvider({
+    children,
+    googleMapsApiKey,
 }: XerticaProviderProps) {
     return (
-        <GoogleMapsLoaderProvider>
+        <GoogleMapsLoaderProvider apiKey={googleMapsApiKey}>
             <LayoutProvider>
                 <TooltipProvider>
                     {children}

package/components/brand/xertica-provider/xertica-provider.mdx

@@ -32,9 +32,13 @@ function App() {
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | **Required** | The application content |
-
-> **Note**: As of version 1.6+, brand colors, API keys, and language state are managed independently or via CSS tokens to increase modularity and performance.
+| `children` | `ReactNode` | **Required** | The application content to be wrapped by all providers. |
+| `googleMapsApiKey` | `string` | — | Google Maps JavaScript API key. Passed to `GoogleMapsLoaderProvider` to enable map components (`SimpleMap`, `MapShowcase`, etc.). |
+| `apiKey` | `string` | — | Gemini / AI service API key for AI-powered features. Accepted by the provider but not yet wired to a default context — pass explicitly to AI components that require it. |
+| `defaultBrandTheme` | `string` | — | Initial theme name (e.g., `'default'`, `'dark'`). Intended for future theme-switching support. |
+| `primaryColor` | `string` | — | Hex color override for the primary brand token. When set, updates `--primary` at runtime. |
+| `useCustomTokens` | `boolean` | `false` | When `true`, skips injecting the library's default CSS token set, relying entirely on the host application's tokens. |
+| `disableDarkMode` | `boolean` | `false` | When `true`, prevents the library from applying dark-mode class or media-query overrides. |
 
 ---
 

package/components/brand/xertica-xlogo/XerticaXLogo.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { XerticaXLogo } from './XerticaXLogo';
+import React from 'react';
+
+const meta: Meta<typeof XerticaXLogo> = {
+  title: 'Brand/XerticaXLogo',
+  component: XerticaXLogo,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'white', 'theme'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof XerticaXLogo>;
+
+export const Default: Story = {
+  args: {
+    variant: 'default',
+    className: 'h-12 w-12',
+  },
+};
+
+export const White: Story = {
+  args: {
+    variant: 'white',
+    className: 'h-12 w-12',
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-slate-900 p-8 rounded-xl">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const Theme: Story = {
+  args: {
+    variant: 'theme',
+    className: 'h-12 w-12 text-blue-600',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-10 p-6 items-end">
+      <div className="space-y-2 text-center">
+        <XerticaXLogo variant="default" className="h-12 w-12" />
+        <p className="text-xs text-muted-foreground">default</p>
+      </div>
+      <div className="space-y-2 text-center bg-slate-900 p-4 rounded-xl">
+        <XerticaXLogo variant="white" className="h-12 w-12" />
+        <p className="text-xs text-slate-400">white</p>
+      </div>
+      <div className="space-y-2 text-center">
+        <XerticaXLogo variant="theme" className="h-12 w-12 text-blue-600" />
+        <p className="text-xs text-muted-foreground">theme</p>
+      </div>
+      <div className="space-y-2 text-center">
+        <XerticaXLogo color="#e11d48" className="h-12 w-12" />
+        <p className="text-xs text-muted-foreground">color override</p>
+      </div>
+    </div>
+  ),
+};
+
+export const CollapsedSidebarSlot: Story = {
+  render: () => (
+    <div className="flex items-center justify-center w-20 h-16 bg-sidebar border-r border-border">
+      <XerticaXLogo className="h-7 w-7" />
+    </div>
+  ),
+};

package/components/brand/xertica-xlogo/xertica-xlogo.mdx

@@ -0,0 +1,55 @@
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand/XerticaXLogo" />
+
+<Title>XerticaXLogo</Title>
+<Subtitle>Compact X-symbol mark for favicons, avatars, and collapsed sidebar slots.</Subtitle>
+
+---
+
+## Overview
+
+`XerticaXLogo` renders only the X-symbol portion of the Xertica identity. It shares the same prop API as `XerticaLogo` and is the preferred choice wherever horizontal space is constrained.
+
+```tsx
+import { XerticaXLogo } from 'xertica-ui';
+
+<XerticaXLogo className="h-8 w-8" />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'white' \| 'theme'` | `'default'` | Color variant. `default` uses `var(--primary)`, `white` forces white fill, `theme` inherits `currentColor`. |
+| `color` | `string` | — | Direct color override. Overrides `variant`. |
+| `className` | `string` | `'w-auto h-8'` | Additional CSS classes applied to the SVG element. |
+
+---
+
+## Usage Examples
+
+```tsx
+// Default — primary color
+<XerticaXLogo className="h-10 w-10" />
+
+// On a dark background
+<XerticaXLogo variant="white" className="h-10 w-10" />
+
+// Inherits current text color
+<XerticaXLogo variant="theme" className="h-10 w-10 text-blue-600" />
+
+// Collapsed sidebar icon slot
+<XerticaXLogo className="h-6 w-6 shrink-0" />
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Square sizing** — Unlike the full logo, set both width and height to the same value (e.g., `h-10 w-10`) since the X symbol has a near-square aspect ratio (viewBox `0 0 258 282`).
+> - **Favicon** — Export as a PNG at 32×32 and 192×192 for web manifest icons; do not use the SVG component directly in `<link rel="icon">`.
+> - **Collapsed sidebar** — Replace the full `XerticaLogo` with `XerticaXLogo` when `sidebarExpanded === false` to avoid clipping.