@cere/cere-design-system 0.0.8 → 0.0.11

package/.agent/rules/COMPONENTS.md

@@ -0,0 +1,1351 @@
+You are a senior UI developer with expertise in React, TypeScript, Material-UI, and the Cere Design System. 
+When building applications using this design system, follow these guidelines and use the components documented below.
+
+## Installation & Setup
+
+```typescript
+import { ThemeProvider } from '@emotion/react';
+import { theme } from '@cere/cere-design-system';
+
+// Wrap your application with the theme provider
+<ThemeProvider theme={theme}>
+  <YourApp />
+</ThemeProvider>
+```
+
+## Theme & Colors
+
+Import theme and colors from the package:
+
+```typescript
+import { theme, colors } from '@cere/cere-design-system';
+```
+
+**Theme Configuration:**
+- Primary color: `#1976d2` (blue)
+- Font family: Inter
+- Border radius: 12px for inputs/buttons, 16px for cards/chips
+- Breakpoints: xs, sm, md, lg, xl (standard Material-UI)
+
+**Available Color Palettes:**
+- `colors.primary` - main, light, dark, contrastText
+- `colors.secondary` - main, light, dark, contrastText  
+- `colors.tertiary` - main (orange/amber)
+- `colors.error`, `colors.warning`, `colors.info`, `colors.success`
+- `colors.grey` - 50, 100, 200, 300, 400, 500, 600, 700, 800, 900
+- `colors.background` - default, paper, selected
+- `colors.text` - primary, secondary, disabled
+
+## Responsive Hooks
+
+```typescript
+import { useIsDesktop, useIsTablet, useIsMobile } from '@cere/cere-design-system';
+
+const isDesktop = useIsDesktop(); // > 1024px
+const isTablet = useIsTablet();   // 768px - 1024px
+const isMobile = useIsMobile();   // < 768px
+```
+
+## Messaging System
+
+```typescript
+import { MessagesProvider, useMessages } from '@cere/cere-design-system';
+
+// Wrap app with MessagesProvider
+<MessagesProvider><App /></MessagesProvider>
+
+// Use in components
+const { showMessage } = useMessages();
+showMessage('Success!', { severity: 'success', duration: 3000 });
+```
+
+---
+
+## BUTTONS
+
+### Button
+Primary, secondary, and tertiary button variants with icons.
+
+```typescript
+import { Button } from '@cere/cere-design-system';
+import type { ButtonProps } from '@cere/cere-design-system';
+
+<Button variant="primary" size="medium" startIcon={<Icon />}>
+  Click Me
+</Button>
+```
+
+**Props:**
+- `variant?: 'primary' | 'secondary' | 'tertiary'` - Button style (default: 'primary')
+- `size?: 'small' | 'medium' | 'large'` - Button size
+- `startIcon?: ReactNode` - Icon before text
+- `endIcon?: ReactNode` - Icon after text
+- `disabled?: boolean` - Disable button
+- `onClick?: () => void` - Click handler
+- `fullWidth?: boolean` - Full width button
+- `type?: 'button' | 'submit' | 'reset'` - Button type
+- All standard MUI Button props
+
+### IconButton
+Button with only an icon, no text.
+
+```typescript
+import { IconButton } from '@cere/cere-design-system';
+
+<IconButton size="medium" aria-label="delete">
+  <DeleteIcon />
+</IconButton>
+```
+
+**Props:**
+- `size?: 'small' | 'medium' | 'large'`
+- `disabled?: boolean`
+- `onClick?: () => void`
+- `edge?: 'start' | 'end' | false`
+- `color?: 'default' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning'`
+
+### LoadingButton
+Button with loading state and spinner.
+
+```typescript
+import { LoadingButton } from '@cere/cere-design-system';
+
+<LoadingButton loading={isLoading} variant="primary">
+  Submit
+</LoadingButton>
+```
+
+**Props:**
+- Same as `Button` props
+- `loading?: boolean` - Show loading spinner
+- `loadingPosition?: 'start' | 'end' | 'center'` - Spinner position
+
+### ButtonGroup
+Group related buttons together.
+
+```typescript
+import { ButtonGroup, Button } from '@cere/cere-design-system';
+
+<ButtonGroup variant="contained" size="medium">
+  <Button>One</Button>
+  <Button>Two</Button>
+  <Button>Three</Button>
+</ButtonGroup>
+```
+
+**Props:**
+- `variant?: 'text' | 'outlined' | 'contained'`
+- `size?: 'small' | 'medium' | 'large'`
+- `orientation?: 'horizontal' | 'vertical'`
+- `disabled?: boolean`
+- `fullWidth?: boolean`
+
+---
+
+## INPUTS
+
+### TextField
+Text input field with label and validation.
+
+```typescript
+import { TextField } from '@cere/cere-design-system';
+
+<TextField
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+  error={!!error}
+  helperText={error}
+  required
+/>
+```
+
+**Props:**
+- `size?: 'small' | 'medium'`
+- `label?: string` - Input label
+- `value?: string` - Input value
+- `onChange?: (e) => void` - Change handler
+- `error?: boolean` - Show error state
+- `helperText?: string` - Helper/error text below input
+- `required?: boolean` - Required field indicator
+- `disabled?: boolean`
+- `multiline?: boolean` - Textarea mode
+- `rows?: number` - Number of rows for multiline
+- `type?: string` - Input type (text, password, email, etc.)
+- `placeholder?: string`
+- `fullWidth?: boolean`
+- `InputProps?: object` - Custom input props (adornments, etc.)
+
+### SearchField
+Search input with search icon.
+
+```typescript
+import { SearchField } from '@cere/cere-design-system';
+
+<SearchField
+  value={query}
+  onChange={(e) => setQuery(e.target.value)}
+  placeholder="Search..."
+/>
+```
+
+**Props:**
+- Same as `TextField` props
+- Automatically includes search icon
+
+### Dropdown (Select/Autocomplete)
+Two variants: input dropdown and navigation dropdown.
+
+```typescript
+// Input variant (Select)
+import { Dropdown } from '@cere/cere-design-system';
+
+<Dropdown
+  label="Select Option"
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  options={[
+    { value: '1', label: 'Option 1' },
+    { value: '2', label: 'Option 2' }
+  ]}
+/>
+
+// Navigation variant (Popover)
+<Dropdown
+  variant="button"
+  label="Menu"
+  open={open}
+  onToggle={(isOpen) => setOpen(isOpen)}
+>
+  <MenuItem>Item 1</MenuItem>
+  <MenuItem>Item 2</MenuItem>
+</Dropdown>
+```
+
+**Props (Navigation Dropdown):**
+- `variant: 'header' | 'button'` - Dropdown style (required)
+- `open: boolean` - Open state (required)
+- `onToggle?: (open: boolean) => void` - Toggle handler
+- `label?: string` - Button label
+- `leftElement?: ReactNode` - Icon/element before label
+- `direction?: 'right' | 'left'` - Dropdown direction (default: 'left')
+- `dense?: boolean` - Compact spacing
+- `disableGutters?: boolean` - Remove horizontal padding
+- `disablePaddings?: boolean` - Remove all padding
+- `renderAnchor?: (options) => ReactNode` - Custom anchor renderer
+
+### Switch
+Toggle switch component.
+
+```typescript
+import { Switch } from '@cere/cere-design-system';
+
+<Switch checked={enabled} onChange={(e) => setEnabled(e.target.checked)} />
+```
+
+**Props:**
+- `checked?: boolean` - Checked state
+- `onChange?: (e) => void` - Change handler
+- `disabled?: boolean`
+- `size?: 'small' | 'medium'`
+- `color?: 'primary' | 'secondary' | 'default'`
+
+### Checkbox
+Checkbox input.
+
+```typescript
+import { Checkbox } from '@cere/cere-design-system';
+
+<Checkbox checked={agreed} onChange={(e) => setAgreed(e.target.checked)} />
+```
+
+**Props:**
+- `checked?: boolean`
+- `onChange?: (e) => void`
+- `disabled?: boolean`
+- `indeterminate?: boolean` - Partially checked state
+- `size?: 'small' | 'medium'`
+- `color?: 'primary' | 'secondary' | 'default'`
+
+### Radio & RadioGroup
+Radio button inputs.
+
+```typescript
+import { Radio, RadioGroup, FormControlLabel } from '@cere/cere-design-system';
+
+<RadioGroup value={value} onChange={(e) => setValue(e.target.value)}>
+  <FormControlLabel value="1" control={<Radio />} label="Option 1" />
+  <FormControlLabel value="2" control={<Radio />} label="Option 2" />
+</RadioGroup>
+```
+
+**Props:**
+- `value?: string` - Selected value
+- `onChange?: (e) => void` - Change handler
+- `name?: string` - Group name
+- `row?: boolean` - Horizontal layout
+
+### ToggleButton & ToggleButtonGroup
+Toggle button for selecting options.
+
+```typescript
+import { ToggleButton, ToggleButtonGroup } from '@cere/cere-design-system';
+
+<ToggleButtonGroup value={alignment} exclusive onChange={(e, val) => setAlignment(val)}>
+  <ToggleButton value="left">Left</ToggleButton>
+  <ToggleButton value="center">Center</ToggleButton>
+  <ToggleButton value="right">Right</ToggleButton>
+</ToggleButtonGroup>
+```
+
+**Props:**
+- `value?: any` - Selected value(s)
+- `onChange?: (e, value) => void` - Change handler
+- `exclusive?: boolean` - Single selection mode
+- `size?: 'small' | 'medium' | 'large'`
+- `disabled?: boolean`
+- `orientation?: 'horizontal' | 'vertical'`
+
+### Form Components
+Form control wrappers and labels.
+
+```typescript
+import {
+  FormControl,
+  FormLabel,
+  FormHelperText,
+  FormControlLabel,
+  InputLabel,
+  InputAdornment
+} from '@cere/cere-design-system';
+
+<FormControl>
+  <FormLabel>Label</FormLabel>
+  <TextField />
+  <FormHelperText>Helper text</FormHelperText>
+</FormControl>
+```
+
+---
+
+## NAVIGATION
+
+### Sidebar & SidebarItem
+Application sidebar navigation.
+
+```typescript
+import { Sidebar, SidebarItem } from '@cere/cere-design-system';
+
+<Sidebar>
+  <SidebarItem icon={<HomeIcon />} label="Home" active />
+  <SidebarItem icon={<SettingsIcon />} label="Settings" />
+</Sidebar>
+```
+
+**Sidebar Props:**
+- `width?: number` - Sidebar width in pixels
+- `collapsed?: boolean` - Collapsed state
+
+**SidebarItem Props:**
+- `icon?: ReactNode` - Item icon
+- `label: string` - Item label
+- `active?: boolean` - Active/selected state
+- `onClick?: () => void` - Click handler
+- `disabled?: boolean`
+- `badge?: string | number` - Badge content
+
+### Tab
+Tab navigation component.
+
+```typescript
+import { Tab } from '@cere/cere-design-system';
+
+<Tab value={value} onChange={(e, val) => setValue(val)}>
+  <Tab label="Tab 1" value="1" />
+  <Tab label="Tab 2" value="2" />
+</Tab>
+```
+
+**Props:**
+- `value?: any` - Active tab value
+- `onChange?: (e, value) => void` - Change handler
+- `variant?: 'standard' | 'scrollable' | 'fullWidth'`
+- `orientation?: 'horizontal' | 'vertical'`
+
+### Menu & MenuItem
+Context menu or dropdown menu.
+
+```typescript
+import { Menu, MenuItem } from '@cere/cere-design-system';
+
+<Menu open={open} onClose={() => setOpen(false)} anchorEl={anchorEl}>
+  <MenuItem onClick={handleEdit}>Edit</MenuItem>
+  <MenuItem onClick={handleDelete}>Delete</MenuItem>
+</Menu>
+```
+
+**Menu Props:**
+- `open: boolean` - Open state
+- `onClose?: () => void` - Close handler
+- `anchorEl?: Element` - Anchor element
+
+**MenuItem Props:**
+- `onClick?: () => void` - Click handler
+- `disabled?: boolean`
+- `selected?: boolean`
+
+### Pagination
+Pagination controls.
+
+```typescript
+import { Pagination } from '@cere/cere-design-system';
+
+<Pagination
+  count={10}
+  page={page}
+  onChange={(e, p) => setPage(p)}
+/>
+```
+
+**Props:**
+- `count: number` - Total pages
+- `page?: number` - Current page (1-indexed)
+- `onChange?: (e, page) => void` - Page change handler
+- `size?: 'small' | 'medium' | 'large'`
+- `variant?: 'text' | 'outlined'`
+- `color?: 'primary' | 'secondary' | 'standard'`
+- `showFirstButton?: boolean`
+- `showLastButton?: boolean`
+
+### Selector
+Option selector dropdown.
+
+```typescript
+import { Selector } from '@cere/cere-design-system';
+import type { SelectorOption } from '@cere/cere-design-system';
+
+const options: SelectorOption[] = [
+  { id: '1', label: 'Option 1', value: 'val1' },
+  { id: '2', label: 'Option 2', value: 'val2' }
+];
+
+<Selector
+  options={options}
+  value={selected}
+  onChange={(option) => setSelected(option)}
+/>
+```
+
+**Props:**
+- `options: SelectorOption[]` - Available options
+- `value?: SelectorOption` - Selected option
+- `onChange?: (option) => void` - Change handler
+- `placeholder?: string`
+
+### Stepper
+Step-by-step progress indicator.
+
+```typescript
+import { Stepper, Step, StepLabel, StepContent, StepButton } from '@cere/cere-design-system';
+
+<Stepper activeStep={activeStep} orientation="vertical">
+  <Step>
+    <StepLabel>Step 1</StepLabel>
+    <StepContent>Content 1</StepContent>
+  </Step>
+  <Step>
+    <StepLabel>Step 2</StepLabel>
+    <StepContent>Content 2</StepContent>
+  </Step>
+</Stepper>
+```
+
+**Props:**
+- `activeStep?: number` - Current step index
+- `orientation?: 'horizontal' | 'vertical'`
+- `alternativeLabel?: boolean`
+- `nonLinear?: boolean` - Allow non-sequential navigation
+
+### Service & Workspace Selectors
+Special navigation components for selecting services/workspaces.
+
+```typescript
+import { ServiceSelectorButton, WorkspaceSelectorButton } from '@cere/cere-design-system';
+import type { Service, Workspace } from '@cere/cere-design-system';
+
+<ServiceSelectorButton
+  services={services}
+  selected={currentService}
+  onSelect={(service) => setCurrentService(service)}
+/>
+
+<WorkspaceSelectorButton
+  workspaces={workspaces}
+  selected={currentWorkspace}
+  onSelect={(workspace) => setCurrentWorkspace(workspace)}
+/>
+```
+
+### Breadcrumbs
+Breadcrumb navigation.
+
+```typescript
+import { Breadcrumbs } from '@cere/cere-design-system';
+import type { BreadcrumbItem } from '@cere/cere-design-system';
+
+const items: BreadcrumbItem[] = [
+  { label: 'Home', href: '/' },
+  { label: 'Category', href: '/category' },
+  { label: 'Current Page' }
+];
+
+<Breadcrumbs items={items} />
+```
+
+**Props:**
+- `items: BreadcrumbItem[]` - Breadcrumb items
+- `maxItems?: number` - Max items to display before collapsing
+- `separator?: ReactNode` - Custom separator
+
+---
+
+## LAYOUT
+
+### Card
+Container card with header, content, and actions.
+
+```typescript
+import { Card, CardHeader, CardContent, CardActions, Button } from '@cere/cere-design-system';
+
+<Card hoverable clickable onClick={handleClick}>
+  <CardHeader title="Card Title" subheader="Subtitle" />
+  <CardContent>Card content here</CardContent>
+  <CardActions>
+    <Button>Action</Button>
+  </CardActions>
+</Card>
+```
+
+**Card Props:**
+- `hoverable?: boolean` - Lift on hover effect
+- `clickable?: boolean` - Cursor pointer, click effect
+- `elevation?: number` - Shadow elevation (0-24)
+- All standard MUI Card props
+
+### Dialog
+Modal dialog/popup.
+
+```typescript
+import { Dialog, Button } from '@cere/cere-design-system';
+
+<Dialog
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Dialog Title"
+  maxWidth="sm"
+  fullWidth
+>
+  <div>Dialog content</div>
+</Dialog>
+```
+
+**Props:**
+- `open: boolean` - Open state
+- `onClose?: () => void` - Close handler
+- `title?: string` - Dialog title
+- `maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false`
+- `fullWidth?: boolean`
+- `fullScreen?: boolean`
+
+### Drawer
+Side drawer panel.
+
+```typescript
+import { Drawer } from '@cere/cere-design-system';
+
+<Drawer
+  open={open}
+  onClose={() => setOpen(false)}
+  anchor="right"
+>
+  <div>Drawer content</div>
+</Drawer>
+```
+
+**Props:**
+- `open: boolean` - Open state
+- `onClose?: () => void` - Close handler
+- `anchor?: 'left' | 'right' | 'top' | 'bottom'`
+- `variant?: 'permanent' | 'persistent' | 'temporary'`
+
+### List & ListItem
+Lists with items.
+
+```typescript
+import { List, ListItem, ListItemText, ListItemIcon, ListItemSecondaryAction } from '@cere/cere-design-system';
+
+<List>
+  <ListItem button onClick={handleClick}>
+    <ListItemIcon><Icon /></ListItemIcon>
+    <ListItemText primary="Primary Text" secondary="Secondary Text" />
+    <ListItemSecondaryAction>
+      <IconButton><MoreIcon /></IconButton>
+    </ListItemSecondaryAction>
+  </ListItem>
+</List>
+```
+
+**Props:**
+- `dense?: boolean` - Compact spacing
+- `disablePadding?: boolean`
+- `button?: boolean` - Make item clickable (ListItem prop)
+- `divider?: boolean` - Show divider (ListItem prop)
+
+### Table
+Data table with headers.
+
+```typescript
+import { Table, TableHeader } from '@cere/cere-design-system';
+
+const columns = [
+  { id: 'name', label: 'Name' },
+  { id: 'email', label: 'Email' }
+];
+
+<Table
+  columns={columns}
+  data={rows}
+  onSort={(column) => handleSort(column)}
+/>
+```
+
+**Props:**
+- `columns: TableColumn[]` - Column definitions
+- `data: any[]` - Table data rows
+- `onSort?: (column) => void` - Sort handler
+- `stickyHeader?: boolean`
+- `size?: 'small' | 'medium'`
+
+### Avatar
+User avatar image or initials.
+
+```typescript
+import { Avatar } from '@cere/cere-design-system';
+
+<Avatar src="/avatar.jpg" alt="User" />
+<Avatar>JD</Avatar>
+```
+
+**Props:**
+- `src?: string` - Image source
+- `alt?: string` - Alt text
+- `size?: 'small' | 'medium' | 'large'` | number
+- `variant?: 'circular' | 'rounded' | 'square'`
+- `children?: ReactNode` - Text/initials
+
+### Grid
+Responsive grid layout.
+
+```typescript
+import { Grid } from '@cere/cere-design-system';
+
+<Grid container spacing={2}>
+  <Grid item xs={12} md={6}>Column 1</Grid>
+  <Grid item xs={12} md={6}>Column 2</Grid>
+</Grid>
+```
+
+**Props:**
+- `container?: boolean` - Grid container
+- `item?: boolean` - Grid item
+- `spacing?: number` - Gap between items (0-10)
+- `xs?: number | 'auto'` - Mobile columns (1-12)
+- `sm?: number | 'auto'` - Tablet columns
+- `md?: number | 'auto'` - Desktop columns
+- `lg?: number | 'auto'` - Large desktop columns
+- `xl?: number | 'auto'` - XL desktop columns
+
+### Box, Stack, Container
+Layout utilities.
+
+```typescript
+import { Box, Stack, Container } from '@cere/cere-design-system';
+
+<Container maxWidth="lg">
+  <Stack spacing={2} direction="row">
+    <Box sx={{ p: 2, bgcolor: 'primary.main' }}>Box 1</Box>
+    <Box sx={{ p: 2, bgcolor: 'secondary.main' }}>Box 2</Box>
+  </Stack>
+</Container>
+```
+
+**Stack Props:**
+- `spacing?: number` - Gap between children
+- `direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'`
+- `divider?: ReactNode` - Divider between items
+- `alignItems?: string` - CSS align-items
+- `justifyContent?: string` - CSS justify-content
+
+**Container Props:**
+- `maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false`
+- `disableGutters?: boolean`
+- `fixed?: boolean`
+
+### Paper
+Elevated surface.
+
+```typescript
+import { Paper } from '@cere/cere-design-system';
+
+<Paper elevation={3} sx={{ p: 2 }}>
+  Content
+</Paper>
+```
+
+**Props:**
+- `elevation?: number` - Shadow depth (0-24)
+- `variant?: 'elevation' | 'outlined'`
+- `square?: boolean` - Sharp corners
+
+### Typography
+Text component with semantic variants.
+
+```typescript
+import { Typography } from '@cere/cere-design-system';
+
+<Typography variant="h1" color="primary">
+  Heading
+</Typography>
+```
+
+**Props:**
+- `variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'caption' | 'button' | 'overline'`
+- `color?: string` - Text color
+- `align?: 'left' | 'center' | 'right' | 'justify'`
+- `gutterBottom?: boolean` - Bottom margin
+- `noWrap?: boolean` - Prevent wrapping
+
+### Link
+Styled link component.
+
+```typescript
+import { Link } from '@cere/cere-design-system';
+
+<Link href="/path" underline="hover">
+  Link Text
+</Link>
+```
+
+**Props:**
+- `href?: string` - Link URL
+- `underline?: 'none' | 'hover' | 'always'`
+- `color?: string`
+- `target?: string`
+
+### AppBar & Toolbar
+Application header bar.
+
+```typescript
+import { AppBar, Toolbar, Typography } from '@cere/cere-design-system';
+
+<AppBar position="fixed">
+  <Toolbar>
+    <Typography variant="h6">App Title</Typography>
+  </Toolbar>
+</AppBar>
+```
+
+**AppBar Props:**
+- `position?: 'fixed' | 'absolute' | 'sticky' | 'static' | 'relative'`
+- `color?: 'default' | 'primary' | 'secondary' | 'transparent'`
+- `elevation?: number`
+
+### Accordion
+Collapsible content panels.
+
+```typescript
+import { Accordion } from '@cere/cere-design-system';
+
+<Accordion expanded={expanded} onChange={() => setExpanded(!expanded)}>
+  <AccordionSummary>Header</AccordionSummary>
+  <AccordionDetails>Content</AccordionDetails>
+</Accordion>
+```
+
+**Props:**
+- `expanded?: boolean` - Expanded state
+- `onChange?: () => void` - Toggle handler
+- `disabled?: boolean`
+- `defaultExpanded?: boolean`
+
+### Collapse
+Animated expand/collapse wrapper.
+
+```typescript
+import { Collapse } from '@cere/cere-design-system';
+
+<Collapse in={show}>
+  <div>Collapsible content</div>
+</Collapse>
+```
+
+**Props:**
+- `in: boolean` - Show/hide state
+- `timeout?: number | 'auto'` - Animation duration
+- `unmountOnExit?: boolean`
+
+### Divider
+Visual separator line.
+
+```typescript
+import { Divider } from '@cere/cere-design-system';
+
+<Divider />
+<Divider orientation="vertical" />
+```
+
+**Props:**
+- `orientation?: 'horizontal' | 'vertical'`
+- `variant?: 'fullWidth' | 'inset' | 'middle'`
+- `flexItem?: boolean`
+
+### Logo
+Cere Network logo component.
+
+```typescript
+import { Logo } from '@cere/cere-design-system';
+
+<Logo size="medium" variant="full" />
+```
+
+**Props:**
+- `size?: 'small' | 'medium' | 'large'` | number
+- `variant?: 'full' | 'icon'`
+
+---
+
+## FEEDBACK
+
+### Alert & Snackbar
+Alert messages and toast notifications.
+
+```typescript
+import { Alert, Snackbar } from '@cere/cere-design-system';
+
+<Alert severity="success" title="Success!">
+  Operation completed
+</Alert>
+
+<Snackbar
+  open={open}
+  message="Saved successfully"
+  severity="success"
+  onClose={() => setOpen(false)}
+  autoHideDuration={6000}
+/>
+```
+
+**Alert Props:**
+- `severity?: 'success' | 'error' | 'warning' | 'info'` (default: 'info')
+- `title?: string` - Alert title
+- `variant?: 'filled' | 'standard' | 'outlined'`
+- `onClose?: () => void` - Close button handler
+
+**Snackbar Props:**
+- `open: boolean` - Open state
+- `message?: string` - Message text
+- `severity?: 'success' | 'error' | 'warning' | 'info'` (default: 'info')
+- `title?: string` - Alert title
+- `variant?: 'filled' | 'standard' | 'outlined'` (default: 'filled')
+- `onClose?: () => void` - Close handler
+- `autoHideDuration?: number` (default: 6000ms)
+- `anchorOrigin?: { vertical, horizontal }` - Position
+
+### Badge
+Small badge indicator.
+
+```typescript
+import { Badge } from '@cere/cere-design-system';
+
+<Badge badgeContent={4} color="primary">
+  <MailIcon />
+</Badge>
+```
+
+**Props:**
+- `badgeContent?: ReactNode` - Badge content
+- `color?: 'default' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning'`
+- `variant?: 'standard' | 'dot'`
+- `max?: number` - Max number before showing "+"
+- `invisible?: boolean`
+
+### Chip
+Compact element representing an input, attribute, or action.
+
+```typescript
+import { Chip } from '@cere/cere-design-system';
+
+<Chip
+  label="Tag"
+  onDelete={handleDelete}
+  color="primary"
+  icon={<Icon />}
+/>
+```
+
+**Props:**
+- `label: string` - Chip text
+- `variant?: 'filled' | 'outlined'`
+- `color?: 'default' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning'`
+- `size?: 'small' | 'medium'`
+- `icon?: ReactNode` - Icon before label
+- `avatar?: ReactNode` - Avatar before label
+- `onDelete?: () => void` - Delete handler (shows X button)
+- `onClick?: () => void` - Click handler
+- `disabled?: boolean`
+- `clickable?: boolean`
+
+### Tooltip
+Informative tooltip on hover.
+
+```typescript
+import { Tooltip } from '@cere/cere-design-system';
+
+<Tooltip title="Helpful information" placement="top">
+  <IconButton><HelpIcon /></IconButton>
+</Tooltip>
+```
+
+**Props:**
+- `title: string | ReactNode` - Tooltip content
+- `placement?: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | etc.`
+- `arrow?: boolean` - Show arrow pointer
+- `open?: boolean` - Controlled open state
+- `onOpen?: () => void`
+- `onClose?: () => void`
+
+### Progress
+Linear progress bar.
+
+```typescript
+import { Progress } from '@cere/cere-design-system';
+
+<Progress value={75} variant="determinate" />
+<Progress variant="indeterminate" />
+```
+
+**Props:**
+- `variant?: 'determinate' | 'indeterminate'`
+- `value?: number` - Progress value (0-100) for determinate
+- `color?: 'primary' | 'secondary'`
+- `valueBuffer?: number` - Buffer value for buffer variant
+
+### CircularProgress
+Circular loading spinner.
+
+```typescript
+import { CircularProgress } from '@cere/cere-design-system';
+
+<CircularProgress size={40} />
+<CircularProgress variant="determinate" value={75} />
+```
+
+**Props:**
+- `variant?: 'determinate' | 'indeterminate'` (default: 'indeterminate')
+- `value?: number` - Progress value (0-100)
+- `size?: number | string` - Spinner size
+- `thickness?: number` - Stroke thickness
+- `color?: 'primary' | 'secondary' | 'inherit'`
+
+### EmptyState
+Empty state placeholder.
+
+```typescript
+import { EmptyState } from '@cere/cere-design-system';
+
+<EmptyState
+  title="No data"
+  description="There are no items to display"
+  icon={<InboxIcon />}
+  action={<Button>Add Item</Button>}
+/>
+```
+
+**Props:**
+- `title: string` - Empty state title
+- `description?: string` - Description text
+- `icon?: ReactNode` - Icon to display
+- `action?: ReactNode` - Action button/component
+
+### Loading
+Loading state indicator.
+
+```typescript
+import { Loading } from '@cere/cere-design-system';
+
+<Loading message="Loading data..." />
+```
+
+**Props:**
+- `message?: string` - Loading message
+- `size?: 'small' | 'medium' | 'large'`
+
+### AppLoading
+Full-screen app loading state.
+
+```typescript
+import { AppLoading } from '@cere/cere-design-system';
+
+<AppLoading />
+```
+
+**Props:**
+- Minimal props - displays animated Cere logo
+
+---
+
+## UTILITIES
+
+### Markdown
+Render markdown content with syntax highlighting.
+
+```typescript
+import { Markdown } from '@cere/cere-design-system';
+
+<Markdown content={markdownString} />
+```
+
+**Props:**
+- `content: string` - Markdown content to render
+- Uses `react-markdown` with `rehype-highlight` for code blocks
+- Supports GitHub-flavored markdown
+
+### Truncate
+Truncate long text with ellipsis.
+
+```typescript
+import { Truncate } from '@cere/cere-design-system';
+
+<Truncate lines={2}>
+  Very long text that will be truncated...
+</Truncate>
+```
+
+**Props:**
+- `lines?: number` - Number of lines to show (default: 1)
+- `children: string` - Text to truncate
+
+### BytesSize
+Format bytes to human-readable size.
+
+```typescript
+import { BytesSize } from '@cere/cere-design-system';
+
+<BytesSize bytes={1024000} />
+// Displays: "1.02 MB"
+```
+
+**Props:**
+- `bytes: number` - Bytes to format
+
+### QRCode
+Display QR code.
+
+```typescript
+import { QRCode } from '@cere/cere-design-system';
+
+<QRCode value="https://example.com" size={256} />
+```
+
+**Props:**
+- `value: string` - Data to encode
+- `size?: number` - QR code size in pixels (default: 128)
+- `level?: 'L' | 'M' | 'Q' | 'H'` - Error correction level
+- `bgColor?: string` - Background color
+- `fgColor?: string` - Foreground color
+
+### OnboardingProvider
+Onboarding/tour provider.
+
+```typescript
+import { OnboardingProvider, useOnboarding } from '@cere/cere-design-system';
+
+<OnboardingProvider>
+  <App />
+</OnboardingProvider>
+
+// In component:
+const { startTour, currentStep } = useOnboarding();
+```
+
+---
+
+## CHARTS
+
+### ChartWidget
+Chart container with title and controls.
+
+```typescript
+import { ChartWidget } from '@cere/cere-design-system';
+
+<ChartWidget
+  title="Sales Data"
+  description="Monthly sales overview"
+  action={<Button>Export</Button>}
+>
+  <YourChart />
+</ChartWidget>
+```
+
+**Props:**
+- `title?: string` - Widget title
+- `description?: string` - Widget description
+- `action?: ReactNode` - Action button/component
+- `children: ReactNode` - Chart content
+
+### MetricsChart
+Pre-built metrics chart with period selector.
+
+```typescript
+import { MetricsChart, PeriodSelect } from '@cere/cere-design-system';
+import type { MetricsPeriod } from '@cere/cere-design-system';
+
+<MetricsChart
+  data={chartData}
+  period="7d"
+  onPeriodChange={(period) => setPeriod(period)}
+  title="Metrics"
+/>
+```
+
+**Props:**
+- `data: any[]` - Chart data
+- `period?: MetricsPeriod` - Selected time period
+- `onPeriodChange?: (period) => void` - Period change handler
+- `title?: string` - Chart title
+- Uses MUI X-Charts internally
+
+**MetricsPeriod:** `'24h' | '7d' | '30d' | '90d' | '1y'`
+
+---
+
+## THIRD-PARTY COMPONENTS
+
+### FlowEditor
+Visual flow/graph editor (ReactFlow wrapper).
+
+```typescript
+import { FlowEditor } from '@cere/cere-design-system';
+import type { Node, Edge, NodeTypes, ReactFlowInstance } from '@cere/cere-design-system';
+
+const nodes: Node[] = [
+  { id: '1', position: { x: 0, y: 0 }, data: { label: 'Node 1' } }
+];
+const edges: Edge[] = [
+  { id: 'e1-2', source: '1', target: '2' }
+];
+
+<FlowEditor
+  nodes={nodes}
+  edges={edges}
+  onNodesChange={handleNodesChange}
+  onEdgesChange={handleEdgesChange}
+  height="600px"
+  showBackground
+  showControls
+  showMinimap
+  nodeTypes={customNodeTypes}
+/>
+```
+
+**Props:**
+- `nodes: Node[]` - Flow nodes (required)
+- `edges: Edge[]` - Flow edges (required)
+- `onNodesChange?: OnNodesChange` - Nodes change handler
+- `onEdgesChange?: OnEdgesChange` - Edges change handler
+- `nodeTypes?: NodeTypes` - Custom node components
+- `edgeTypes?: EdgeTypes` - Custom edge components
+- `height?: string | number` (default: '600px')
+- `showBackground?: boolean` (default: true)
+- `backgroundVariant?: BackgroundVariant` (default: 'dots')
+- `showControls?: boolean` (default: true)
+- `showMinimap?: boolean` (default: false)
+- `containerProps?: BoxProps` - Container styling
+- `onInit?: (instance: ReactFlowInstance) => void` - Initialization callback
+- All ReactFlow props supported
+
+**Re-exported from ReactFlow:**
+- `Background`, `Controls`, `MiniMap`, `Panel` components
+- `BackgroundVariant`, `ConnectionLineType` enums
+- `Node`, `Edge`, `NodeTypes`, `EdgeTypes`, `ReactFlowInstance` types
+- `OnNodesChange`, `OnEdgesChange` types
+
+### CodeEditor
+Code editor with syntax highlighting (Monaco Editor wrapper).
+
+```typescript
+import { CodeEditor } from '@cere/cere-design-system';
+import type { CodeEditorLanguage } from '@cere/cere-design-system';
+
+<CodeEditor
+  value={code}
+  onChange={setCode}
+  language="typescript"
+  height="500px"
+  onValidate={(markers) => console.log('Errors:', markers)}
+  typeDefinitions={`
+    declare interface CustomType {
+      id: string;
+      name: string;
+    }
+  `}
+/>
+```
+
+**Props:**
+- `value: string` - Editor content (required)
+- `onChange: (value: string) => void` - Change handler (required)
+- `language?: CodeEditorLanguage` (default: 'typescript')
+  - Options: `'typescript' | 'javascript' | 'json' | 'html' | 'css' | 'python' | 'yaml' | 'markdown' | 'sql' | 'xml' | 'plaintext'`
+- `height?: string | number` (default: '400px')
+- `minHeight?: string | number` - Minimum height
+- `theme?: string` - Monaco theme ('light' | 'dark' | 'vs-dark' | 'hc-black')
+- `lineNumbers?: 'on' | 'off' | 'relative' | 'interval'` (default: 'on')
+- `options?: editor.IStandaloneEditorConstructionOptions` - Monaco editor options
+- `onMount?: (editor, monaco) => void` - Editor mounted callback
+- `onValidate?: (markers: editor.IMarker[]) => void` - Validation errors callback
+- `editorRef?: React.MutableRefObject<editor.IStandaloneCodeEditor | null>` - Editor instance ref
+- `monacoRef?: React.MutableRefObject<Monaco | null>` - Monaco instance ref
+- `onFullscreenChange?: (isFullscreen: boolean) => void` - Fullscreen state callback
+- `containerProps?: BoxProps` - Container styling
+- `typeDefinitions?: string | string[]` - Additional TypeScript type definitions
+
+**Features:**
+- Fullscreen mode support
+- TypeScript validation and IntelliSense
+- Custom type definitions injection
+- Syntax highlighting for multiple languages
+- Error/warning markers display
+- Collapsible problems panel
+
+---
+
+## ICONS
+
+The design system includes custom Cere-branded icons:
+
+```typescript
+import {
+  CereIcon,
+  ActivityAppIcon,
+  StorageAppIcon,
+  DecentralizedServerIcon,
+  CloudFlashIcon,
+  BarTrackingIcon,
+  GithubLogoIcon,
+  DiscordIcon,
+  ClockIcon,
+  AvatarIcon,
+  ShareIcon,
+  DownloadIcon,
+  UploadFileIcon,
+  UploadFolderIcon,
+  FolderIcon,
+  FilledFolderIcon,
+  ArrowLeft,
+  ArrowRight
+} from '@cere/cere-design-system';
+
+<CereIcon />
+<ActivityAppIcon />
+```
+
+All icons are React components that accept standard SVG props (width, height, color, etc.).
+
+---
+
+## BEST PRACTICES
+
+### Component Usage Guidelines
+
+1. **Always wrap with ThemeProvider**: Ensure all components are wrapped with the Cere theme provider for consistent styling.
+
+2. **Use TypeScript types**: Import and use the exported TypeScript types for better IDE support and type safety.
+   ```typescript
+   import type { ButtonProps, TextFieldProps } from '@cere/cere-design-system';
+   ```
+
+3. **Responsive Design**: Use the responsive hooks (`useIsDesktop`, `useIsTablet`, `useIsMobile`) or Grid component for responsive layouts.
+
+4. **Form Validation**: Use TextField's `error` and `helperText` props for inline validation feedback.
+
+5. **Loading States**: Use LoadingButton for async actions and Loading/CircularProgress for data fetching.
+
+6. **Accessibility**: 
+   - Always provide `aria-label` for IconButtons
+   - Use semantic HTML and proper heading hierarchy
+   - Ensure sufficient color contrast
+   - Support keyboard navigation
+
+7. **Consistent Spacing**: Use the theme's spacing system (`theme.spacing(n)`) or sx prop for consistent spacing.
+
+8. **Icon Usage**: Prefer custom Cere icons when available, otherwise use Material-UI icons.
+
+9. **Error Handling**: Use Alert/Snackbar for user-facing error messages.
+
+10. **Code Editing**: For any code input, use CodeEditor with appropriate language and type definitions.
+
+### Common Patterns
+
+**Form with Validation:**
+```typescript
+<form onSubmit={handleSubmit}>
+  <Stack spacing={2}>
+    <TextField
+      label="Email"
+      value={email}
+      onChange={(e) => setEmail(e.target.value)}
+      error={!!errors.email}
+      helperText={errors.email}
+      required
+    />
+    <LoadingButton
+      type="submit"
+      variant="primary"
+      loading={isSubmitting}
+    >
+      Submit
+    </LoadingButton>
+  </Stack>
+</form>
+```
+
+**Data Table with Actions:**
+```typescript
+<Card>
+  <CardHeader title="Users" />
+  <Table
+    columns={columns}
+    data={users}
+    onSort={handleSort}
+  />
+</Card>
+```
+
+**Dashboard Layout:**
+```typescript
+<Container maxWidth="lg">
+  <Grid container spacing={3}>
+    <Grid item xs={12} md={6}>
+      <ChartWidget title="Metrics">
+        <MetricsChart data={data} />
+      </ChartWidget>
+    </Grid>
+    <Grid item xs={12} md={6}>
+      <Card>
+        <CardContent>...</CardContent>
+      </Card>
+    </Grid>
+  </Grid>
+</Container>
+```