xertica-ui 2.5.3 → 2.7.0

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/blocks/index.ts

@@ -1 +1,2 @@
 export * from './card-patterns';
+export * from './auth';

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.

package/components/brand/language-selector/language-selector.mdx

@@ -1,126 +1,126 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as LanguageSelectorStories from './language-selector.stories';
-
-<Meta of={LanguageSelectorStories} />
-
-<Title />
-<Subtitle>A self-contained dropdown for switching the application language, wired to LanguageContext and i18next.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage
-
-```tsx
-import { LanguageSelector } from 'xertica-ui/brand';
-
-<LanguageSelector />
-```
-
-The component reads the current language from `LanguageContext` and changes it via `setLanguage()` — which persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache so that mock/API responses also refresh in the new language.
-
-### Minimal variant (short label only)
-
-```tsx
-<LanguageSelector variant="minimal" showIcon={false} />
-```
-
-### Force-visible in a monolingual app
-
-By default, the selector renders `null` when only one language is configured. Pass `showWhenMonolingual` to render anyway:
-
-```tsx
-<LanguageSelector showWhenMonolingual />
-```
-
----
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `variant` | `'default' \| 'minimal'` | `'default'` | `minimal` uses the short label (e.g. `PT`, `EN`) instead of the full name |
-| `showIcon` | `boolean` | `true` | Show the globe icon next to the label |
-| `showLabel` | `boolean` | `false` | Reserved for future use — currently no visual effect |
-| `className` | `string` | `''` | Additional CSS classes applied to the trigger button |
-| `showWhenMonolingual` | `boolean` | `false` | Render the selector even when only one language is configured (would otherwise auto-hide) |
-
-> The component does **not** accept `initialLanguage` or `onLanguageChange`. Language state lives in `LanguageContext` — read or change it via `useLanguage()`.
-
----
-
-## Supported Languages
-
-By default, the selector exposes the three languages that ship with the library:
-
-| Code | Full label | Short label |
-|---|---|---|
-| `pt-BR` | Português (BR) | PT |
-| `en` | English | EN |
-| `es` | Español | ES |
-
-**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` (or `<LanguageProvider>`) to add, remove, or restrict the languages shown.
-
-### Add a new language
-
-```tsx
-import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
-import fr from './locales/fr.json';
-
-<XerticaProvider
-  availableLanguages={[
-    ...DEFAULT_LANGUAGES,
-    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
-  ]}
->
-  <LanguageSelector />
-  {/* French now appears in the dropdown; its strings are auto-registered with i18next */}
-</XerticaProvider>
-```
-
-### Monolingual app (no selector visible)
-
-```tsx
-<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
-  <LanguageSelector />
-  {/* Renders nothing — there is nothing to switch to */}
-</XerticaProvider>
-```
-
-### Programmatic access
-
-```tsx
-import { useLanguage } from 'xertica-ui';
-
-function MyComponent() {
-  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
-  // ...
-}
-```
-
----
-
-## Behavior
-
-- **Reads** `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
-- **Persists** the selected language to `localStorage` under the key `xertica_language`
-- **Notifies** `i18next` via `i18n.changeLanguage()` — all components using `useTranslation()` re-render immediately
-- **Invalidates** the React Query cache so mock/API responses translated via `i18n.t()` are refetched in the new language
-- **Auto-hides** when `isMonolingual === true` (single-language apps)
-- **Labels**: known codes (`pt-BR`, `en`, `es`) use translated labels from `assistant.languageSelector.*`. Custom codes fall back to the `label` passed in the `LanguageDefinition`.
-- **Short labels**: when `variant="minimal"`, uses the `shortLabel` from the `LanguageDefinition`, or `code.slice(0, 2).toUpperCase()` as fallback
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
-> - **Placement**: Typically inside `Header` actions (`showLanguageSelector` prop) or the `Sidebar` footer.
-> - **`<LanguageProvider>` is required**: `LanguageSelector` calls `useLanguage()` and throws when rendered outside a `LanguageProvider`. `<XerticaProvider>` provides it automatically.
-> - **Do NOT pass `initialLanguage` or `onLanguageChange`** — these props were removed. Use `useLanguage()` to read or change the language programmatically.
-> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Use `showWhenMonolingual` only if you explicitly need it visible.
-> - **One instance per layout shell** — multiple selectors create UX confusion. Place a single instance in `Header` or `Sidebar`.
-> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as LanguageSelectorStories from './language-selector.stories';
+
+<Meta of={LanguageSelectorStories} />
+
+<Title />
+<Subtitle>A self-contained dropdown for switching the application language, wired to LanguageContext and i18next.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage
+
+```tsx
+import { LanguageSelector } from 'xertica-ui/brand';
+
+<LanguageSelector />
+```
+
+The component reads the current language from `LanguageContext` and changes it via `setLanguage()` — which persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache so that mock/API responses also refresh in the new language.
+
+### Minimal variant (short label only)
+
+```tsx
+<LanguageSelector variant="minimal" showIcon={false} />
+```
+
+### Force-visible in a monolingual app
+
+By default, the selector renders `null` when only one language is configured. Pass `showWhenMonolingual` to render anyway:
+
+```tsx
+<LanguageSelector showWhenMonolingual />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'minimal'` | `'default'` | `minimal` uses the short label (e.g. `PT`, `EN`) instead of the full name |
+| `showIcon` | `boolean` | `true` | Show the globe icon next to the label |
+| `showLabel` | `boolean` | `false` | Reserved for future use — currently no visual effect |
+| `className` | `string` | `''` | Additional CSS classes applied to the trigger button |
+| `showWhenMonolingual` | `boolean` | `false` | Render the selector even when only one language is configured (would otherwise auto-hide) |
+
+> The component does **not** accept `initialLanguage` or `onLanguageChange`. Language state lives in `LanguageContext` — read or change it via `useLanguage()`.
+
+---
+
+## Supported Languages
+
+By default, the selector exposes the three languages that ship with the library:
+
+| Code | Full label | Short label |
+|---|---|---|
+| `pt-BR` | Português (BR) | PT |
+| `en` | English | EN |
+| `es` | Español | ES |
+
+**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` (or `<LanguageProvider>`) to add, remove, or restrict the languages shown.
+
+### Add a new language
+
+```tsx
+import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
+import fr from './locales/fr.json';
+
+<XerticaProvider
+  availableLanguages={[
+    ...DEFAULT_LANGUAGES,
+    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
+  ]}
+>
+  <LanguageSelector />
+  {/* French now appears in the dropdown; its strings are auto-registered with i18next */}
+</XerticaProvider>
+```
+
+### Monolingual app (no selector visible)
+
+```tsx
+<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
+  <LanguageSelector />
+  {/* Renders nothing — there is nothing to switch to */}
+</XerticaProvider>
+```
+
+### Programmatic access
+
+```tsx
+import { useLanguage } from 'xertica-ui';
+
+function MyComponent() {
+  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
+  // ...
+}
+```
+
+---
+
+## Behavior
+
+- **Reads** `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
+- **Persists** the selected language to `localStorage` under the key `xertica_language`
+- **Notifies** `i18next` via `i18n.changeLanguage()` — all components using `useTranslation()` re-render immediately
+- **Invalidates** the React Query cache so mock/API responses translated via `i18n.t()` are refetched in the new language
+- **Auto-hides** when `isMonolingual === true` (single-language apps)
+- **Labels**: known codes (`pt-BR`, `en`, `es`) use translated labels from `assistant.languageSelector.*`. Custom codes fall back to the `label` passed in the `LanguageDefinition`.
+- **Short labels**: when `variant="minimal"`, uses the `shortLabel` from the `LanguageDefinition`, or `code.slice(0, 2).toUpperCase()` as fallback
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Placement**: Typically inside `Header` actions (`showLanguageSelector` prop) or the `Sidebar` footer.
+> - **`<LanguageProvider>` is required**: `LanguageSelector` calls `useLanguage()` and throws when rendered outside a `LanguageProvider`. `<XerticaProvider>` provides it automatically.
+> - **Do NOT pass `initialLanguage` or `onLanguageChange`** — these props were removed. Use `useLanguage()` to read or change the language programmatically.
+> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Use `showWhenMonolingual` only if you explicitly need it visible.
+> - **One instance per layout shell** — multiple selectors create UX confusion. Place a single instance in `Header` or `Sidebar`.
+> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.

