@matteoaliano/forest-ui 0.4.3 → 0.5.0

package/skills/forest-external/SKILL.md

@@ -3,14 +3,14 @@ name: forest-external
 description: Forest UI Design System rules for the External (violet) preset. Enforces correct imports, component usage, and theming with @matteoaliano/forest-ui. Use when the project uses forest-ui, forest-external preset, or when user builds UI components in a forest-ui project. Triggers on "forest", "forest-ui", "forest external", "@matteoaliano/forest-ui".
 metadata:
   author: Forest Design System
-  version: 0.4.3
+  version: 0.5.0
 ---
 
 # Forest UI — External 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`.
+1. **NEVER import from `@mui/material` directly.** Always import from `@matteoaliano/forest-ui`. All MUI components, layout primitives, transitions, form helpers, and hooks are re-exported. The only exception is `@mui/icons-material` — import icons from there directly.
 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.
@@ -23,6 +23,8 @@ metadata:
 npm install @matteoaliano/forest-ui @mui/material @mui/x-data-grid @mui/x-date-pickers @mui/x-charts dayjs @emotion/react @emotion/styled
 ```
 
+> **Note:** `@mui/material`, `@mui/x-data-grid`, `@mui/x-date-pickers`, and `@mui/x-charts` are **peer dependencies** — install them but **always import from `@matteoaliano/forest-ui`**, not from these packages directly. Forest UI re-exports everything.
+
 ```tsx
 import { ForestProvider } from "@matteoaliano/forest-ui";
 
