xertica-ui 2.3.0 → 2.4.0

package/docs/guidelines.md

@@ -1,328 +1,330 @@
-# Design Guidelines & Tokens — Xertica UI
-
-> These guidelines define the visual language and architectural rules of Xertica UI. AI agents **must follow these strictly** — violations result in visually inconsistent, non-themeable output that breaks dark mode and brand cohesion.
-
----
-
-## 1. Color System
-
-### Token Architecture
-
-All colors are defined as CSS custom properties on `:root` and injected by `XerticaProvider`. Tailwind classes map to these variables, enabling both light and dark mode from a single source of truth.
-
-### Semantic Token Reference
-
-| Role                    | Background Class | Text Class                    | Use Case                              |
-| ----------------------- | ---------------- | ----------------------------- | ------------------------------------- |
-| **Page background**     | `bg-background`  | `text-foreground`             | Root page area                        |
-| **Card / Panel**        | `bg-card`        | `text-card-foreground`        | Content containers                    |
-| **Popover / Dropdown**  | `bg-popover`     | `text-popover-foreground`     | Overlays and menus                    |
-| **Muted / Subdued**     | `bg-muted`       | `text-muted-foreground`       | Backgrounds of panels, secondary text |
-| **Primary action**      | `bg-primary`     | `text-primary-foreground`     | Main CTA buttons, active states       |
-| **Secondary action**    | `bg-secondary`   | `text-secondary-foreground`   | Secondary buttons, badges             |
-| **Accent / Hover**      | `bg-accent`      | `text-accent-foreground`      | Hover states, highlighted rows        |
-| **Destructive / Error** | `bg-destructive` | `text-destructive-foreground` | Delete, revoke, danger actions        |
-| **Border (general)**    | `border-border`  | —                             | Dividers, card borders                |
-| **Border (forms)**      | `border-input`   | —                             | Input fields                          |
-| **Focus ring**          | `ring-ring`      | —                             | Keyboard focus indicators             |
-
-### Hard Rules
-
-```
-✅ bg-primary              → Primary action button backgrounds
-✅ text-muted-foreground   → Descriptive/secondary text
-✅ border-border           → All borders
-✅ bg-destructive          → Error / danger states
-✅ bg-success / bg-warning → Semantic status states
-
-❌ #3B82F6                 → Never hardcode hex values
-❌ rgb(59, 130, 246)       → Never use rgb() in className or style
-```
-
-> **Color rule nuance:** The restriction on generic Tailwind colors applies **contextually**:
->
-> - **Semantic/status contexts** (error states, warning banners, success indicators, status badges): always use semantic tokens (`bg-destructive`, `bg-success`, `bg-warning`, `text-muted-foreground`, etc.) so they respond to theme changes and dark mode.
-> - **Layout, spacing, and general UI** (custom components, Storybook stories, non-semantic decorative elements): standard Tailwind color utilities (`bg-blue-500`, `text-gray-700`, `bg-slate-100`) are acceptable when no semantic token maps to the intent.
-> - **Absolute prohibitions** (all contexts): raw hex values (`#3B82F6`), `rgb()`/`hsl()` in `className` or `style`, and `style={{ color: '...' }}` for theming purposes.
-
----
-
-## 2. Typography
-
-### Font Scale
-
-Typography uses CSS variable-based font sizing tokens. Always use the Tailwind type scale — never set font sizes in pixels directly.
-
-| Use Case              | Class                                                               |
-| --------------------- | ------------------------------------------------------------------- |
-| Page title            | `text-3xl font-bold tracking-tight`                                 |
-| Section heading       | `text-2xl font-semibold`                                            |
-| Card title            | `text-lg font-semibold` (or `text-sm font-medium` in compact cards) |
-| KPI value (StatsCard) | `text-2xl font-bold`                                                |
-| Body text             | `text-sm` (default)                                                 |
-| Descriptive / caption | `text-xs text-muted-foreground`                                     |
-| Code / mono           | `font-mono text-sm bg-muted px-1 rounded`                           |
-
-### Font Family
-
-The system uses the project's configured font (default: `Inter` via Google Fonts). Do not set `font-family` inline or via utility classes.
-
----
-
-## 3. Spacing & Layout
-
-### Spacing Scale
-
-Use Tailwind's spacing scale (based on `0.25rem` units). Common patterns:
-
-| Context                | Value   | Class                  |
-| ---------------------- | ------- | ---------------------- |
-| Card internal padding  | 24px    | `p-6`                  |
-| Compact panel padding  | 16px    | `p-4`                  |
-| Section gap (vertical) | 24px    | `space-y-6` or `gap-6` |
-| Inline element gap     | 8px     | `gap-2`                |
-| Icon-to-text gap       | 8px     | `gap-2`                |
-| Form field stack       | 8px     | `gap-2`                |
-| Form section gap       | 16–24px | `gap-4` to `gap-6`     |
-
-### Grid Patterns
-
-| Pattern              | Class                                                  |
-| -------------------- | ------------------------------------------------------ |
-| Stats grid (4 cols)  | `grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4` |
-| Dashboard dual panel | `grid grid-cols-1 lg:grid-cols-7 gap-4`                |
-| Form grid            | `grid grid-cols-1 md:grid-cols-2 gap-6`                |
-| Full-width field     | Add `col-span-full` or `md:col-span-2`                 |
-
-**Never use hardcoded pixel widths in grids.** Use the responsive grid column system.
-
----
-
-## 4. Border Radius
-
-Xertica UI uses a CSS variable for border radius: `--radius`. Use Tailwind utilities that map to this variable:
-
-| Size   | Class                        | Use                      |
-| ------ | ---------------------------- | ------------------------ |
-| Small  | `rounded-sm` (`--radius-sm`) | Badges, compact elements |
-| Medium | `rounded-md` (`--radius-md`) | Inputs, buttons          |
-| Large  | `rounded-lg` (`--radius-lg`) | Cards, panels            |
-| Full   | `rounded-full`               | Avatars, pills           |
-
-> **Never set border-radius in pixels (`rounded-[8px]`)** unless there's a very specific visual requirement.
-
----
-
-## 5. Component Composition Rules
-
-### Forms
-
-1. All forms **must** use `react-hook-form` + `zod`. No manual state validation.
-2. Form structure: `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` + `<FormControl>` + `<FormMessage>`.
-3. Error messages flow automatically through `<FormMessage>` — never render error `<span>` manually.
-4. Large entity forms use a 2-column grid: `grid grid-cols-1 md:grid-cols-2 gap-6`.
-5. Long fields (description, textarea, rich selects) use `col-span-full`.
-
-### Buttons & Actions
-
-1. **Submit actions** in modals: left-aligned in `CardFooter`.
-2. **Submit actions** on full pages: right-aligned at the bottom.
-3. **Destructive actions** always require a confirmation dialog (`AlertDialog`) before execution.
-4. **Icon-only buttons** use `size="icon"` on `<Button>`.
-5. Never place two primary (`variant="default"`) buttons side by side.
-
-### Tables & Data
-
-1. Use `<Table>`, `<TableHeader>`, `<TableBody>`, `<TableRow>`, `<TableHead>`, `<TableCell>`.
-2. Action menus in table rows use `<DropdownMenu>` with `<DropdownMenuTrigger asChild>`.
-3. Status values are always represented as `<Badge>` variants — never plain text.
-4. Filter inputs above tables use a relative container with an absolute icon: `relative` + `<Search className="absolute left-2.5 top-2.5" />` + `pl-8` on the input.
-
-### Cards
-
-1. Never create surfaces with raw `<div className="bg-white rounded-lg shadow border">`.
-2. If you need a container without a heading, use `<Card><CardContent>...</CardContent></Card>` — omit `CardHeader`.
-3. `CardFooter` must use `flex` with `justify-between` (for cancel/confirm pairs) or `justify-end` (for single confirm).
-
----
-
-## 6. Page Structure & Headers
-
-### PageHeader Component
-
-All pages **must** use the `PageHeader` component for their primary titles and descriptions. Do not use raw `<div>` or `<h2>` tags for page-level headers.
-
-1. **Title**: The `title` prop is mandatory and renders an H1-level heading.
-2. **Subtitle**: Use the `subtitle` prop for secondary descriptions.
-3. **Back Button**: If the page is a sub-view, use `backHref` (for routing) or `onBack` (for custom logic).
-4. **Actions**: Use the `actions` prop to pass primary CTA buttons (e.g., "New Content", "Save").
-
-```tsx
-<PageHeader
-  title="Users Management"
-  subtitle="Manage your system users and permissions"
-  actions={
-    <Button>
-      <Plus className="mr-2 h-4 w-4" /> Create User
-    </Button>
-  }
-/>
-```
-
-### Sidebar & Navigation
-
-The `Sidebar` is the primary navigation component. It is designed to be **autonomous** and persistent.
-
-1. **Autonomous Mode**: Works without `LayoutProvider` using internal state, but ideally integrated via `LayoutContext`.
-2. **Persistence**: The expansion state is saved in cookies (`sidebar_state`).
-3. **Shortcuts**: Use `Ctrl+B` (or `Cmd+B`) to toggle expansion globally.
-4. **Context Awareness**: Other components (Header, AudioPlayer) adjust their layout based on the sidebar's width and state via `LayoutContext`.
-
-### Standard Page Composition
-
-The typical page content area should follow this hierarchy:
-
-1. `ScrollArea` (to ensure the layout stays fixed)
-2. Outer padding (`p-2 sm:p-4 md:p-6`)
-3. Max-width container (`max-w-6xl mx-auto`)
-4. `PageHeader`
-5. Grid or Content blocks
-
----
-
-## 7. Interaction Patterns
-
-### Loading States
-
-Always render a skeleton placeholder — never a spinner — for data-bearing surfaces. Spinner-only loading is acceptable **only** for inline actions (button submit, "saving…" state).
-
-**For block-level cards**, use the matching `*Skeleton` companion that ships with every card pattern:
-
-```tsx
-import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
-
-{isLoading
-  ? <ActivityCardSkeleton rows={5} />
-  : <ActivityCard items={items} />}
-```
-
-Available skeleton companions: `ActivityCardSkeleton`, `ProfileCardSkeleton`, `ProjectCardSkeleton`, `NotificationCardSkeleton`, `QuickActionCardSkeleton`, `FeatureCardSkeleton`, `StatsCardSkeleton`.
-
-**For grids**, render one skeleton per expected card so layout shift is minimized when data arrives:
-
-```tsx
-{isLoading ? (
-  <>
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-  </>
-) : (
-  data.map(item => <FeatureCard key={item.id} {...item} />)
-)}
-```
-
-**For tables**, render skeleton `<TableRow>`s using the `<Skeleton>` primitive (`xertica-ui/ui`) sized to match each cell:
-
-```tsx
-{isLoading
-  ? Array.from({ length: 5 }).map((_, i) => (
-      <TableRow key={i}>
-        <TableCell><Skeleton className="h-3.5 w-28" /></TableCell>
-        <TableCell><Skeleton className="h-3.5 w-36" /></TableCell>
-        <TableCell><Skeleton className="h-5 w-16 rounded-full" /></TableCell>
-      </TableRow>
-    ))
-  : rows.map(...)}
-```
-
-**Pass `rows={maxItems}` to list-style skeletons** (`ActivityCardSkeleton`, `NotificationCardSkeleton`) so the placeholder height matches the loaded state's row count.
-
-### Empty States
-
-Use `<Empty>` for zero-state views (empty tables, no results). Always include an icon, a message, and a call-to-action.
-
-### Error States
-
-Destructive actions use `text-destructive` and `bg-destructive`. Form errors appear via `FormMessage`. API errors use `toast.error(message)` via Sonner.
-
----
-
-## 8. Internationalization (i18n)
-
-All user-facing strings in library components are translated via **`react-i18next`**. When authoring or consuming a Xertica UI component:
-
-### Always use translation hooks for UI strings
-
-```tsx
-import { useTranslation } from 'react-i18next';
-
-function MyButton() {
-  const { t } = useTranslation();
-  return <Button aria-label={t('common.save')}>{t('common.save')}</Button>;
-}
-```
-
-Never hardcode user-facing text — including `aria-label`, `placeholder`, `title`, toast messages, error text, and dropdown items.
-
-### Factory functions, not frozen constants
-
-When generating arrays of translated strings outside the React render cycle (mock data, fallback options), use **functions** so `i18n.t()` re-runs on every call:
-
-```tsx
-// ❌ Wrong — locked to whatever language was active at module load
-export const FALLBACK_OPTIONS = [i18n.t('feedback.notWhatIWanted')];
-
-// ✅ Correct — always returns the current language
-export function getFallbackOptions() {
-  return [i18n.t('feedback.notWhatIWanted')];
-}
-```
-
-Inside components, do the same with `useMemo([..., t])`.
-
-### Language-aware React Query keys
-
-Hooks whose response contains translated strings **must** include the active language in their `queryKey`:
-
-```tsx
-import { useLanguage } from 'xertica-ui/hooks';
-
-export function useFeatureCards() {
-  const { language } = useLanguage();
-  return useQuery({
-    queryKey: ['home', 'feature-cards', language],
-    queryFn: fetchFeatureCards,
-  });
-}
-```
-
-This ensures the cache flushes and refetches automatically when the user changes language — no page reload required.
-
-### Runtime-configurable language set
-
-The set of available languages is configured via `availableLanguages` on `<XerticaProvider>`. Read the current set from `useLanguage()`:
-
-```tsx
-const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
-```
-
-- **Never hardcode the language list** in custom settings UIs — iterate over `availableLanguages` so it stays in sync with the consumer's `<XerticaProvider>` config.
-- **`<LanguageSelector>` auto-hides** when `isMonolingual` is true. Never wrap it in a conditional yourself; pass `showWhenMonolingual` only when you explicitly need it visible.
-
----
-
-## 9. Accessibility
-
-All Xertica UI interactive components are built on Radix UI primitives, which provide:
-
-- Full keyboard navigation
-- ARIA roles and attributes
-- Focus management
-- Screen reader announcements
-
-Do not override or disable these behaviors. If adding custom interactive elements, ensure:
-
-- All interactive elements have visible focus indicators
-- Buttons have accessible labels (`aria-label` if icon-only) — and that `aria-label` must be passed through `t()` for translation
-- Form fields are associated with labels via `htmlFor` / `id`
+# Design Guidelines & Tokens — Xertica UI
+
+> These guidelines define the visual language and architectural rules of Xertica UI. AI agents **must follow these strictly** — violations result in visually inconsistent, non-themeable output that breaks dark mode and brand cohesion.
+
+---
+
+## 1. Color System
+
+### Token Architecture
+
+All colors are defined as CSS custom properties on `:root` and injected by `XerticaProvider`. Tailwind classes map to these variables, enabling both light and dark mode from a single source of truth.
+
+### Semantic Token Reference
+
+| Role                    | Background Class | Text Class                    | Use Case                              |
+| ----------------------- | ---------------- | ----------------------------- | ------------------------------------- |
+| **Page background**     | `bg-background`  | `text-foreground`             | Root page area                        |
+| **Card / Panel**        | `bg-card`        | `text-card-foreground`        | Content containers                    |
+| **Popover / Dropdown**  | `bg-popover`     | `text-popover-foreground`     | Overlays and menus                    |
+| **Muted / Subdued**     | `bg-muted`       | `text-muted-foreground`       | Backgrounds of panels, secondary text |
+| **Primary action**      | `bg-primary`     | `text-primary-foreground`     | Main CTA buttons, active states       |
+| **Secondary action**    | `bg-secondary`   | `text-secondary-foreground`   | Secondary buttons, badges             |
+| **Accent / Hover**      | `bg-accent`      | `text-accent-foreground`      | Hover states, highlighted rows        |
+| **Destructive / Error** | `bg-destructive` | `text-destructive-foreground` | Delete, revoke, danger actions        |
+| **Border (general)**    | `border-border`  | —                             | Dividers, card borders                |
+| **Border (forms)**      | `border-input`   | —                             | Input fields                          |
+| **Focus ring**          | `ring-ring`      | —                             | Keyboard focus indicators             |
+
+### Hard Rules
+
+```
+✅ bg-primary              → Primary action button backgrounds
+✅ text-muted-foreground   → Descriptive/secondary text
+✅ border-border           → All borders
+✅ bg-destructive          → Error / danger states
+✅ bg-success / bg-warning → Semantic status states
+
+❌ #3B82F6                 → Never hardcode hex values
+❌ rgb(59, 130, 246)       → Never use rgb() in className or style
+```
+
+> **Color rule nuance:** The restriction on generic Tailwind colors applies **contextually**:
+>
+> - **Semantic/status contexts** (error states, warning banners, success indicators, status badges): always use semantic tokens (`bg-destructive`, `bg-success`, `bg-warning`, `text-muted-foreground`, etc.) so they respond to theme changes and dark mode.
+> - **Layout, spacing, and general UI** (custom components, Storybook stories, non-semantic decorative elements): standard Tailwind color utilities (`bg-blue-500`, `text-gray-700`, `bg-slate-100`) are acceptable when no semantic token maps to the intent.
+> - **Absolute prohibitions** (all contexts): raw hex values (`#3B82F6`), `rgb()`/`hsl()` in `className` or `style`, and `style={{ color: '...' }}` for theming purposes.
+
+---
+
+## 2. Typography
+
+### Font Scale
+
+Typography uses CSS variable-based font sizing tokens. Always use the Tailwind type scale — never set font sizes in pixels directly.
+
+| Use Case              | Class                                                               |
+| --------------------- | ------------------------------------------------------------------- |
+| Page title            | `text-3xl font-bold tracking-tight`                                 |
+| Section heading       | `text-2xl font-semibold`                                            |
+| Card title            | `text-lg font-semibold` (or `text-sm font-medium` in compact cards) |
+| KPI value (StatsCard) | `text-2xl font-bold`                                                |
+| Body text             | `text-sm` (default)                                                 |
+| Descriptive / caption | `text-xs text-muted-foreground`                                     |
+| Code / mono           | `font-mono text-sm bg-muted px-1 rounded`                           |
+
+### Font Family
+
+The system uses the project's configured font (default: `Inter` via Google Fonts). Do not set `font-family` inline or via utility classes.
+
+---
+
+## 3. Spacing & Layout
+
+### Spacing Scale
+
+Use Tailwind's spacing scale (based on `0.25rem` units). Common patterns:
+
+| Context                | Value   | Class                  |
+| ---------------------- | ------- | ---------------------- |
+| Card internal padding  | 24px    | `p-6`                  |
+| Compact panel padding  | 16px    | `p-4`                  |
+| Section gap (vertical) | 24px    | `space-y-6` or `gap-6` |
+| Inline element gap     | 8px     | `gap-2`                |
+| Icon-to-text gap       | 8px     | `gap-2`                |
+| Form field stack       | 8px     | `gap-2`                |
+| Form section gap       | 16–24px | `gap-4` to `gap-6`     |
+
+### Grid Patterns
+
+| Pattern              | Class                                                  |
+| -------------------- | ------------------------------------------------------ |
+| Stats grid (4 cols)  | `grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4` |
+| Dashboard dual panel | `grid grid-cols-1 lg:grid-cols-7 gap-4`                |
+| Form grid            | `grid grid-cols-1 md:grid-cols-2 gap-6`                |
+| Full-width field     | Add `col-span-full` or `md:col-span-2`                 |
+
+**Never use hardcoded pixel widths in grids.** Use the responsive grid column system.
+
+---
+
+## 4. Border Radius
+
+Xertica UI uses a CSS variable for border radius: `--radius`. Use Tailwind utilities that map to this variable:
+
+| Size   | Class                        | Use                      |
+| ------ | ---------------------------- | ------------------------ |
+| Small  | `rounded-sm` (`--radius-sm`) | Badges, compact elements |
+| Medium | `rounded-md` (`--radius-md`) | Inputs, buttons          |
+| Large  | `rounded-lg` (`--radius-lg`) | Cards, panels            |
+| Full   | `rounded-full`               | Avatars, pills           |
+
+> **Never set border-radius in pixels (`rounded-[8px]`)** unless there's a very specific visual requirement.
+
+---
+
+## 5. Component Composition Rules
+
+### Forms
+
+1. All forms **must** use `react-hook-form` + `zod`. No manual state validation.
+2. Form structure: `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` + `<FormControl>` + `<FormMessage>`.
+3. Error messages flow automatically through `<FormMessage>` — never render error `<span>` manually.
+4. Large entity forms use a 2-column grid: `grid grid-cols-1 md:grid-cols-2 gap-6`.
+5. Long fields (description, textarea, rich selects) use `col-span-full`.
+
+### Buttons & Actions
+
+1. **Submit actions** in modals: left-aligned in `CardFooter`.
+2. **Submit actions** on full pages: right-aligned at the bottom.
+3. **Destructive actions** always require a confirmation dialog (`AlertDialog`) before execution.
+4. **Icon-only buttons** use `size="icon"` on `<Button>`.
+5. Never place two primary (`variant="default"`) buttons side by side.
+
+### Tables & Data
+
+1. Use `<Table>`, `<TableHeader>`, `<TableBody>`, `<TableRow>`, `<TableHead>`, `<TableCell>`.
+2. Action menus in table rows use `<DropdownMenu>` with `<DropdownMenuTrigger asChild>`.
+3. Status values are always represented as `<Badge>` variants — never plain text.
+4. Filter inputs above tables use a relative container with an absolute icon: `relative` + `<Search className="absolute left-2.5 top-2.5" />` + `pl-8` on the input.
+
+### Cards
+
+1. Never create surfaces with raw `<div className="bg-white rounded-lg shadow border">`.
+2. If you need a container without a heading, use `<Card><CardContent>...</CardContent></Card>` — omit `CardHeader`.
+3. `CardFooter` must use `flex` with `justify-between` (for cancel/confirm pairs) or `justify-end` (for single confirm).
+
+---
+
+## 6. Page Structure & Headers
+
+### PageHeader Component
+
+All pages **must** use the `PageHeader` component for their primary titles and descriptions. Do not use raw `<div>` or `<h2>` tags for page-level headers.
+
+1. **Title**: The `title` prop is mandatory and renders an H1-level heading.
+2. **Subtitle**: Use the `subtitle` prop for secondary descriptions.
+3. **Back Button**: If the page is a sub-view, use `backHref` (for routing) or `onBack` (for custom logic).
+4. **Actions**: Use the `actions` prop to pass primary CTA buttons (e.g., "New Content", "Save").
+
+```tsx
+<PageHeader
+  title="Users Management"
+  subtitle="Manage your system users and permissions"
+  actions={
+    <Button>
+      <Plus className="mr-2 h-4 w-4" /> Create User
+    </Button>
+  }
+/>
+```
+
+### Sidebar & Navigation
+
+The `Sidebar` is the primary navigation component. It is designed to be **autonomous** and persistent.
+
+1. **Autonomous Mode**: Works without `LayoutProvider` using internal state, but ideally integrated via `LayoutContext`.
+2. **Persistence**: The expansion state is saved in cookies (`sidebar_state`).
+3. **Shortcuts**: Use `Ctrl+B` (or `Cmd+B`) to toggle expansion globally.
+4. **Context Awareness**: Other components (Header, AudioPlayer) adjust their layout based on the sidebar's width and state via `LayoutContext`.
+
+### Standard Page Composition
+
+The typical page content area should follow this hierarchy:
+
+1. `ScrollArea` (to ensure the layout stays fixed)
+2. Outer padding (`p-2 sm:p-4 md:p-6`)
+3. Max-width container (`max-w-6xl mx-auto`)
+4. `PageHeader`
+5. Grid or Content blocks
+
+---
+
+## 7. Interaction Patterns
+
+### Loading States
+
+Always render a skeleton placeholder — never a spinner — for data-bearing surfaces. Spinner-only loading is acceptable **only** for inline actions (button submit, "saving…" state).
+
+**For block-level cards**, use the matching `*Skeleton` companion that ships with every card pattern:
+
+```tsx
+import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
+
+{
+  isLoading ? <ActivityCardSkeleton rows={5} /> : <ActivityCard items={items} />;
+}
+```
+
+Available skeleton companions: `ActivityCardSkeleton`, `ProfileCardSkeleton`, `ProjectCardSkeleton`, `NotificationCardSkeleton`, `QuickActionCardSkeleton`, `FeatureCardSkeleton`, `StatsCardSkeleton`.
+
+**For grids**, render one skeleton per expected card so layout shift is minimized when data arrives:
+
+```tsx
+{
+  isLoading ? (
+    <>
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+    </>
+  ) : (
+    data.map(item => <FeatureCard key={item.id} {...item} />)
+  );
+}
+```
+
+**For tables**, render skeleton `<TableRow>`s using the `<Skeleton>` primitive (`xertica-ui/ui`) sized to match each cell:
+
+```tsx
+{isLoading
+  ? Array.from({ length: 5 }).map((_, i) => (
+      <TableRow key={i}>
+        <TableCell><Skeleton className="h-3.5 w-28" /></TableCell>
+        <TableCell><Skeleton className="h-3.5 w-36" /></TableCell>
+        <TableCell><Skeleton className="h-5 w-16 rounded-full" /></TableCell>
+      </TableRow>
+    ))
+  : rows.map(...)}
+```
+
+**Pass `rows={maxItems}` to list-style skeletons** (`ActivityCardSkeleton`, `NotificationCardSkeleton`) so the placeholder height matches the loaded state's row count.
+
+### Empty States
+
+Use `<Empty>` for zero-state views (empty tables, no results). Always include an icon, a message, and a call-to-action.
+
+### Error States
+
+Destructive actions use `text-destructive` and `bg-destructive`. Form errors appear via `FormMessage`. API errors use `toast.error(message)` via Sonner.
+
+---
+
+## 8. Internationalization (i18n)
+
+All user-facing strings in library components are translated via **`react-i18next`**. When authoring or consuming a Xertica UI component:
+
+### Always use translation hooks for UI strings
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function MyButton() {
+  const { t } = useTranslation();
+  return <Button aria-label={t('common.save')}>{t('common.save')}</Button>;
+}
+```
+
+Never hardcode user-facing text — including `aria-label`, `placeholder`, `title`, toast messages, error text, and dropdown items.
+
+### Factory functions, not frozen constants
+
+When generating arrays of translated strings outside the React render cycle (mock data, fallback options), use **functions** so `i18n.t()` re-runs on every call:
+
+```tsx
+// ❌ Wrong — locked to whatever language was active at module load
+export const FALLBACK_OPTIONS = [i18n.t('feedback.notWhatIWanted')];
+
+// ✅ Correct — always returns the current language
+export function getFallbackOptions() {
+  return [i18n.t('feedback.notWhatIWanted')];
+}
+```
+
+Inside components, do the same with `useMemo([..., t])`.
+
+### Language-aware React Query keys
+
+Hooks whose response contains translated strings **must** include the active language in their `queryKey`:
+
+```tsx
+import { useLanguage } from 'xertica-ui/hooks';
+
+export function useFeatureCards() {
+  const { language } = useLanguage();
+  return useQuery({
+    queryKey: ['home', 'feature-cards', language],
+    queryFn: fetchFeatureCards,
+  });
+}
+```
+
+This ensures the cache flushes and refetches automatically when the user changes language — no page reload required.
+
+### Runtime-configurable language set
+
+The set of available languages is configured via `availableLanguages` on `<XerticaProvider>`. Read the current set from `useLanguage()`:
+
+```tsx
+const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
+```
+
+- **Never hardcode the language list** in custom settings UIs — iterate over `availableLanguages` so it stays in sync with the consumer's `<XerticaProvider>` config.
+- **`<LanguageSelector>` auto-hides** when `isMonolingual` is true. Never wrap it in a conditional yourself; pass `showWhenMonolingual` only when you explicitly need it visible.
+
+---
+
+## 9. Accessibility
+
+All Xertica UI interactive components are built on Radix UI primitives, which provide:
+
+- Full keyboard navigation
+- ARIA roles and attributes
+- Focus management
+- Screen reader announcements
+
+Do not override or disable these behaviors. If adding custom interactive elements, ensure:
+
+- All interactive elements have visible focus indicators
+- Buttons have accessible labels (`aria-label` if icon-only) — and that `aria-label` must be passed through `t()` for translation
+- Form fields are associated with labels via `htmlFor` / `id`