@matteoaliano/forest-ui 0.3.3 → 0.3.5

package/skills/forest-external/references/components.md

@@ -0,0 +1,94 @@
+# Forest UI — Component Reference
+
+> Full API reference for all components exported by `@matteoaliano/forest-ui`.
+
+## Import Pattern
+
+```tsx
+// CORRECT — import from forest-ui
+import { Button, TextField, Alert } from "@matteoaliano/forest-ui";
+
+// WRONG — never import from @mui/material
+import Button from "@mui/material/Button";
+```
+
+> Layout primitives (`Box`, `Stack`, `Grid`, `Container`) are NOT re-exported. Import those directly from `@mui/material`.
+
+## Inputs
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Button` | `import { Button } from "forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `color`, `disabled`, `startIcon`, `endIcon`, `loading`, `fullWidth`, `href` | `variant="contained"`, `size` prop removed |
+| `ButtonGroup` | `import { ButtonGroup } from "forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `size: "small" \| "medium" \| "large"`, `orientation: "horizontal" \| "vertical"`, `color`, `disabled`, `fullWidth` | `variant="contained"` |
+| `TextField` | `import { TextField } from "forest-ui"` | `variant: "outlined" \| "filled" \| "standard"`, `size: "small" \| "medium"`, `label`, `error`, `helperText`, `fullWidth`, `multiline`, `rows`, `type`, `placeholder`, `required`, `disabled` | — |
+| `Select` + `MenuItem` | `import { Select, MenuItem } from "forest-ui"` | `variant: "outlined" \| "filled" \| "standard"`, `size: "small" \| "medium"`, `multiple`, `displayEmpty`, `label`, `labelId`, `renderValue`, `native`, `error`, `disabled` | — |
+| `MultiSelect` | `import { MultiSelect } from "forest-ui"` | `options: { label, value }[]`, `value: string[]`, `onChange: (values) => void`, `selectAll: boolean`, `selectAllLabel: string`, `label` + all SelectProps | `selectAll={true}`, `selectAllLabel="Select All"` |
+| `Checkbox` | `import { Checkbox } from "forest-ui"` | `color: "default" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning"`, `size: "small" \| "medium"`, `checked`, `indeterminate`, `disabled` | — |
+| `RadioGroup` + `Radio` | `import { RadioGroup, Radio } from "forest-ui"` | `row`, `value`, `onChange`; Radio: `color`, `size: "small" \| "medium" \| "large"`, `disabled` | — |
+| `Switch` | `import { Switch } from "forest-ui"` | `color: "default" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning"`, `size: "small" \| "medium"`, `checked`, `disabled` | — |
+| `ToggleButton` + `ToggleButtonGroup` | `import { ToggleButton, ToggleButtonGroup } from "forest-ui"` | `value`, `exclusive`, `onChange`, `orientation: "horizontal" \| "vertical"`, `size: "small" \| "medium" \| "large"`, `color`, `fullWidth` | — |
+| `Fab` | `import { Fab } from "forest-ui"` | `variant: "circular" \| "extended"`, `size: "small" \| "medium" \| "large"`, `color`, `disabled`, `href` | `color="primary"` |
+| `IconButton` | `import { IconButton } from "forest-ui"` | `color: "inherit" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning" \| "default"`, `size: "small" \| "medium" \| "large"`, `disabled`, `disableRipple` | — |
+| `Autocomplete` | `import { Autocomplete } from "forest-ui"` | `options`, `renderInput` (required), `multiple`, `freeSolo`, `disableClearable`, `loading`, `groupBy`, `limitTags`, `filterOptions` | — |
+| `Search` | `import { Search } from "forest-ui"` | `onClear`, `placeholder`, all TextField props (except `variant`) | `variant="outlined"`, `placeholder="Search..."`, built-in search icon and clear button |
+| `DatePicker` | `import { DatePicker } from "forest-ui"` | All MUI X DatePicker props (`value`, `onChange`, `label`, `format`, `minDate`, `maxDate`, `disabled`, `readOnly`) | Wraps with `LocalizationProvider` + `AdapterDayjs` automatically |
+
+## Data Display
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Badge` | `import { Badge } from "forest-ui"` | `variant: "standard" \| "dot"`, `color`, `badgeContent`, `max`, `invisible`, `showZero`, `overlap: "rectangular" \| "circular"`, `anchorOrigin` | — |
+| `Chip` | `import { Chip } from "forest-ui"` | `variant: "filled" \| "outlined"`, `color`, `size: "small" \| "medium"`, `label`, `onDelete`, `clickable`, `avatar`, `icon` | `deleteIcon={<CloseOutlined />}` |
+| `Divider` | `import { Divider } from "forest-ui"` | `orientation: "horizontal" \| "vertical"`, `variant: "fullWidth" \| "inset" \| "middle"`, `textAlign`, `flexItem` | — |
+| `Typography` | `import { Typography } from "forest-ui"` | `variant: "h1"-"h6" \| "subtitle1" \| "subtitle2" \| "body1" \| "body2" \| "caption" \| "overline" \| "button"`, `align`, `gutterBottom`, `noWrap` | — |
+| `Tooltip` | `import { Tooltip } from "forest-ui"` | `title` (required), `placement` (12 positions), `arrow`, `followCursor`, `enterDelay`, `leaveDelay` | `arrow={true}` |
+| `Table` family | `import { Table, TableHead, TableBody, TableRow, TableCell, TableContainer } from "forest-ui"` | Table: `size: "small" \| "medium"`, `stickyHeader`; TableCell: `align`, `padding`, `sortDirection`, `variant`; TableRow: `hover`, `selected` | — |
+| `DataGrid` | `import { DataGrid, type GridColDef } from "forest-ui"` | `rows`, `columns`, `paginationModel`, `sortModel`, `filterModel`, `checkboxSelection`, `loading`, `density` | — |
+| `List` family | `import { List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListSubheader } from "forest-ui"` | `dense`, `disablePadding`; ListItemButton: `selected`, `disabled`; ListItemText: `primary`, `secondary` | — |
+
+## Surfaces
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Accordion` family | `import { Accordion, AccordionSummary, AccordionDetails, AccordionActions } from "forest-ui"` | `expanded`, `defaultExpanded`, `onChange`, `disabled`, `disableGutters`, `square` | — |
+| `AppBar` + `Toolbar` | `import { AppBar, Toolbar } from "forest-ui"` | `position`, `color`, `elevation`; Toolbar: `variant: "dense" \| "regular"` | — |
+| `Card` family | `import { Card, CardContent, CardHeader, CardActions, CardMedia } from "forest-ui"` | `variant: "elevation" \| "outlined"`, `elevation`, `raised`; CardHeader: `title`, `subheader`, `avatar`, `action` | — |
+| `Paper` | `import { Paper } from "forest-ui"` | `variant: "elevation" \| "outlined"`, `elevation` (0-24), `square` | — |
+
+## Feedback
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Alert` + `AlertTitle` | `import { Alert, AlertTitle } from "forest-ui"` | `severity: "success" \| "info" \| "warning" \| "error"`, `variant: "filled" \| "outlined" \| "standard"`, `color`, `icon`, `action`, `onClose` | — |
+| `Dialog` family | `import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText } from "forest-ui"` | `open` (required), `onClose`, `fullWidth`, `maxWidth`, `fullScreen`, `scroll: "paper" \| "body"` | — |
+| `Backdrop` | `import { Backdrop } from "forest-ui"` | `open` (required), `invisible`, `onClick` | — |
+| `LinearProgress` | `import { LinearProgress } from "forest-ui"` | `variant: "indeterminate" \| "determinate" \| "buffer" \| "query"`, `value` (0-100), `color` | — |
+| `CircularProgress` | `import { CircularProgress } from "forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` (0-100), `color`, `size`, `thickness` | — |
+| `Skeleton` | `import { Skeleton } from "forest-ui"` | `variant: "text" \| "circular" \| "rectangular" \| "rounded"`, `animation: "pulse" \| "wave" \| false`, `width`, `height` | — |
+| `Modal` | `import { Modal } from "forest-ui"` | `open` (required), `onClose`, `children`, `keepMounted`, `disableAutoFocus`, `disableEscapeKeyDown` | — |
+| `Popover` | `import { Popover } from "forest-ui"` | `open` (required), `anchorEl`, `onClose`, `anchorOrigin`, `transformOrigin`, `elevation` | — |
+| `Snackbar` | `import { Snackbar } from "forest-ui"` | `open`, `message`, `autoHideDuration`, `onClose`, `action`, `anchorOrigin` | — |
+
+## Navigation
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Breadcrumbs` | `import { Breadcrumbs } from "forest-ui"` | `separator`, `maxItems`, `itemsAfterCollapse`, `itemsBeforeCollapse` | — |
+| `Link` | `import { Link } from "forest-ui"` | `href`, `underline: "none" \| "hover" \| "always"`, `color`, `variant` | — |
+| `Menu` + `MenuList` | `import { Menu, MenuList } from "forest-ui"` | Menu: `open` (required), `anchorEl`, `onClose`; use with `MenuItem` | — |
+| `Pagination` | `import { Pagination } from "forest-ui"` | `count`, `page`, `onChange`, `variant: "text" \| "outlined"`, `shape`, `size`, `color`, `showFirstButton`, `showLastButton` | — |
+| `Stepper` family | `import { Stepper, Step, StepLabel } from "forest-ui"` | `activeStep`, `orientation`, `alternativeLabel`, `nonLinear`; Step: `completed`, `disabled`; StepLabel: `optional`, `error` | — |
+| `Tabs` + `Tab` | `import { Tabs, Tab } from "forest-ui"` | Tabs: `value`, `onChange`, `variant: "standard" \| "scrollable" \| "fullWidth"`, `orientation`, `centered`; Tab: `label`, `icon`, `iconPosition`, `disabled`, `value` | — |
+| `SidebarNav` | `import { SidebarNav, SidebarItem, useSidebar } from "forest-ui"` | `open`, `onOpenChange`, `behavior: "permanent" \| "hover"`, `expandedWidth`, `collapsedWidth`, `showToggle`, `header`, `footer` | `expandedWidth=240`, `collapsedWidth=48`, `behavior="permanent"` |
+| `SidebarItem` | (same import) | `icon` (required), `label` (required), `endAdornment`, `selected`, `onClick`, `disabled` | — |
+
+## Charts
+
+Requires `@mui/x-charts` peer dependency. Chart colors are automatically applied from the theme's 12-color series palette.
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `BarChart` | `import { BarChart } from "forest-ui"` | `series` (supports `variant: "solid" \| "striped"` per series), `colors`, `xAxis`, `yAxis`, `width`, `height` | `grid horizontal`, `borderRadius=4`, highlight/fade on hover |
+| `LineChart` | `import { LineChart } from "forest-ui"` | `series`, `colors`, `xAxis`, `yAxis`, `width`, `height` | `curve="linear"`, `strokeWidth=3`, `grid horizontal`, highlight/fade on hover |
+| `PieChart` | `import { PieChart } from "forest-ui"` | `series` (data: `{ id, value, label, color? }[]`), `colors`, `width`, `height` | highlight/fade on hover |
+| `useChartColors` | `import { useChartColors } from "forest-ui"` | `useChartColors(count)` — returns `string[]` of theme chart series colors (max 12) | — |

package/skills/forest-external/references/patterns.md

@@ -0,0 +1,256 @@
+# Forest UI — Code Patterns & Anti-Patterns
+
+## Code Patterns
+
+### Form Layout
+
+```tsx
+import { TextField, Button, Select, MenuItem, Checkbox } from "@matteoaliano/forest-ui";
+import Box from "@mui/material/Box"; // Box, Stack, Grid are OK from MUI
+
+function ContactForm() {
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
+      <TextField label="Name" fullWidth />
+      <TextField label="Email" type="email" fullWidth />
+      <Select label="Subject" fullWidth>
+        <MenuItem value="support">Support</MenuItem>
+        <MenuItem value="sales">Sales</MenuItem>
+      </Select>
+      <Button variant="contained" type="submit">
+        Send
+      </Button>
+    </Box>
+  );
+}
+```
+
+### MultiSelect with Select All
+
+```tsx
+import { useState } from "react";
+import { MultiSelect } from "@matteoaliano/forest-ui";
+
+const options = [
+  { label: "Bug", value: "bug" },
+  { label: "Enhancement", value: "enhancement" },
+  { label: "New Feature", value: "feature" },
+];
+
+function CategoryFilter() {
+  const [selected, setSelected] = useState<string[]>([]);
+  return (
+    <MultiSelect
+      label="Category"
+      options={options}
+      value={selected}
+      onChange={setSelected}
+    />
+  );
+}
+```
+
+### Data Table
+
+```tsx
+import {
+  Table, TableContainer, TableHead, TableBody, TableRow, TableCell,
+} from "@matteoaliano/forest-ui";
+
+function UsersTable({ users }) {
+  return (
+    <TableContainer>
+      <Table>
+        <TableHead>
+          <TableRow>
+            <TableCell>Name</TableCell>
+            <TableCell>Email</TableCell>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {users.map((u) => (
+            <TableRow key={u.id}>
+              <TableCell>{u.name}</TableCell>
+              <TableCell>{u.email}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </TableContainer>
+  );
+}
+```
+
+### DataGrid
+
+```tsx
+import { DataGrid, type GridColDef } from "@matteoaliano/forest-ui";
+
+const columns: GridColDef[] = [
+  { field: "id", headerName: "ID", width: 70 },
+  { field: "name", headerName: "Name", flex: 1 },
+  { field: "email", headerName: "Email", flex: 1 },
+];
+
+function UsersGrid({ rows }) {
+  return <DataGrid rows={rows} columns={columns} />;
+}
+```
+
+### Feedback Pattern
+
+```tsx
+import { Alert, AlertTitle, Snackbar } from "@matteoaliano/forest-ui";
+
+// Inline feedback
+<Alert severity="error">
+  <AlertTitle>Error</AlertTitle>
+  Something went wrong.
+</Alert>
+
+// Toast notification
+<Snackbar open={open} autoHideDuration={4000} onClose={handleClose}>
+  <Alert severity="success" variant="filled">Saved!</Alert>
+</Snackbar>
+```
+
+### Confirmation Dialog
+
+```tsx
+import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText, Button } from "@matteoaliano/forest-ui";
+
+function ConfirmDialog({ open, onClose, onConfirm }) {
+  return (
+    <Dialog open={open} onClose={onClose}>
+      <DialogTitle>Confirm</DialogTitle>
+      <DialogContent>
+        <DialogContentText>Are you sure?</DialogContentText>
+      </DialogContent>
+      <DialogActions>
+        <Button variant="outlined" onClick={onClose}>Cancel</Button>
+        <Button onClick={onConfirm}>Confirm</Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+```
+
+### Sidebar Navigation
+
+```tsx
+import { SidebarNav, SidebarItem } from "@matteoaliano/forest-ui";
+import DashboardOutlined from "@mui/icons-material/DashboardOutlined";
+import SettingsOutlined from "@mui/icons-material/SettingsOutlined";
+
+function AppShell() {
+  const [open, setOpen] = useState(true);
+  return (
+    <SidebarNav open={open} onOpenChange={setOpen}>
+      <SidebarItem icon={<DashboardOutlined />} label="Dashboard" selected />
+      <SidebarItem icon={<SettingsOutlined />} label="Settings" />
+    </SidebarNav>
+  );
+}
+```
+
+### Charts
+
+Colors are automatically assigned from the theme's 12-series palette. Override with the `colors` prop if needed.
+
+```tsx
+import { BarChart, LineChart, PieChart, useChartColors } from "@matteoaliano/forest-ui";
+
+// Bar chart with striped variant
+<BarChart
+  series={[
+    { data: [10, 20, 30], label: "Current", variant: "solid" },
+    { data: [8, 15, 25], label: "Previous", variant: "striped" },
+  ]}
+  xAxis={[{ data: ["Jan", "Feb", "Mar"], scaleType: "band" }]}
+  height={300}
+/>
+
+// Line chart
+<LineChart
+  series={[{ data: [10, 20, 30], label: "Revenue" }]}
+  xAxis={[{ data: ["Jan", "Feb", "Mar"], scaleType: "band" }]}
+  height={300}
+/>
+
+// Pie chart
+<PieChart
+  series={[{ data: [
+    { id: 0, value: 40, label: "Desktop" },
+    { id: 1, value: 30, label: "Mobile" },
+    { id: 2, value: 30, label: "Tablet" },
+  ]}]}
+  height={300}
+/>
+
+// Access chart colors programmatically
+const colors = useChartColors(3);
+```
+
+## Storybook Controls
+
+When adding argTypes to stories:
+
+```tsx
+const meta: Meta<typeof Button> = {
+  component: Button,
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["contained", "outlined", "text"],
+    },
+    color: {
+      control: "select",
+      options: ["primary", "secondary", "error", "warning", "success", "info"],
+    },
+    disabled: { control: "boolean" },
+  },
+};
+```
+
+**Control types:** `"select"` with `options`, `"boolean"`, `"number"`, `"text"`.
+
+## Anti-Patterns
+
+```tsx
+// WRONG: importing from @mui/material
+import Button from "@mui/material/Button";
+
+// WRONG: hardcoded colors
+<Box sx={{ backgroundColor: "#7f56d9" }} />
+
+// WRONG: hardcoded spacing
+<Box sx={{ padding: "16px" }} />
+
+// WRONG: forgetting ForestProvider
+ReactDOM.render(<App />, root); // theme won't apply
+
+// WRONG: using filled (default) icons
+import CloseIcon from "@mui/icons-material/Close";
+
+// CORRECT: always use Outlined variant
+import CloseIcon from "@mui/icons-material/CloseOutlined";
+
+// CORRECT: use theme tokens
+<Box sx={{ backgroundColor: "primary.main", p: 4 }} />
+
+// WRONG: manually building multi-select with Select + Checkbox
+// CORRECT: use the MultiSelect component
+<MultiSelect options={options} value={value} onChange={setValue} />
+```
+
+## TypeScript Props
+
+Every component exports its props type:
+
+```tsx
+import { Button, type ButtonProps } from "@matteoaliano/forest-ui";
+
+interface MyButtonProps extends ButtonProps {
+  analyticsId: string;
+}
+```

package/skills/forest-internal/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: forest-internal
+description: Forest UI Design System rules for the Internal (magenta) preset. Enforces correct imports, component usage, and theming with @matteoaliano/forest-ui. Use when the project uses forest-ui, forest-internal preset, or when user builds UI components in a forest-ui project. Triggers on "forest", "forest-ui", "forest internal", "@matteoaliano/forest-ui".
+metadata:
+  author: Forest Design System
+  version: 0.3.5
+---
+
+# Forest UI — Internal Preset
+
+## Golden Rules
+
+1. **NEVER import from `@mui/material` directly.** Always import from `@matteoaliano/forest-ui`. Exception: layout primitives (`Box`, `Stack`, `Grid`, `Container`) come from `@mui/material`.
+2. **ALWAYS wrap your app root with `<ForestProvider>`** — it applies the theme and CSS baseline.
+3. **NEVER use inline colors or spacing values.** Use design tokens or MUI's `sx` prop with theme values (`p: 4`, `backgroundColor: "primary.main"`).
+4. **NEVER create custom component wrappers** for things Forest UI already provides.
+5. **TypeScript is required.** All components export their prop types (e.g. `type ButtonProps`).
+6. **ALWAYS use the Outlined variant of MUI icons.** Import from `@mui/icons-material/*Outlined` (e.g. `CloseOutlined`, `MailOutlined`). Never use filled, Rounded, Sharp, or TwoTone variants.
+
+## Setup
+
+```bash
+npm install @matteoaliano/forest-ui @mui/material @mui/x-data-grid @mui/x-date-pickers @mui/x-charts dayjs @emotion/react @emotion/styled
+```
+
+```tsx
+import { ForestProvider } from "@matteoaliano/forest-ui";
+
+function App() {
+  return (
+    <ForestProvider preset="forest-internal">
+      {/* All app content here */}
+    </ForestProvider>
+  );
+}
+```
+
+## Preset Identity
+
+**Atmosphere:** Playful, energetic, and unapologetically expressive — vibrant yet functional.
+
+| Role | Color | Hex |
+|------|-------|-----|
+| Primary (brand) | Hot Magenta | `#FF78F3` |
+| Primary hover | Vivid Fuchsia | `#e650d4` |
+| Brand depth | Deep Orchid | `#cc28b5` |
+| Brand tint | Blush Mist | `#fff0fa` |
+| Background | Warm Parchment | `#faf9f8` |
+| Surface | Pure White | `#ffffff` |
+| Text primary | Near-Black Ink | `#18181b` |
+| Text secondary | Steel Gray | `#3f3f46` |
+| Border primary | Silver Mist | `#d8d8dc` |
+| Border brand | Pink Frost | `#ff90d8` |
+| Success | Verdant | `#079455` |
+| Warning | Amber | `#dc6803` |
+| Error | Coral | `#d92d20` |
+| Info | Sky | `#1570ef` |
+
+**Corner radius:** Sharp and geometric (4px for buttons/inputs, up to 12px for cards/modals).
+**Font:** Aeonik (geometric sans-serif). Consumers must load it.
+**Button height:** Compact 32px.
+
+## Available Components
+
+**Inputs:** Button, ButtonGroup, TextField, Select + MenuItem, MultiSelect, Checkbox, RadioGroup + Radio, Switch, ToggleButton + ToggleButtonGroup, Fab, IconButton, Autocomplete, Search, DatePicker
+
+**Data Display:** Badge, Chip, Divider, Typography, Tooltip, Table family (Table, TableHead, TableBody, TableRow, TableCell, TableContainer), DataGrid + GridColDef, List family
+
+**Surfaces:** Accordion family, AppBar + Toolbar, Card family, Paper
+
+**Feedback:** Alert + AlertTitle, Dialog family, Backdrop, LinearProgress, CircularProgress, Skeleton, Modal, Popover, Snackbar
+
+**Navigation:** Breadcrumbs, Link, Menu + MenuList, Pagination, Stepper family, Tabs + Tab, SidebarNav + SidebarItem + useSidebar
+
+**Charts:** BarChart, LineChart, PieChart, useChartColors
+
+See `references/components.md` for full API details and `references/patterns.md` for code examples.
+
+## Common Anti-Patterns
+
+1. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui`
+2. **Hardcoded color values** (`backgroundColor: "#7f56d9"`) instead of theme tokens (`backgroundColor: "primary.main"`)
+3. **Hardcoded spacing** (`padding: "16px"`) instead of theme spacing (`p: 4`)
+4. **Missing `<ForestProvider>`** at the app root — theme won't apply
+5. **Using filled MUI icons** (`Close`) instead of Outlined (`CloseOutlined`)
+6. **Building custom multi-select** instead of using the `<MultiSelect>` component

package/skills/forest-internal/references/components.md

@@ -0,0 +1,94 @@
+# Forest UI — Component Reference
+
+> Full API reference for all components exported by `@matteoaliano/forest-ui`.
+
+## Import Pattern
+
+```tsx
+// CORRECT — import from forest-ui
+import { Button, TextField, Alert } from "@matteoaliano/forest-ui";
+
+// WRONG — never import from @mui/material
+import Button from "@mui/material/Button";
+```
+
+> Layout primitives (`Box`, `Stack`, `Grid`, `Container`) are NOT re-exported. Import those directly from `@mui/material`.
+
+## Inputs
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Button` | `import { Button } from "forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `color`, `disabled`, `startIcon`, `endIcon`, `loading`, `fullWidth`, `href` | `variant="contained"`, `size` prop removed |
+| `ButtonGroup` | `import { ButtonGroup } from "forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `size: "small" \| "medium" \| "large"`, `orientation: "horizontal" \| "vertical"`, `color`, `disabled`, `fullWidth` | `variant="contained"` |
+| `TextField` | `import { TextField } from "forest-ui"` | `variant: "outlined" \| "filled" \| "standard"`, `size: "small" \| "medium"`, `label`, `error`, `helperText`, `fullWidth`, `multiline`, `rows`, `type`, `placeholder`, `required`, `disabled` | — |
+| `Select` + `MenuItem` | `import { Select, MenuItem } from "forest-ui"` | `variant: "outlined" \| "filled" \| "standard"`, `size: "small" \| "medium"`, `multiple`, `displayEmpty`, `label`, `labelId`, `renderValue`, `native`, `error`, `disabled` | — |
+| `MultiSelect` | `import { MultiSelect } from "forest-ui"` | `options: { label, value }[]`, `value: string[]`, `onChange: (values) => void`, `selectAll: boolean`, `selectAllLabel: string`, `label` + all SelectProps | `selectAll={true}`, `selectAllLabel="Select All"` |
+| `Checkbox` | `import { Checkbox } from "forest-ui"` | `color: "default" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning"`, `size: "small" \| "medium"`, `checked`, `indeterminate`, `disabled` | — |
+| `RadioGroup` + `Radio` | `import { RadioGroup, Radio } from "forest-ui"` | `row`, `value`, `onChange`; Radio: `color`, `size: "small" \| "medium" \| "large"`, `disabled` | — |
+| `Switch` | `import { Switch } from "forest-ui"` | `color: "default" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning"`, `size: "small" \| "medium"`, `checked`, `disabled` | — |
+| `ToggleButton` + `ToggleButtonGroup` | `import { ToggleButton, ToggleButtonGroup } from "forest-ui"` | `value`, `exclusive`, `onChange`, `orientation: "horizontal" \| "vertical"`, `size: "small" \| "medium" \| "large"`, `color`, `fullWidth` | — |
+| `Fab` | `import { Fab } from "forest-ui"` | `variant: "circular" \| "extended"`, `size: "small" \| "medium" \| "large"`, `color`, `disabled`, `href` | `color="primary"` |
+| `IconButton` | `import { IconButton } from "forest-ui"` | `color: "inherit" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning" \| "default"`, `size: "small" \| "medium" \| "large"`, `disabled`, `disableRipple` | — |
+| `Autocomplete` | `import { Autocomplete } from "forest-ui"` | `options`, `renderInput` (required), `multiple`, `freeSolo`, `disableClearable`, `loading`, `groupBy`, `limitTags`, `filterOptions` | — |
+| `Search` | `import { Search } from "forest-ui"` | `onClear`, `placeholder`, all TextField props (except `variant`) | `variant="outlined"`, `placeholder="Search..."`, built-in search icon and clear button |
+| `DatePicker` | `import { DatePicker } from "forest-ui"` | All MUI X DatePicker props (`value`, `onChange`, `label`, `format`, `minDate`, `maxDate`, `disabled`, `readOnly`) | Wraps with `LocalizationProvider` + `AdapterDayjs` automatically |
+
+## Data Display
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Badge` | `import { Badge } from "forest-ui"` | `variant: "standard" \| "dot"`, `color`, `badgeContent`, `max`, `invisible`, `showZero`, `overlap: "rectangular" \| "circular"`, `anchorOrigin` | — |
+| `Chip` | `import { Chip } from "forest-ui"` | `variant: "filled" \| "outlined"`, `color`, `size: "small" \| "medium"`, `label`, `onDelete`, `clickable`, `avatar`, `icon` | `deleteIcon={<CloseOutlined />}` |
+| `Divider` | `import { Divider } from "forest-ui"` | `orientation: "horizontal" \| "vertical"`, `variant: "fullWidth" \| "inset" \| "middle"`, `textAlign`, `flexItem` | — |
+| `Typography` | `import { Typography } from "forest-ui"` | `variant: "h1"-"h6" \| "subtitle1" \| "subtitle2" \| "body1" \| "body2" \| "caption" \| "overline" \| "button"`, `align`, `gutterBottom`, `noWrap` | — |
+| `Tooltip` | `import { Tooltip } from "forest-ui"` | `title` (required), `placement` (12 positions), `arrow`, `followCursor`, `enterDelay`, `leaveDelay` | `arrow={true}` |
+| `Table` family | `import { Table, TableHead, TableBody, TableRow, TableCell, TableContainer } from "forest-ui"` | Table: `size: "small" \| "medium"`, `stickyHeader`; TableCell: `align`, `padding`, `sortDirection`, `variant`; TableRow: `hover`, `selected` | — |
+| `DataGrid` | `import { DataGrid, type GridColDef } from "forest-ui"` | `rows`, `columns`, `paginationModel`, `sortModel`, `filterModel`, `checkboxSelection`, `loading`, `density` | — |
+| `List` family | `import { List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListSubheader } from "forest-ui"` | `dense`, `disablePadding`; ListItemButton: `selected`, `disabled`; ListItemText: `primary`, `secondary` | — |
+
+## Surfaces
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Accordion` family | `import { Accordion, AccordionSummary, AccordionDetails, AccordionActions } from "forest-ui"` | `expanded`, `defaultExpanded`, `onChange`, `disabled`, `disableGutters`, `square` | — |
+| `AppBar` + `Toolbar` | `import { AppBar, Toolbar } from "forest-ui"` | `position`, `color`, `elevation`; Toolbar: `variant: "dense" \| "regular"` | — |
+| `Card` family | `import { Card, CardContent, CardHeader, CardActions, CardMedia } from "forest-ui"` | `variant: "elevation" \| "outlined"`, `elevation`, `raised`; CardHeader: `title`, `subheader`, `avatar`, `action` | — |
+| `Paper` | `import { Paper } from "forest-ui"` | `variant: "elevation" \| "outlined"`, `elevation` (0-24), `square` | — |
+
+## Feedback
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Alert` + `AlertTitle` | `import { Alert, AlertTitle } from "forest-ui"` | `severity: "success" \| "info" \| "warning" \| "error"`, `variant: "filled" \| "outlined" \| "standard"`, `color`, `icon`, `action`, `onClose` | — |
+| `Dialog` family | `import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText } from "forest-ui"` | `open` (required), `onClose`, `fullWidth`, `maxWidth`, `fullScreen`, `scroll: "paper" \| "body"` | — |
+| `Backdrop` | `import { Backdrop } from "forest-ui"` | `open` (required), `invisible`, `onClick` | — |
+| `LinearProgress` | `import { LinearProgress } from "forest-ui"` | `variant: "indeterminate" \| "determinate" \| "buffer" \| "query"`, `value` (0-100), `color` | — |
+| `CircularProgress` | `import { CircularProgress } from "forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` (0-100), `color`, `size`, `thickness` | — |
+| `Skeleton` | `import { Skeleton } from "forest-ui"` | `variant: "text" \| "circular" \| "rectangular" \| "rounded"`, `animation: "pulse" \| "wave" \| false`, `width`, `height` | — |
+| `Modal` | `import { Modal } from "forest-ui"` | `open` (required), `onClose`, `children`, `keepMounted`, `disableAutoFocus`, `disableEscapeKeyDown` | — |
+| `Popover` | `import { Popover } from "forest-ui"` | `open` (required), `anchorEl`, `onClose`, `anchorOrigin`, `transformOrigin`, `elevation` | — |
+| `Snackbar` | `import { Snackbar } from "forest-ui"` | `open`, `message`, `autoHideDuration`, `onClose`, `action`, `anchorOrigin` | — |
+
+## Navigation
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `Breadcrumbs` | `import { Breadcrumbs } from "forest-ui"` | `separator`, `maxItems`, `itemsAfterCollapse`, `itemsBeforeCollapse` | — |
+| `Link` | `import { Link } from "forest-ui"` | `href`, `underline: "none" \| "hover" \| "always"`, `color`, `variant` | — |
+| `Menu` + `MenuList` | `import { Menu, MenuList } from "forest-ui"` | Menu: `open` (required), `anchorEl`, `onClose`; use with `MenuItem` | — |
+| `Pagination` | `import { Pagination } from "forest-ui"` | `count`, `page`, `onChange`, `variant: "text" \| "outlined"`, `shape`, `size`, `color`, `showFirstButton`, `showLastButton` | — |
+| `Stepper` family | `import { Stepper, Step, StepLabel } from "forest-ui"` | `activeStep`, `orientation`, `alternativeLabel`, `nonLinear`; Step: `completed`, `disabled`; StepLabel: `optional`, `error` | — |
+| `Tabs` + `Tab` | `import { Tabs, Tab } from "forest-ui"` | Tabs: `value`, `onChange`, `variant: "standard" \| "scrollable" \| "fullWidth"`, `orientation`, `centered`; Tab: `label`, `icon`, `iconPosition`, `disabled`, `value` | — |
+| `SidebarNav` | `import { SidebarNav, SidebarItem, useSidebar } from "forest-ui"` | `open`, `onOpenChange`, `behavior: "permanent" \| "hover"`, `expandedWidth`, `collapsedWidth`, `showToggle`, `header`, `footer` | `expandedWidth=240`, `collapsedWidth=48`, `behavior="permanent"` |
+| `SidebarItem` | (same import) | `icon` (required), `label` (required), `endAdornment`, `selected`, `onClick`, `disabled` | — |
+
+## Charts
+
+Requires `@mui/x-charts` peer dependency. Chart colors are automatically applied from the theme's 12-color series palette.
+
+| Component | Import | Variants / Key Props | Default Props |
+|-----------|--------|----------------------|---------------|
+| `BarChart` | `import { BarChart } from "forest-ui"` | `series` (supports `variant: "solid" \| "striped"` per series), `colors`, `xAxis`, `yAxis`, `width`, `height` | `grid horizontal`, `borderRadius=4`, highlight/fade on hover |
+| `LineChart` | `import { LineChart } from "forest-ui"` | `series`, `colors`, `xAxis`, `yAxis`, `width`, `height` | `curve="linear"`, `strokeWidth=3`, `grid horizontal`, highlight/fade on hover |
+| `PieChart` | `import { PieChart } from "forest-ui"` | `series` (data: `{ id, value, label, color? }[]`), `colors`, `width`, `height` | highlight/fade on hover |
+| `useChartColors` | `import { useChartColors } from "forest-ui"` | `useChartColors(count)` — returns `string[]` of theme chart series colors (max 12) | — |