@@ -39,30 +41,39 @@ function App() {
 
 - **Aeonik** — the default font for all UI text (headings, body, labels, buttons, etc.)
 - **Aeonik Mono** — use for numeric values: prices, stats, table figures, counters, dates, IDs, code snippets
-- **Alkemy Beta** — reserved exclusively for branding elements (e.g. Logo component). Never use for general UI text
+- **Alkemy Beta** — use for page titles (h1/hero headings). Not for general UI text
 
 Import the font CSS files you need in your app entry point:
 
 ```tsx
 import "@matteoaliano/forest-ui/fonts/aeonik/aeonik.css";
 import "@matteoaliano/forest-ui/fonts/aeonik-mono/aeonik-mono.css";
-// Only if using branding/logo elements:
 import "@matteoaliano/forest-ui/fonts/alkemy-beta/alkemy-beta.css";
 ```
 
 ## Available Components
 
-**Inputs:** Button, ButtonGroup, TextField, Select + MenuItem, MultiSelect, Checkbox, RadioGroup + Radio, Switch, ToggleButton + ToggleButtonGroup, Fab, IconButton, Autocomplete, Search, DatePicker
+**Inputs:** Button, ButtonGroup, TextField, Select + MenuItem, MultiSelect, Checkbox, RadioGroup + Radio, Switch, ToggleButton + ToggleButtonGroup, Fab, IconButton, Autocomplete, Search, DatePicker, Input
+
+**Data Display:** Badge, Chip, Divider, Typography, Tooltip, Logo, Table family (Table, TableHead, TableBody, TableRow, TableCell, TableContainer, TableFooter, TablePagination, TableSortLabel), DataGrid + GridColDef, List family (List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListItemSecondaryAction, ListSubheader), Avatar + AvatarGroup, ImageList + ImageListItem + ImageListItemBar, Rating
+
+**Surfaces:** Accordion family, AppBar + Toolbar + AppBarNavItem, Card family + CardActionArea, Paper, Drawer + SwipeableDrawer
+
+**Feedback:** Alert + AlertTitle, Dialog family, Backdrop, LinearProgress, CircularProgress, Skeleton, Modal, Popover, Snackbar + SnackbarContent, Slider
+
+**Navigation:** Breadcrumbs, Link, Menu + MenuList, Pagination + PaginationItem, Stepper family (Stepper, Step, StepLabel, StepButton, StepConnector, StepContent, StepIcon), Tabs + Tab + TabScrollButton, SidebarNav + SidebarItem + useSidebar, BottomNavigation + BottomNavigationAction, SpeedDial + SpeedDialAction + SpeedDialIcon, MobileStepper
+
+**Layout:** Box, Stack, Grid, Container
 
-**Data Display:** Badge, Chip, Divider, Typography, Tooltip, Table family (Table, TableHead, TableBody, TableRow, TableCell, TableContainer), DataGrid + GridColDef, List family
+**Form Helpers:** FormControl, FormControlLabel, FormGroup, FormHelperText, FormLabel, InputAdornment, InputBase, InputLabel, OutlinedInput, FilledInput
 
-**Surfaces:** Accordion family, AppBar + Toolbar, Card family, Paper
+**Transitions:** Collapse, Fade, Grow, Slide, Zoom
 
-**Feedback:** Alert + AlertTitle, Dialog family, Backdrop, LinearProgress, CircularProgress, Skeleton, Modal, Popover, Snackbar
+**Utilities:** ClickAwayListener, NoSsr, Portal, Popper, TextareaAutosize, SvgIcon, ButtonBase, GlobalStyles
 
-**Navigation:** Breadcrumbs, Link, Menu + MenuList, Pagination, Stepper family, Tabs + Tab, SidebarNav + SidebarItem + useSidebar
+**Hooks:** useMediaQuery, useScrollTrigger, useFormControl, useTheme
 
-**Charts:** BarChart, LineChart, PieChart, useChartColors
+**Charts:** BarChart, LineChart, PieChart, ScatterChart, Gauge, SparkLineChart, useChartColors, plus composition primitives (see components.md)
 
 See `references/components.md` for full API details and `references/patterns.md` for code examples.
 
@@ -75,7 +86,7 @@ See `references/components.md` for full API details and `references/patterns.md`
 
 ## Common Anti-Patterns
 
-1. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui`
+1. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui` — all components, hooks, and layout primitives are available from 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

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

@@ -12,83 +12,191 @@ import { Button, TextField, Alert } from "@matteoaliano/forest-ui";
 import Button from "@mui/material/Button";
 ```
 
-> Layout primitives (`Box`, `Stack`, `Grid`, `Container`) are NOT re-exported. Import those directly from `@mui/material`.
+> **All MUI components are re-exported.** Never import from `@mui/material` — always use `@matteoaliano/forest-ui`. The only exception is `@mui/icons-material` for icons.
+
+## Layout
+
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `Box` | `import { Box } from "@matteoaliano/forest-ui"` | `sx`, `component`, all HTML attributes |
+| `Stack` | `import { Stack } from "@matteoaliano/forest-ui"` | `direction`, `spacing`, `divider`, `alignItems`, `justifyContent` |
+| `Grid` | `import { Grid } from "@matteoaliano/forest-ui"` | `container`, `size`, `spacing`, `offset`, `columns`, `direction` |
+| `Container` | `import { Container } from "@matteoaliano/forest-ui"` | `maxWidth: "xs" \| "sm" \| "md" \| "lg" \| "xl" \| false`, `fixed`, `disableGutters` |
+
+## Form Helpers
+
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `FormControl` | `import { FormControl } from "@matteoaliano/forest-ui"` | `variant`, `fullWidth`, `error`, `disabled`, `required`, `size` |
+| `FormControlLabel` | `import { FormControlLabel } from "@matteoaliano/forest-ui"` | `control` (required), `label`, `labelPlacement`, `disabled` |
+| `FormGroup` | `import { FormGroup } from "@matteoaliano/forest-ui"` | `row`, `children` |
+| `FormHelperText` | `import { FormHelperText } from "@matteoaliano/forest-ui"` | `error`, `disabled`, `margin` |
+| `FormLabel` | `import { FormLabel } from "@matteoaliano/forest-ui"` | `error`, `focused`, `required`, `disabled`, `color` |
+| `InputAdornment` | `import { InputAdornment } from "@matteoaliano/forest-ui"` | `position: "start" \| "end"`, `variant`, `disablePointerEvents` |
+| `InputBase` | `import { InputBase } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `placeholder`, `multiline`, `rows`, `startAdornment`, `endAdornment` |
+| `InputLabel` | `import { InputLabel } from "@matteoaliano/forest-ui"` | `shrink`, `variant`, `error`, `required`, `disabled` |
+| `OutlinedInput` | `import { OutlinedInput } from "@matteoaliano/forest-ui"` | `label`, `notched`, all InputBase props |
+| `FilledInput` | `import { FilledInput } from "@matteoaliano/forest-ui"` | All InputBase props |
 
 ## 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 |
+| `Button` | `import { Button } from "@matteoaliano/forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `color`, `size: "small" \| "medium" \| "large"`, `disabled`, `startIcon`, `endIcon`, `fullWidth`, `href` | `variant="contained"` |
+| `ButtonGroup` | `import { ButtonGroup } from "@matteoaliano/forest-ui"` | `variant: "contained" \| "outlined" \| "text"`, `size: "small" \| "medium" \| "large"`, `orientation: "horizontal" \| "vertical"`, `color`, `disabled`, `fullWidth` | `variant="contained"` |
+| `TextField` | `import { TextField } from "@matteoaliano/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 "@matteoaliano/forest-ui"` | `variant: "outlined" \| "filled" \| "standard"`, `size: "small" \| "medium"`, `multiple`, `displayEmpty`, `label`, `labelId`, `renderValue`, `native`, `error`, `disabled` | — |
+| `MultiSelect` | `import { MultiSelect } from "@matteoaliano/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 "@matteoaliano/forest-ui"` | `color: "default" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning"`, `size: "small" \| "medium"`, `checked`, `indeterminate`, `disabled` | — |
+| `RadioGroup` + `Radio` | `import { RadioGroup, Radio } from "@matteoaliano/forest-ui"` | `row`, `value`, `onChange`; Radio: `color`, `size: "small" \| "medium" \| "large"`, `disabled` | — |
+| `Switch` | `import { Switch } from "@matteoaliano/forest-ui"` | `color: "default" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning"`, `size: "small" \| "medium"`, `checked`, `disabled` | — |
+| `ToggleButton` + `ToggleButtonGroup` | `import { ToggleButton, ToggleButtonGroup } from "@matteoaliano/forest-ui"` | `value`, `exclusive`, `onChange`, `orientation: "horizontal" \| "vertical"`, `size: "small" \| "medium" \| "large"`, `color`, `fullWidth` | — |
+| `Fab` | `import { Fab } from "@matteoaliano/forest-ui"` | `variant: "circular" \| "extended"`, `size: "small" \| "medium" \| "large"`, `color`, `disabled`, `href` | `color="primary"` |
+| `IconButton` | `import { IconButton } from "@matteoaliano/forest-ui"` | `color: "inherit" \| "primary" \| "secondary" \| "error" \| "info" \| "success" \| "warning" \| "default"`, `size: "small" \| "medium" \| "large"`, `disabled`, `disableRipple` | — |
+| `Autocomplete` | `import { Autocomplete } from "@matteoaliano/forest-ui"` | `options`, `renderInput` (required), `multiple`, `freeSolo`, `disableClearable`, `loading`, `groupBy`, `limitTags`, `filterOptions` | — |
+| `Search` | `import { Search } from "@matteoaliano/forest-ui"` | `onClear`, `placeholder`, all TextField props (except `variant`) | `variant="outlined"`, `placeholder="Search..."`, built-in search icon and clear button |
+| `Input` | `import { Input } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `placeholder`, `multiline`, `rows`, `startAdornment`, `endAdornment`, `disabled`, `error` — all InputBase props | — |
+| `DatePicker` | `import { DatePicker } from "@matteoaliano/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` | — |
+| `Badge` | `import { Badge } from "@matteoaliano/forest-ui"` | `variant: "standard" \| "dot"`, `color`, `badgeContent`, `max`, `invisible`, `showZero`, `overlap: "rectangular" \| "circular"`, `anchorOrigin` | — |
+| `Chip` | `import { Chip } from "@matteoaliano/forest-ui"` | `variant: "filled" \| "outlined"`, `color`, `size: "small" \| "medium"`, `label`, `onDelete`, `clickable`, `avatar`, `icon` | `deleteIcon={<CloseOutlined />}` |
+| `Divider` | `import { Divider } from "@matteoaliano/forest-ui"` | `orientation: "horizontal" \| "vertical"`, `variant: "fullWidth" \| "inset" \| "middle"`, `textAlign`, `flexItem` | — |
+| `Typography` | `import { Typography } from "@matteoaliano/forest-ui"` | `variant: "h1"-"h6" \| "subtitle1" \| "subtitle2" \| "body1" \| "body2" \| "caption" \| "overline" \| "button"`, `align`, `gutterBottom`, `noWrap` | — |
+| `Tooltip` | `import { Tooltip } from "@matteoaliano/forest-ui"` | `title` (required), `placement` (12 positions), `arrow`, `followCursor`, `enterDelay`, `leaveDelay` | `arrow={true}` |
+| `Avatar` | `import { Avatar } from "@matteoaliano/forest-ui"` | `src`, `alt`, `variant: "circular" \| "rounded" \| "square"`, `sizes`, `children` (fallback) |
+| `AvatarGroup` | `import { AvatarGroup } from "@matteoaliano/forest-ui"` | `max`, `total`, `spacing`, `variant` |
+| `ImageList` | `import { ImageList } from "@matteoaliano/forest-ui"` | `variant: "masonry" \| "quilted" \| "standard" \| "woven"`, `cols`, `gap`, `rowHeight` |
+| `ImageListItem` | `import { ImageListItem } from "@matteoaliano/forest-ui"` | `cols`, `rows` |
+| `ImageListItemBar` | `import { ImageListItemBar } from "@matteoaliano/forest-ui"` | `title`, `subtitle`, `position`, `actionIcon` |
+| `Logo` | `import { Logo } from "@matteoaliano/forest-ui"` | `product: "wsuite" \| "studio" \| "feedati"`, `variant: "logo" \| "logomark"`, `sx` | `product="wsuite"`, `variant="logo"`, `height={32}` |
+| `Rating` | `import { Rating } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `precision`, `max`, `size`, `readOnly`, `disabled` |
+| `Table` family | `import { Table, TableHead, TableBody, TableRow, TableCell, TableContainer } from "@matteoaliano/forest-ui"` | Table: `size: "small" \| "medium"`, `stickyHeader`; TableCell: `align`, `padding`, `sortDirection`, `variant`; TableRow: `hover`, `selected` | — |
+| `DataGrid` | `import { DataGrid, type GridColDef } from "@matteoaliano/forest-ui"` | `rows`, `columns`, `paginationModel`, `sortModel`, `filterModel`, `checkboxSelection`, `loading`, `density` | — |
+| `List` family | `import { List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListSubheader } from "@matteoaliano/forest-ui"` | `dense`, `disablePadding`; ListItemButton: `selected`, `disabled`; ListItemText: `primary`, `secondary` | — |
+| `TableFooter` | `import { TableFooter } from "@matteoaliano/forest-ui"` | `component`, `children` |
+| `TablePagination` | `import { TablePagination } from "@matteoaliano/forest-ui"` | `count`, `page`, `rowsPerPage`, `onPageChange`, `onRowsPerPageChange` |
+| `TableSortLabel` | `import { TableSortLabel } from "@matteoaliano/forest-ui"` | `active`, `direction: "asc" \| "desc"`, `onClick` |
+| `ListItemSecondaryAction` | `import { ListItemSecondaryAction } from "@matteoaliano/forest-ui"` | `children` |
+| `SnackbarContent` | `import { SnackbarContent } from "@matteoaliano/forest-ui"` | `message`, `action` |
 
 ## 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` | — |
+| `Accordion` family | `import { Accordion, AccordionSummary, AccordionDetails, AccordionActions } from "@matteoaliano/forest-ui"` | `expanded`, `defaultExpanded`, `onChange`, `disabled`, `disableGutters`, `square` | — |
+| `AppBar` + `Toolbar` | `import { AppBar, Toolbar } from "@matteoaliano/forest-ui"` | `position`, `color`, `elevation`; Toolbar: `variant: "dense" \| "regular"` | — |
+| `AppBarNavItem` | `import { AppBarNavItem } from "@matteoaliano/forest-ui"` | `label` (required), `icon`, `selected`, `href`, `sx` — navigation button for AppBar | — |
+| `Card` family | `import { Card, CardContent, CardHeader, CardActions, CardMedia } from "@matteoaliano/forest-ui"` | `variant: "elevation" \| "outlined"`, `elevation`, `raised`; CardHeader: `title`, `subheader`, `avatar`, `action` | — |
+| `Paper` | `import { Paper } from "@matteoaliano/forest-ui"` | `variant: "elevation" \| "outlined"`, `elevation` (0-24), `square` | — |
+| `CardActionArea` | `import { CardActionArea } from "@matteoaliano/forest-ui"` | `onClick`, `href`, `disabled` |
+| `Drawer` | `import { Drawer } from "@matteoaliano/forest-ui"` | `open`, `onClose`, `anchor: "left" \| "right" \| "top" \| "bottom"`, `variant: "permanent" \| "persistent" \| "temporary"` |
+| `SwipeableDrawer` | `import { SwipeableDrawer } from "@matteoaliano/forest-ui"` | `onOpen` (required), `onClose` (required), `open`, `anchor`, `swipeAreaWidth` |
 
 ## 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` | — |
+| `Alert` + `AlertTitle` | `import { Alert, AlertTitle } from "@matteoaliano/forest-ui"` | `severity: "success" \| "info" \| "warning" \| "error"`, `variant: "filled" \| "outlined" \| "standard"`, `color`, `icon`, `action`, `onClose` | — |
+| `Dialog` family | `import { Dialog, DialogTitle, DialogContent, DialogActions, DialogContentText } from "@matteoaliano/forest-ui"` | `open` (required), `onClose`, `fullWidth`, `maxWidth`, `fullScreen`, `scroll: "paper" \| "body"` | — |
+| `Backdrop` | `import { Backdrop } from "@matteoaliano/forest-ui"` | `open` (required), `invisible`, `onClick` | — |
+| `LinearProgress` | `import { LinearProgress } from "@matteoaliano/forest-ui"` | `variant: "indeterminate" \| "determinate" \| "buffer" \| "query"`, `value` (0-100), `color` | — |
+| `CircularProgress` | `import { CircularProgress } from "@matteoaliano/forest-ui"` | `variant: "indeterminate" \| "determinate"`, `value` (0-100), `color`, `size`, `thickness` | — |
+| `Skeleton` | `import { Skeleton } from "@matteoaliano/forest-ui"` | `variant: "text" \| "circular" \| "rectangular" \| "rounded"`, `animation: "pulse" \| "wave" \| false`, `width`, `height` | — |
+| `Modal` | `import { Modal } from "@matteoaliano/forest-ui"` | `open` (required), `onClose`, `children`, `keepMounted`, `disableAutoFocus`, `disableEscapeKeyDown` | — |
+| `Popover` | `import { Popover } from "@matteoaliano/forest-ui"` | `open` (required), `anchorEl`, `onClose`, `anchorOrigin`, `transformOrigin`, `elevation` | — |
+| `Snackbar` | `import { Snackbar } from "@matteoaliano/forest-ui"` | `open`, `message`, `autoHideDuration`, `onClose`, `action`, `anchorOrigin` | — |
+| `Slider` | `import { Slider } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `min`, `max`, `step`, `marks`, `valueLabelDisplay`, `orientation`, `size` | — |
 
 ## 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"` |
+| `Breadcrumbs` | `import { Breadcrumbs } from "@matteoaliano/forest-ui"` | `separator`, `maxItems`, `itemsAfterCollapse`, `itemsBeforeCollapse` | — |
+| `Link` | `import { Link } from "@matteoaliano/forest-ui"` | `href`, `underline: "none" \| "hover" \| "always"`, `color`, `variant` | — |
+| `Menu` + `MenuList` | `import { Menu, MenuList } from "@matteoaliano/forest-ui"` | Menu: `open` (required), `anchorEl`, `onClose`; use with `MenuItem` | — |
+| `Pagination` | `import { Pagination } from "@matteoaliano/forest-ui"` | `count`, `page`, `onChange`, `variant: "text" \| "outlined"`, `shape`, `size`, `color`, `showFirstButton`, `showLastButton` | — |
+| `Stepper` family | `import { Stepper, Step, StepLabel } from "@matteoaliano/forest-ui"` | `activeStep`, `orientation`, `alternativeLabel`, `nonLinear`; Step: `completed`, `disabled`; StepLabel: `optional`, `error` | — |
+| `Tabs` + `Tab` | `import { Tabs, Tab } from "@matteoaliano/forest-ui"` | Tabs: `value`, `onChange`, `variant: "standard" \| "scrollable" \| "fullWidth"`, `orientation`, `centered`; Tab: `label`, `icon`, `iconPosition`, `disabled`, `value` | — |
+| `SidebarNav` | `import { SidebarNav, SidebarItem, useSidebar } from "@matteoaliano/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` | — |
+| `BottomNavigation` | `import { BottomNavigation } from "@matteoaliano/forest-ui"` | `value`, `onChange`, `showLabels` |
+| `BottomNavigationAction` | `import { BottomNavigationAction } from "@matteoaliano/forest-ui"` | `label`, `icon`, `value`, `showLabel` |
+| `SpeedDial` | `import { SpeedDial } from "@matteoaliano/forest-ui"` | `ariaLabel` (required), `open`, `onOpen`, `onClose`, `icon`, `direction` |
+| `SpeedDialAction` | `import { SpeedDialAction } from "@matteoaliano/forest-ui"` | `icon`, `tooltipTitle`, `onClick` |
+| `SpeedDialIcon` | `import { SpeedDialIcon } from "@matteoaliano/forest-ui"` | `icon`, `openIcon` |
+| `MobileStepper` | `import { MobileStepper } from "@matteoaliano/forest-ui"` | `steps`, `activeStep`, `variant: "dots" \| "progress" \| "text"`, `nextButton`, `backButton` |
+| `PaginationItem` | `import { PaginationItem } from "@matteoaliano/forest-ui"` | `type`, `page`, `selected`, `disabled`, `shape`, `size` |
+| `StepButton` | `import { StepButton } from "@matteoaliano/forest-ui"` | `optional`, `children`, `onClick` |
+| `StepConnector` | `import { StepConnector } from "@matteoaliano/forest-ui"` | (styling via theme) |
+| `StepContent` | `import { StepContent } from "@matteoaliano/forest-ui"` | `children`, `TransitionComponent`, `transitionDuration` |
+| `StepIcon` | `import { StepIcon } from "@matteoaliano/forest-ui"` | `active`, `completed`, `error`, `icon` |
+| `TabScrollButton` | `import { TabScrollButton } from "@matteoaliano/forest-ui"` | `direction: "left" \| "right"`, `orientation`, `disabled` |
 
 ## Charts
 
-Requires `@mui/x-charts` peer dependency. Chart colors are automatically applied from the theme's 12-color series palette.
+Requires `@mui/x-charts` peer dependency. All chart components are re-exported from `@matteoaliano/forest-ui` — never import directly from `@mui/x-charts`. Chart colors are automatically applied from the theme's 12-color series palette.
+
+### Chart Components
 
 | 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) | — |
