# Cameleer3 Design System

## Before Building UI

Always read `COMPONENT_GUIDE.md` before building any UI feature. It contains decision trees for choosing the right component, composition patterns, and the full component index.

## Project Structure

- `src/design-system/primitives/` — atomic UI components (Button, Input, Badge, etc.)
- `src/design-system/composites/` — composed components (DataTable, Modal, Toast, etc.)
- `src/design-system/layout/` — page-level layout (AppShell, Sidebar, TopBar)
- `src/design-system/providers/` — ThemeProvider
- `src/design-system/tokens.css` — all design tokens (colors, spacing, typography)
- `src/pages/` — application pages
- `src/pages/Inventory/` — component showcase at `/inventory`

## Conventions

### Styling
- CSS Modules only — import as `import styles from './Component.module.css'`
- Use tokens from `tokens.css` — never hardcode hex colors
- All colors via CSS custom properties — supports light/dark via `[data-theme="dark"]`
- No inline styles except dynamic values (width from props, etc.)

### Components
- `forwardRef` on all form controls (Input, Textarea, Select, Checkbox, Toggle, Label)
- Every component accepts a `className` prop
- Semantic color variants: `'success' | 'warning' | 'error'` pattern
- Barrel exports: `src/design-system/primitives/index.ts` and `src/design-system/composites/index.ts`

### Testing
- Vitest + React Testing Library + happy-dom
- Tests co-located: `Component.test.tsx` next to `Component.tsx`
- Run: `npx vitest run` (all) or `npx vitest run src/path/to/Component` (single)
- Wrap in `<ThemeProvider>` when component uses `useTheme()` or `hashColor()`

### Import Paths
```tsx
import { Button, Input } from '../design-system/primitives'
import { Modal, DataTable } from '../design-system/composites'
import type { Column } from '../design-system/composites'
import { AppShell } from '../design-system/layout/AppShell'
import { ThemeProvider } from '../design-system/providers/ThemeProvider'
```