# AI Agent Usage Manual — Xertica UI

> This document is addressed **exclusively to AI agents** (LLMs) operating on projects that use `xertica-ui`. Developers may also read it to understand constraints the system enforces.

---

## 1. Knowledge Extraction Protocol

Your knowledge about the library must come from these sources, in priority order:

1. **`docs/llms.md`** — Start here. It contains the component catalog index and critical rules.
2. **`docs/components/*.md`** — Component-specific documentation with full prop tables and examples.
3. **`docs/patterns/*.md`** — Pre-validated layout patterns for common page types.
4. **`components/ui/*.tsx` source files** — Read the TSDoc annotations on interfaces before using any component.

> **Reading source code is for understanding prop contracts, not for remixing implementations.** Do not derive alternative versions of components from the source.

---

## 2. Strict Rules

### 2.1 Native HTML Elements Are Forbidden for UI Surfaces

| ❌ Forbidden             | ✅ Required                            |
| ------------------------ | -------------------------------------- |
| `<button>`               | `<Button>` from `xertica-ui`           |
| `<input>`                | `<Input>` from `xertica-ui`            |
| `<div className="card">` | `<Card>` from `xertica-ui`             |
| `<a>` for actions        | `<Button asChild>` wrapping a `<Link>` |
| `<select>`               | `<Select>` from `xertica-ui`           |
| `<textarea>`             | `<Textarea>` from `xertica-ui`         |

If a validation engine reports `<button> inserted illegally`, it means you used a native HTML element. The fix is to replace it with the `xertica-ui` counterpart — **not to wrap it**.

### 2.2 SVGs and Icons

Never generate raw SVG markup (`<svg><path .../></svg>`). Always use `lucide-react`:

```tsx
// ❌ Never do this
<svg xmlns="http://www.w3.org/2000/svg" ...><path .../></svg>

// ✅ Always do this
import { Settings, Home, LogOut } from 'lucide-react';
<Settings className="w-4 h-4" />
```

The standard icon size in UI controls is `w-4 h-4` (`16px`). In hero or empty states, `w-8 h-8` or `w-12 h-12` is acceptable.

### 2.3 Color Tokens — Context-Dependent Rules

Color usage depends on the **semantic context** of the element:

**Always forbidden (all contexts):**

```tsx
// ❌ Never use raw hex or rgb() values
<div style={{ backgroundColor: '#3B82F6' }}>
<div style={{ color: 'rgb(59, 130, 246)' }}>
```

**Required for semantic/status contexts** (errors, warnings, success states, status badges, danger actions):

```tsx
// ❌ Wrong — non-semantic color for a semantic state
<div className="bg-red-500 text-white">Error</div>

// ✅ Required — semantic token responds to theme and dark mode
<div className="bg-destructive text-destructive-foreground">Error</div>
```

**Acceptable for layout and general non-semantic UI** (custom components, Storybook stories, decorative elements where no semantic token applies):

```tsx
// ✅ Acceptable — non-semantic context, no theme dependency needed
<div className="bg-blue-500 text-white border-gray-200">Custom UI</div>

// ✅ Required for semantic contexts
<div className="bg-primary text-primary-foreground border-border">Action</div>
```

The only additional exception is within chart configurations (`recharts`) where literal colors may be required for data series styling.

### 2.4 Prop Inference

Do not assume all native HTML props are forwarded by a Xertica UI component. Some are intentionally blocked by the component's design. Always check the prop table in the component's `.md` file before using a prop.

---

## 3. Component Validation Checklist

Before generating code that uses a Xertica UI component, verify:

- [ ] The component is exported from `xertica-ui` (check `docs/llms.md` catalog)
- [ ] All required props are provided (check the component's `## Props` table)
- [ ] All passed props are documented — do not invent props
- [ ] Icons come from `lucide-react`, not inline SVG
- [ ] Colors use semantic token classes, not raw values
- [ ] The component is not re-implemented from scratch with Tailwind classes

---

## 4. Layout System Rules

The layout state is managed globally by `LayoutContext`. **Never manage sidebar or layout state locally.**

```tsx
import { useLayout } from 'xertica-ui/hooks';

const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
```

The `sidebarWidth` value drives `padding-left` on the main content container:

```tsx
<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
```

Do not hardcode `pl-64` or `padding-left: 280px`. Read `docs/layout.md` for details.

---

## 5. Form Validation Rules

Forms must use `react-hook-form` + `zod`. Never implement manual validation logic.

```tsx
// ❌ Never do this
const [error, setError] = useState('');
if (!email.includes('@')) setError('Invalid email');

// ✅ Always do this
const schema = z.object({ email: z.string().email() });
// Errors flow automatically to <FormMessage />
```

See `docs/patterns/form.md` for the validated full form pattern.

---

## 6. Routing Rules

The library supports `react-router-dom` v6. Pass router hooks directly to components that need them:

```tsx
import { useNavigate, useLocation } from 'react-router-dom';

const navigate = useNavigate();
const location = useLocation();

<Sidebar navigate={navigate} location={location} ... />
```

When mocking these in previews/tests, pass empty functions — never string literals:

```tsx
// ❌ Wrong
<Sidebar navigate="/home" location="/home" />

// ✅ Correct (mock)
<Sidebar navigate={() => {}} location={{ pathname: '/home' }} />
```

---

## 7. Anti-Patterns Reference

| Anti-Pattern                                   | Reason                                        | Fix                                       |
| ---------------------------------------------- | --------------------------------------------- | ----------------------------------------- |
| `<button>`                                     | Bypasses design system                        | Use `<Button>`                            |
| `<div className="bg-white rounded shadow">`    | Duplicates Card logic                         | Use `<Card>`                              |
| `text-red-500` for error states                | Non-semantic — won't adapt to theme/dark mode | Use `text-destructive`                    |
| `bg-green-500` for success states              | Non-semantic — won't adapt to theme/dark mode | Use `bg-success`                          |
| Hardcoded `pl-64` for layout                   | Breaks dynamic width                          | Use `sidebarWidth` from `useLayout()`     |
| Manually managing sidebar state                | Defeats context                               | Use `useLayout()`                         |
| Custom SVG icons                               | Inconsistent style                            | Use `lucide-react`                        |
| `style={{ color: '#...' }}`                    | Non-themeable raw value                       | Use semantic token classes                |
| `#3b82f6` or `rgb(...)` in any className/style | Non-themeable raw value                       | Use semantic tokens or Tailwind utilities |
| Inventing new component variants               | Breaks design system                          | Use only documented variants              |
| Wrapping `<XerticaProvider>` per component     | Performance issue                             | Wrap once at app root                     |

---

## 8. Emergency Debug Checklist

If components appear unstyled (transparent backgrounds, no borders):

1. Verify `import 'xertica-ui/style.css'` exists in `main.tsx` or `App.tsx`
2. Verify `<XerticaProvider>` wraps the app root
3. Verify Tailwind CSS is configured to scan `xertica-ui` files (if using custom setup)

If dialogs/modals don't appear:

1. Verify `<XerticaProvider>` is present (it renders the Radix portal container)
2. Check that `Toaster` is included (it's auto-injected by `XerticaProvider`)