+| `BarChart` | `import { BarChart } from "@matteoaliano/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 "@matteoaliano/forest-ui"` | `series`, `colors`, `xAxis`, `yAxis`, `width`, `height` | `curve="linear"`, `strokeWidth=3`, `grid horizontal`, highlight/fade on hover |
+| `PieChart` | `import { PieChart } from "@matteoaliano/forest-ui"` | `series` (data: `{ id, value, label, color? }[]`), `colors`, `width`, `height` | highlight/fade on hover |
+| `ScatterChart` | `import { ScatterChart } from "@matteoaliano/forest-ui"` | `series`, `colors`, `xAxis`, `yAxis`, `width`, `height` | — |
+| `Gauge` | `import { Gauge } from "@matteoaliano/forest-ui"` | `value`, `valueMin`, `valueMax`, `startAngle`, `endAngle`, `width`, `height` | — |
+| `SparkLineChart` | `import { SparkLineChart } from "@matteoaliano/forest-ui"` | `data`, `plotType: "line" \| "bar"`, `width`, `height`, `colors` | — |
+| `useChartColors` | `import { useChartColors } from "@matteoaliano/forest-ui"` | `useChartColors(count)` — returns `string[]` of theme chart series colors (max 12) | — |
+
+### Chart Composition Primitives
+
+For building custom chart layouts, these low-level primitives are also available:
+
+- **Containers:** `ChartContainer`, `ResponsiveChartContainer`, `ChartsSurface`, `ChartsClipPath`
+- **Axis & Grid:** `ChartsAxis`, `ChartsXAxis`, `ChartsYAxis`, `ChartsGrid`, `ChartsReferenceLine`
+- **Legend & Tooltip:** `ChartsLegend`, `DefaultChartsLegend`, `ChartsTooltip`, `ChartsAxisTooltipContent`, `ChartsItemTooltipContent`, `ContinuousColorLegend`, `PiecewiseColorLegend`
+- **Gauge parts:** `GaugeContainer`, `GaugeReferenceArc`, `GaugeValueArc`, `GaugeValueText`
+- **Plot layers — Bar:** `BarPlot`, `BarElement`, `BarElementPath`, `BarLabel`
+- **Plot layers — Line & Area:** `LinePlot`, `LineElement`, `AreaPlot`, `AreaElement`, `LineHighlightPlot`, `MarkPlot`, `AnimatedArea`, `AnimatedLine`
+- **Plot layers — Pie:** `PiePlot`, `PieArc`, `PieArcPlot`, `PieArcLabel`, `PieArcLabelPlot`
+- **Plot layers — Scatter:** `ScatterPlot`, `Scatter`
+- **Interaction:** `ChartsAxisHighlight`, `ChartsOnAxisClickHandler`, `ChartsVoronoiHandler`, `HighlightedProvider`
+- **Text:** `ChartsText`
+- **Hooks:** `useDrawingArea`, `useChartId`, `useSvgRef`, `useXAxis`, `useXScale`, `useYAxis`, `useYScale`, `useAxisTooltip`, `useItemTooltip`, `useMouseTracker`, `useHighlighted`, `useItemHighlighted`, `useGaugeState`
+- **Color palettes:** `blueberryTwilightPalette`, `cheerfulFiestaPalette`, `mangoFusionPalette` (each with `Light` and `Dark` variants)
+
+## Transitions
+
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `Collapse` | `import { Collapse } from "@matteoaliano/forest-ui"` | `in`, `timeout`, `orientation: "vertical" \| "horizontal"`, `collapsedSize`, `unmountOnExit` |
+| `Fade` | `import { Fade } from "@matteoaliano/forest-ui"` | `in`, `timeout`, `appear` |
+| `Grow` | `import { Grow } from "@matteoaliano/forest-ui"` | `in`, `timeout`, `appear` |
+| `Slide` | `import { Slide } from "@matteoaliano/forest-ui"` | `in`, `direction: "up" \| "down" \| "left" \| "right"`, `timeout`, `container` |
+| `Zoom` | `import { Zoom } from "@matteoaliano/forest-ui"` | `in`, `timeout`, `appear` |
+
+## Utilities
+
+| Component | Import | Key Props |
+|-----------|--------|-----------|
+| `ClickAwayListener` | `import { ClickAwayListener } from "@matteoaliano/forest-ui"` | `onClickAway` (required), `mouseEvent`, `touchEvent`, `children` |
+| `NoSsr` | `import { NoSsr } from "@matteoaliano/forest-ui"` | `defer`, `fallback`, `children` |
+| `Portal` | `import { Portal } from "@matteoaliano/forest-ui"` | `container`, `disablePortal`, `children` |
+| `Popper` | `import { Popper } from "@matteoaliano/forest-ui"` | `open` (required), `anchorEl`, `placement`, `transition`, `modifiers` |
+| `TextareaAutosize` | `import { TextareaAutosize } from "@matteoaliano/forest-ui"` | `minRows`, `maxRows`, all textarea HTML attributes |
+| `SvgIcon` | `import { SvgIcon } from "@matteoaliano/forest-ui"` | `viewBox`, `fontSize`, `color`, `children` (SVG path elements) |
+| `ButtonBase` | `import { ButtonBase } from "@matteoaliano/forest-ui"` | `onClick`, `disabled`, `href`, `component`, `disableRipple` |
+| `GlobalStyles` | `import { GlobalStyles } from "@matteoaliano/forest-ui"` | `styles` (required) — CSS object or function |
+
+## Hooks
+
+| Hook | Import | Signature |
+|------|--------|-----------|
+| `useMediaQuery` | `import { useMediaQuery } from "@matteoaliano/forest-ui"` | `useMediaQuery(query): boolean` — responsive breakpoint detection |
+| `useScrollTrigger` | `import { useScrollTrigger } from "@matteoaliano/forest-ui"` | `useScrollTrigger(options?): boolean` — detect scroll for hide-on-scroll AppBars |
+| `useFormControl` | `import { useFormControl } from "@matteoaliano/forest-ui"` | `useFormControl(): FormControlState` — access parent FormControl state |
+| `useTheme` | `import { useTheme } from "@matteoaliano/forest-ui"` | `useTheme(): Theme` — access the current MUI theme object |

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