package/components/brand/theme-toggle/theme-toggle.mdx

@@ -1,47 +1,47 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ThemeToggleStories from './theme-toggle.stories';
-
-<Meta of={ThemeToggleStories} />
-
-<Title />
-<Subtitle>Light/dark mode switcher that operates directly on the document root class.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage
-
-```tsx
-import { ThemeToggle } from 'xertica-ui/brand';
-
-<ThemeToggle />
-```
-
-### With Label
-
-```tsx
-<ThemeToggle showLabel size="md" variant="outline" />
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
-| `variant` | `'default' \| 'outline' \| 'ghost'` | `'ghost'` | Button visual variant |
-| `showLabel` | `boolean` | `false` | Show a text label next to the icon |
-| `className` | `string` | `''` | Extra CSS classes |
-
-## Behavior
-
-`ThemeToggle` reads and writes the `dark` class on `document.documentElement` directly. It does **not** depend on any context provider — it is fully self-contained and safe to use anywhere in the tree.
-
-## AI Rules
-
-> [!IMPORTANT]
-> - **Placement**: Typically placed in the `Sidebar` footer or the `Header` actions area.
-> - **Do not use raw JS** — never toggle dark mode manually. Always use this component or `ThemeToggle`.
-> - **One instance only** per layout — placing multiple toggles causes conflicting state.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ThemeToggleStories from './theme-toggle.stories';
+
+<Meta of={ThemeToggleStories} />
+
+<Title />
+<Subtitle>Light/dark mode switcher that operates directly on the document root class.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage
+
+```tsx
+import { ThemeToggle } from 'xertica-ui/brand';
+
+<ThemeToggle />
+```
+
+### With Label
+
+```tsx
+<ThemeToggle showLabel size="md" variant="outline" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `variant` | `'default' \| 'outline' \| 'ghost'` | `'ghost'` | Button visual variant |
+| `showLabel` | `boolean` | `false` | Show a text label next to the icon |
+| `className` | `string` | `''` | Extra CSS classes |
+
+## Behavior
+
+`ThemeToggle` reads and writes the `dark` class on `document.documentElement` directly. It does **not** depend on any context provider — it is fully self-contained and safe to use anywhere in the tree.
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Placement**: Typically placed in the `Sidebar` footer or the `Header` actions area.
+> - **Do not use raw JS** — never toggle dark mode manually. Always use this component or `ThemeToggle`.
+> - **One instance only** per layout — placing multiple toggles causes conflicting state.