design-system/CLAUDE.md

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

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'