@@ -5,8 +5,7 @@
 ### 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
+import { TextField, Button, Select, MenuItem, Checkbox, Box } from "@matteoaliano/forest-ui";
 
 function ContactForm() {
   return (
@@ -135,24 +134,95 @@ function ConfirmDialog({ open, onClose, onConfirm }) {
 }
 ```
 
-### Sidebar Navigation
+### App Shell (AppBar + Sidebar Navigation)
+
+The standard application layout: a full-width AppBar at the top with a SidebarNav below it. The Toolbar uses three equal `flex: 1` columns so the Search stays visually centered. The sidebar drawer uses `position: relative` to flow inside the layout instead of overlaying as a fixed panel.
 
 ```tsx
-import { SidebarNav, SidebarItem } from "@matteoaliano/forest-ui";
-import DashboardOutlined from "@mui/icons-material/DashboardOutlined";
+import { useState } from "react";
+import {
+  AppBar, Toolbar, Logo, Search, IconButton, Badge,
+  SidebarNav, SidebarItem, List, Typography, Box, Avatar,
+} from "@matteoaliano/forest-ui";
+import NotificationsOutlined from "@mui/icons-material/NotificationsOutlined";
 import SettingsOutlined from "@mui/icons-material/SettingsOutlined";
+import HomeOutlined from "@mui/icons-material/HomeOutlined";
+import BarChartOutlined from "@mui/icons-material/BarChartOutlined";
+import PeopleOutlined from "@mui/icons-material/PeopleOutlined";
+
+function AppShell({ children }) {
+  const [sidebarOpen, setSidebarOpen] = useState(true);
 
-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>
+    <Box sx={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+      {/* ── App Bar ── */}
+      <AppBar
+        position="sticky"
+        elevation={0}
+        sx={{ zIndex: (theme) => theme.zIndex.drawer + 1 }}
+      >
+        <Toolbar variant="dense" sx={{ px: { xs: "16px", sm: "16px" } }}>
+          {/* Left — Logo */}
+          <Box sx={{ flex: 1, display: "flex", alignItems: "center" }}>
+            <Logo product="wsuite" />
+          </Box>
+          {/* Center — Search (always visually centered) */}
+          <Box sx={{ flex: 1, display: "flex", justifyContent: "center" }}>
+            <Search size="small" sx={{ width: "100%", maxWidth: 480 }} />
+          </Box>
+          {/* Right — Actions */}
+          <Box sx={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "flex-end", gap: 1 }}>
+            <IconButton size="small" color="inherit">
+              <Badge color="error" variant="dot">
+                <NotificationsOutlined fontSize="small" />
+              </Badge>
+            </IconButton>
+            <IconButton size="small" color="inherit">
+              <SettingsOutlined fontSize="small" />
+            </IconButton>
+            <Avatar sx={{ width: 28, height: 28, fontSize: 13 }}>MA</Avatar>
+          </Box>
+        </Toolbar>
+      </AppBar>
+
+      {/* ── Body: Sidebar + Content ── */}
+      <Box sx={{ display: "flex", flexGrow: 1, overflow: "hidden" }}>
+        <SidebarNav
+          open={sidebarOpen}
+          onOpenChange={setSidebarOpen}
+          sx={{
+            height: "100%",
+            "& .MuiDrawer-paper": { position: "relative", height: "100%" },
+          }}
+        >
+          <List>
+            <SidebarItem icon={<HomeOutlined />} label="Home" selected />
+            <SidebarItem icon={<BarChartOutlined />} label="Analytics" />
+            <SidebarItem icon={<PeopleOutlined />} label="Users" />
+            <SidebarItem icon={<SettingsOutlined />} label="Settings" />
+          </List>
+        </SidebarNav>
+
+        <Box
+          component="main"
+          sx={{ flexGrow: 1, p: 3, overflow: "auto", backgroundColor: "background.paper" }}
+        >
+          {children}
+        </Box>
+      </Box>
+    </Box>
   );
 }
 ```
 
+**Key patterns:**
+- `Toolbar variant="dense"` — 48px height instead of 64px
+- Three `flex: 1` columns in Toolbar — keeps Search centered regardless of left/right content width
+- `px: { xs: "16px", sm: "16px" }` on Toolbar — aligns logo with sidebar icons (overrides MUI's responsive 24px default)
+- `position: "relative"` on drawer paper — makes sidebar flow in layout, not overlay
+- `height: "100%"` on SidebarNav — sidebar border extends full height
+- `backgroundColor: "background.paper"` on content — contrasts with sidebar/AppBar background
+
 ### Charts
 
 Colors are automatically assigned from the theme's 12-series palette. Override with the `colors` prop if needed.

package/skills/forest-internal/SKILL.md

@@ -3,14 +3,14 @@ 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.4.3
+  version: 0.5.0
 ---
 
 # 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`.
+1. **NEVER import from `@mui/material` directly.** Always import from `@matteoaliano/forest-ui`. All MUI components, layout primitives, transitions, form helpers, and hooks are re-exported. The only exception is `@mui/icons-material` — import icons from there directly.
 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.
@@ -23,6 +23,8 @@ metadata:
 npm install @matteoaliano/forest-ui @mui/material @mui/x-data-grid @mui/x-date-pickers @mui/x-charts dayjs @emotion/react @emotion/styled
 ```
 
+> **Note:** `@mui/material`, `@mui/x-data-grid`, `@mui/x-date-pickers`, and `@mui/x-charts` are **peer dependencies** — install them but **always import from `@matteoaliano/forest-ui`**, not from these packages directly. Forest UI re-exports everything.
+
 ```tsx
 import { ForestProvider } from "@matteoaliano/forest-ui";
 
@@ -39,30 +41,39 @@ function App() {
 
 - **Aeonik** — the default font for all UI text (headings, body, labels, buttons, etc.)
 - **Aeonik Mono** — use for numeric values: prices, stats, table figures, counters, dates, IDs, code snippets
-- **Alkemy Beta** — reserved exclusively for branding elements (e.g. Logo component). Never use for general UI text
+- **Alkemy Beta** — use for page titles (h1/hero headings). Not for general UI text
 
 Import the font CSS files you need in your app entry point:
 
 ```tsx
 import "@matteoaliano/forest-ui/fonts/aeonik/aeonik.css";
 import "@matteoaliano/forest-ui/fonts/aeonik-mono/aeonik-mono.css";
-// Only if using branding/logo elements:
 import "@matteoaliano/forest-ui/fonts/alkemy-beta/alkemy-beta.css";
 ```
 
 ## Available Components
 
-**Inputs:** Button, ButtonGroup, TextField, Select + MenuItem, MultiSelect, Checkbox, RadioGroup + Radio, Switch, ToggleButton + ToggleButtonGroup, Fab, IconButton, Autocomplete, Search, DatePicker
+**Inputs:** Button, ButtonGroup, TextField, Select + MenuItem, MultiSelect, Checkbox, RadioGroup + Radio, Switch, ToggleButton + ToggleButtonGroup, Fab, IconButton, Autocomplete, Search, DatePicker, Input
+
+**Data Display:** Badge, Chip, Divider, Typography, Tooltip, Logo, Table family (Table, TableHead, TableBody, TableRow, TableCell, TableContainer, TableFooter, TablePagination, TableSortLabel), DataGrid + GridColDef, List family (List, ListItem, ListItemButton, ListItemIcon, ListItemText, ListItemAvatar, ListItemSecondaryAction, ListSubheader), Avatar + AvatarGroup, ImageList + ImageListItem + ImageListItemBar, Rating
+
+**Surfaces:** Accordion family, AppBar + Toolbar + AppBarNavItem, Card family + CardActionArea, Paper, Drawer + SwipeableDrawer
+
+**Feedback:** Alert + AlertTitle, Dialog family, Backdrop, LinearProgress, CircularProgress, Skeleton, Modal, Popover, Snackbar + SnackbarContent, Slider
+
+**Navigation:** Breadcrumbs, Link, Menu + MenuList, Pagination + PaginationItem, Stepper family (Stepper, Step, StepLabel, StepButton, StepConnector, StepContent, StepIcon), Tabs + Tab + TabScrollButton, SidebarNav + SidebarItem + useSidebar, BottomNavigation + BottomNavigationAction, SpeedDial + SpeedDialAction + SpeedDialIcon, MobileStepper
+
+**Layout:** Box, Stack, Grid, Container
 
-**Data Display:** Badge, Chip, Divider, Typography, Tooltip, Table family (Table, TableHead, TableBody, TableRow, TableCell, TableContainer), DataGrid + GridColDef, List family
+**Form Helpers:** FormControl, FormControlLabel, FormGroup, FormHelperText, FormLabel, InputAdornment, InputBase, InputLabel, OutlinedInput, FilledInput
 
-**Surfaces:** Accordion family, AppBar + Toolbar, Card family, Paper
+**Transitions:** Collapse, Fade, Grow, Slide, Zoom
 
-**Feedback:** Alert + AlertTitle, Dialog family, Backdrop, LinearProgress, CircularProgress, Skeleton, Modal, Popover, Snackbar
+**Utilities:** ClickAwayListener, NoSsr, Portal, Popper, TextareaAutosize, SvgIcon, ButtonBase, GlobalStyles
 
-**Navigation:** Breadcrumbs, Link, Menu + MenuList, Pagination, Stepper family, Tabs + Tab, SidebarNav + SidebarItem + useSidebar
+**Hooks:** useMediaQuery, useScrollTrigger, useFormControl, useTheme
 
-**Charts:** BarChart, LineChart, PieChart, useChartColors
+**Charts:** BarChart, LineChart, PieChart, ScatterChart, Gauge, SparkLineChart, useChartColors, plus composition primitives (see components.md)
 
 See `references/components.md` for full API details and `references/patterns.md` for code examples.
 
@@ -75,7 +86,7 @@ See `references/components.md` for full API details and `references/patterns.md`
 
 ## Common Anti-Patterns
 
-1. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui`
+1. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui` — all components, hooks, and layout primitives are available from 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