9240acddb6
All checks were successful
Build & Publish / publish (push) Successful in 1m26s
- Add Sidebar, SidebarTree, useStarred to import paths - Update navigation decision tree with compound component entries - Replace old Sidebar props description with compound API - Add standard page layout composition pattern for new Sidebar Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
# 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
|
|
```tsx
|
|
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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```html
|
|
<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:
|
|
|
|
```tsx
|
|
import '@cameleer/design-system/style.css'
|
|
import { Button, AppShell, ThemeProvider } from '@cameleer/design-system'
|
|
```
|
|
|
|
### Import Paths (Consumer)
|
|
|
|
```tsx
|
|
// 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'
|
|
```
|