diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..18318de
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,44 @@
+# 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'
+```