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, FilterPill)
• 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, KpiStrip, SplitPane, EntityList, LogViewer } from '../design-system/composites'
import type { Column, KpiItem, LogEntry } from '../design-system/composites'
import { AppShell } from '../design-system/layout/AppShell'
import { Sidebar } from '../design-system/layout/Sidebar/Sidebar'
import { SidebarTree } from '../design-system/layout/Sidebar/SidebarTree'
import type { SidebarTreeNode } from '../design-system/layout/Sidebar/SidebarTree'
import { useStarred } from '../design-system/layout/Sidebar/useStarred'
import { ThemeProvider } from '../design-system/providers/ThemeProvider'

Using This Design System in Other Apps

This design system is published as @cameleer/design-system to the Gitea npm registry.

Registry: https://gitea.siegeln.net/api/packages/cameleer/npm/

Setup in a consuming app

1. Add .npmrc to the project root:

@cameleer:registry=https://gitea.siegeln.net/api/packages/cameleer/npm/
//gitea.siegeln.net/api/packages/cameleer/npm/:_authToken=${GITEA_TOKEN}

Note: CI pipelines for consuming apps also need this .npmrc and a GITEA_TOKEN secret to fetch the package during npm ci.

2. Install:

# Snapshot builds (during development)
npm install @cameleer/design-system@dev

# Stable releases
npm install @cameleer/design-system

3. Add fonts to index.html (required — the package does not bundle fonts):

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">

Without these, var(--font-body) and var(--font-mono) fall back to system-ui / monospace.

4. Import styles once at app root, then use components:

import '@cameleer/design-system/style.css'
import { Button, AppShell, ThemeProvider } from '@cameleer/design-system'

Import Paths (Consumer)

// All components from single entry
import { Button, Input, Modal, DataTable, KpiStrip, SplitPane, EntityList, LogViewer, StatusText, AppShell } from '@cameleer/design-system'

// Sidebar (compound component — compose your own navigation)
import { Sidebar, SidebarTree, useStarred } from '@cameleer/design-system'
import type { SidebarTreeNode } from '@cameleer/design-system'

// Types
import type { Column, DataTableProps, SearchResult, KpiItem, LogEntry } from '@cameleer/design-system'

// Providers
import { ThemeProvider, useTheme } from '@cameleer/design-system'
import { CommandPaletteProvider, useCommandPalette } from '@cameleer/design-system'
import { GlobalFilterProvider, useGlobalFilters } from '@cameleer/design-system'

// Utils
import { hashColor } from '@cameleer/design-system'

// Recharts theme (for advanced charts — treemap, radar, heatmap, etc.)
import { rechartsTheme, CHART_COLORS } from '@cameleer/design-system'
import type { ChartSeries, DataPoint } from '@cameleer/design-system'

// Styles (once, at app root)
import '@cameleer/design-system/style.css'

// Brand assets (static files — logo variants and favicon sizes)
import logo from '@cameleer/design-system/logo'           // full resolution PNG
import logo16 from '@cameleer/design-system/logo-16'       // 16×16 favicon
import logo32 from '@cameleer/design-system/logo-32'       // 32×32 favicon
import logo48 from '@cameleer/design-system/logo-48'       // 48×48 taskbar
import logo180 from '@cameleer/design-system/logo-180'     // Apple touch icon
import logo192 from '@cameleer/design-system/logo-192'     // Android/PWA icon
import logo512 from '@cameleer/design-system/logo-512'     // PWA splash, og:image
import logoSvg from '@cameleer/design-system/logo-svg'     // SVG vector logo