@matteoaliano/forest-ui 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matteoaliano/forest-ui",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Forest Design System — themed MUI components",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -30,7 +30,7 @@
     "fonts"
   ],
   "scripts": {
-    "sync": "node bin/sync.mjs",
+    "sync": "node bin/sync.mjs --internal",
     "lint": "eslint src --ext .ts,.tsx",
     "build": "tsup",
     "prepublishOnly": "tsup && node bin/sync.mjs",

package/skills/forest-alkemy-plus/SKILL.md

@@ -3,158 +3,52 @@ name: forest-alkemy-plus
 description: Forest UI Design System rules for the Alkemy+ (charcoal/red) preset. Enforces correct imports, component usage, and theming with @matteoaliano/forest-ui. Use when the project uses forest-ui, forest-alkemy-plus preset, or when user builds UI components in a forest-ui project. Triggers on "forest", "forest-ui", "forest alkemy", "forest alkemy+", "@matteoaliano/forest-ui".
 metadata:
   author: Forest Design System
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Forest UI — Alkemy+ Preset
 
-## Golden Rules
+## Golden Rules (non-negotiable)
 
-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 import the Forest font CSS at app entry** (see Setup → Step 2). The package bundles Aeonik / Aeonik Mono / AlkemyBETA as `.woff2` + `@font-face` CSS, but it does **not** auto-inject them — the consuming app must import the CSS. Skip this and `font-family: "Aeonik"` silently falls back to system sans-serif (Helvetica / Arial / DejaVu), inconsistently across machines. This is the #1 reason Forest sites "don't look right".
-3. **ALWAYS wrap your app root with `<ForestProvider>`** — it applies the theme and CSS baseline.
-4. **NEVER use inline colors or spacing values.** Use design tokens or MUI's `sx` prop with theme values (`p: 4`, `backgroundColor: "primary.main"`).
-5. **NEVER create custom component wrappers** for things Forest UI already provides.
-6. **TypeScript is required.** All components export their prop types (e.g. `type ButtonProps`).
-7. **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.
-8. **A clickable card MUST use `CardActionArea`.** Wrap the card's content in `<CardActionArea onClick={…}>` — never put `onClick`/`href` on a bare `<Card>`. `CardActionArea` carries the faux-3D bevel + glaze + press affordance (the same interaction language as `Button`), which is how users tell a clickable card apart from a static one. Static (non-interactive) cards must **not** use it.
-9. **Every authenticated product surface MUST use the App Shell layout.** Build the top-level chrome from the App Shell pattern (AppBar + SidebarNav) — see Setup → App Shell and `references/patterns.md`. Its AppBar actions MUST include the color-mode toggle (`ColorModeToggle`), which is the single sanctioned dark-mode switch. Do not hand-roll a bespoke app frame or scatter ad-hoc theme toggles elsewhere.
+1. **Import only from `@matteoaliano/forest-ui`** — never `@mui/material`. Icons only from `@mui/icons-material/*Outlined` (always the Outlined variant).
+2. **Wrap the app root in `<ForestProvider preset="forest-alkemy+">`** and import the three font CSS files at entry (below). Skipping the fonts is the #1 "looks wrong" cause.
+3. **Every authenticated surface is `<AppShell>`; every routed page is `<Page>`.** Never hand-roll app chrome or page scaffolds. The color-mode toggle is built into AppShell — never add your own.
+4. **Every widget, chart, or table inside a `<Page>` lives in a `<Card>`.** A clickable card wraps its content in `<CardActionArea>`.
+5. **No raw colors or spacing** (`#hex`, `rgb()`, `"16px"`) — use theme tokens via `sx` (`p: 4`, `color: "text.secondary"`, `backgroundColor: "primary.main"`). Never override a component's internals.
+6. **Dark mode is built in** — `defaultMode` on ForestProvider + `useColorScheme`. Never `createTheme`, a second `ThemeProvider`, or `.dark` CSS.
 
-## Setup
-
-### Step 1 — Install
-
-```bash
-npm install @matteoaliano/forest-ui \
-  @mui/material@^7 @mui/icons-material@^7 \
-  @mui/x-charts@^7 @mui/x-data-grid@^7 @mui/x-date-pickers@^8 \
-  @emotion/react @emotion/styled dayjs
-```
-
-> **Note:** Every `@mui/*` package above is a **peer dependency** of `@matteoaliano/forest-ui`. Install them at the pinned major versions shown — newer majors are not yet supported and will fail `npm install` with `ERESOLVE`. Always import components, hooks, and layout primitives from `@matteoaliano/forest-ui` (Forest UI re-exports them with branded defaults). The single exception is `@mui/icons-material` — import icons from there directly, using the Outlined variant (e.g. `import { CloseOutlined } from "@mui/icons-material"`).
-
-### Step 2 — Load the fonts (CRITICAL — do this before anything else)
-
-The Forest preset sets `fontFamily: '"Aeonik", sans-serif'`. Without the matching `@font-face` rules, the browser cannot resolve "Aeonik" and silently falls back to a system font. **Forest UI ships the font files in the npm tarball, but the consuming app must import the CSS.** Add these three imports at the top of your root entry file:
+## Setup (once per app)
 
 ```tsx
-// Next.js App Router → app/layout.tsx (above any other CSS imports)
-// Next.js Pages Router → pages/_app.tsx
-// Vite / CRA → src/main.tsx or src/index.tsx
+// App entry — fonts first, then the provider:
 import "@matteoaliano/forest-ui/fonts/aeonik/aeonik.css";
 import "@matteoaliano/forest-ui/fonts/aeonik-mono/aeonik-mono.css";
 import "@matteoaliano/forest-ui/fonts/alkemy-beta/alkemy-beta.css";
-```
-
-No `public/fonts/` copy, no `next/font/local`, no manual `@font-face` rules — the bundler resolves the relative `.woff2` URLs inside the CSS automatically.
-
-**For Next.js**, also add `transpilePackages` so Turbopack resolves the CSS subpath exports cleanly:
+import { ForestProvider } from "@matteoaliano/forest-ui";
 
-```ts
-// next.config.ts
-const nextConfig = {
-  transpilePackages: ["@matteoaliano/forest-ui"],
-  experimental: {
-    optimizePackageImports: [
-      "@matteoaliano/forest-ui",
-      "@mui/material",
-      "@mui/icons-material",
-    ],
-  },
-};
-export default nextConfig;
+<ForestProvider preset="forest-alkemy+" defaultMode="system">{app}</ForestProvider>
 ```
 
-**Verify it worked.** Open DevTools after running `next dev`:
-
-1. **Network tab → filter "font"** — you should see `aeonik-regular.woff2` and friends loading with `200 OK` from `/_next/static/media/...` (or your bundler's asset path).
-2. **Elements → Computed → font-family** on a `<Typography>` — should read `"Aeonik", sans-serif`.
-3. **Elements → Rendered Fonts** (Chrome only) — should say `Aeonik — Web font`, not `Arial — Local file` or `Helvetica — Local file`.
+Install: `npm install @matteoaliano/forest-ui @mui/material@^7 @mui/icons-material@^7 @mui/x-charts@^7 @mui/x-data-grid@^7 @mui/x-date-pickers@^8 @emotion/react @emotion/styled dayjs`. Next.js needs `transpilePackages: ["@matteoaliano/forest-ui"]` — details + font troubleshooting in `references/patterns.md`.
 
-If Network shows 404s on the woff2 files, the `transpilePackages` step is missing or the bundler isn't picking up the package's subpath exports.
-
-### Step 3 — Wrap your app
+## Layout baseline (mandatory shape of every screen)
 
 ```tsx
-import { ForestProvider } from "@matteoaliano/forest-ui";
-
-function App() {
-  return (
-    <ForestProvider preset="forest-alkemy+">
-      {/* All app content here */}
-    </ForestProvider>
-  );
-}
+<AppShell navItems={[{ label: "Home", icon: <HomeOutlined />, href: "/", active: true }]} search actions={...}>
+  <Page title="Home" breadcrumbs={[{ label: "Home" }]}>
+    <Card>…every widget/chart/table goes in a Card…</Card>
+  </Page>
+</AppShell>
 ```
 
-## Dark Mode
-
-The preset ships a dark color scheme (MUI `colorSchemes` / CSS variables). It
-activates on a **`.dark` class** on any ancestor — same convention as
-`@matteoaliano/forest-web`.
-
-- Class toggle: put `dark` on `<html>` (`document.documentElement.classList.toggle("dark", isDark)`) — NOT a deep wrapper, or portaled components (Modal/Menu/Tooltip) stay light. `useColorScheme` handles this for you.
-- Initial scheme: `<ForestProvider preset="forest-alkemy+" defaultMode="system">` — `defaultMode` is `"light"` (default), `"dark"`, or `"system"` (follows `prefers-color-scheme`).
-- Programmatic: `const { mode, setMode } = useColorScheme();` (re-exported from the package) — call `setMode("dark" | "light" | "system")`.
-- Next.js App Router: render `<InitColorSchemeScript attribute="class" />` (re-exported) as the first child of `<body>` to avoid a flash of the wrong scheme.
-- **Where the switch lives:** expose it as the `ColorModeToggle` in the App Shell's AppBar actions (see `references/patterns.md` → App Shell). That is the sanctioned, single entry point for toggling dark mode — don't duplicate it.
-
-Do NOT hand-roll a second theme or a `.dark` stylesheet — the palette already
-inverts through the preset's dark tokens; just toggle the class or use `setMode`.
-
-## Typography & Fonts
-
-- **Aeonik** — the default font for all UI text (headings, body, labels, buttons, etc.). Family name: `"Aeonik"`.
-- **Aeonik Mono** — use for numeric values: prices, stats, table figures, counters, dates, IDs, code snippets. Family name: `"Aeonik Mono"`.
-- **AlkemyBETA** — editorial display face for page titles / hero h1. Family name: **`"AlkemyBETA"`** (one word, no space — do not write `"Alkemy Beta"`, it will not resolve). Not auto-applied by the preset — opt in explicitly:
-  ```tsx
-  <Typography variant="h1" sx={{ fontFamily: '"AlkemyBETA", serif' }}>...</Typography>
-  ```
-
-The three CSS imports in Setup → Step 2 register all of these families. If a Forest site looks like Arial or Helvetica, you skipped Step 2.
-
-## Available Components
-
-**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
-
-**Form Helpers:** FormControl, FormControlLabel, FormGroup, FormHelperText, FormLabel, InputAdornment, InputBase, InputLabel, OutlinedInput, FilledInput
-
-**Transitions:** Collapse, Fade, Grow, Slide, Zoom
-
-**Utilities:** ClickAwayListener, NoSsr, Portal, Popper, TextareaAutosize, SvgIcon, ButtonBase, GlobalStyles
-
-**Hooks:** useMediaQuery, useScrollTrigger, useFormControl, useTheme
-
-**Charts:** BarChart, LineChart, PieChart, ScatterChart, Gauge, SparkLineChart, useChartColors, plus composition primitives (see components.md)
-
-See `references/components.md` for full API details, `references/patterns.md` for code examples, and `references/upgrading.md` for update / re-sync guidance.
+Full APIs (nav router escape, logoVariant, brand/search/actions slots, Page actions/maxWidth) in `references/patterns.md` → "App Shell + Page".
 
-## Tooltip vs Popover
+## Fonts
 
-- **Tooltip** — Use for **text-only hints**. The Tooltip has a dark (black) background and is meant for short, plain-text labels or descriptions. Do not nest rich content inside a Tooltip.
-- **Popover** — Use when you need to display **rich or interactive content** such as Chips, lists, buttons, or any nested components. Popover renders in a neutral surface container that supports arbitrary children.
+**Aeonik** = all UI text. **Aeonik Mono** = numbers (prices, stats, dates, IDs, code). **`"AlkemyBETA"`** (one word!) = hero/h1 titles only, opt-in via `sx={{ fontFamily: '"AlkemyBETA", serif' }}`.
 
-**Rule of thumb:** If the overlay content is just a string, use `<Tooltip>`. If it contains components, use `<Popover>`.
+## Components
 
-## Common Anti-Patterns
+Inputs: Button, ButtonGroup, TextField, Select+MenuItem, MultiSelect, Checkbox, RadioGroup, Switch, ToggleButton, Fab, IconButton (variant: text|contained|outlined), Autocomplete, Search, DatePicker, Input · Data: Badge, Chip, Divider, Typography, Tooltip (plain text only; rich content → Popover), Logo, Table family, DataGrid, List family, Avatar, ImageList, Rating · Surfaces: Accordion, AppBar+Toolbar, Card family, Paper, Drawer · Feedback: Alert, Dialog, Backdrop, Progress, Skeleton, Modal, Popover, Snackbar, Slider · Navigation: Breadcrumbs, Link, Menu, Pagination, Stepper, Tabs, SidebarNav+SidebarItem, BottomNavigation, SpeedDial · Layout: **AppShell, Page**, Box, Stack, Grid, Container · Charts: BarChart, LineChart, PieChart, ScatterChart, Gauge, SparkLineChart · plus form helpers, transitions, utilities, hooks (useMediaQuery, useTheme, useColorScheme).
 
-1. **Missing the three font-CSS imports at app entry** — the most common Forest setup mistake. Aeonik silently falls back to system sans-serif and the UI looks "off" without any console error. See Setup → Step 2 for the imports and a DevTools verification checklist.
-2. **Writing the AlkemyBETA family with a space** (`"Alkemy Beta"`) — the `@font-face` declares `"AlkemyBETA"` (one word). The spaced form fails to resolve.
-3. **Importing from `@mui/material`** instead of `@matteoaliano/forest-ui` — all components, hooks, and layout primitives are available from forest-ui
-4. **Hardcoded color values** (`backgroundColor: "#7f56d9"`) instead of theme tokens (`backgroundColor: "primary.main"`)
-5. **Hardcoded spacing** (`padding: "16px"`) instead of theme spacing (`p: 4`)
-6. **Missing `<ForestProvider>`** at the app root — theme won't apply
-7. **Using filled MUI icons** (`Close`) instead of Outlined (`CloseOutlined`)
-8. **Building custom multi-select** instead of using the `<MultiSelect>` component
-9. **`onClick` on a bare `<Card>`** — a clickable card must wrap its content in `<CardActionArea>` so it gets the 3D bevel/glaze/press affordance. `<Card onClick>` looks identical to a static card and gives no click cue.
-10. **Theme-only components rendering like stock MUI grey** — `Switch`, `Checkbox`, `Radio`, `ToggleButton` (and other pure re-exports) carry NO styling of their own; 100% of their Forest look comes from the theme applied by `<ForestProvider>`. If one looks unstyled/plain-grey while the rest of the app looks right: (a) confirm you imported it from `@matteoaliano/forest-ui`, **not** `@mui/material` (a stray `import Switch from "@mui/material/Switch"` is the usual culprit — it renders with zero error), and (b) confirm it's actually inside `<ForestProvider>` (watch portals/modals and any nested non-Forest MUI `ThemeProvider`, which resets the overrides for its subtree).
+**Full prop tables:** `references/components.md` · **Copy-paste patterns** (forms, tables, dialogs, app shell, detail drawer, charts): `references/patterns.md` · **Upgrading:** `references/upgrading.md`.

package/skills/forest-alkemy-plus/references/components.md

@@ -18,6 +18,8 @@ import Button from "@mui/material/Button";
 
 | Component | Import | Key Props |
 |-----------|--------|-----------|
+| `AppShell` | `import { AppShell, type AppShellNavItem } from "@matteoaliano/forest-ui"` | **Mandatory app frame.** `navItems: AppShellNavItem[]` (`{ label, icon, active?, href?, onClick?, component?, endAdornment? }` — `component` is the router escape), `nav` (custom sidebar node, overrides navItems), `product`, `logoVariant: "logomark" \| "full"`, `brand` (custom node), `search: boolean \| ReactNode`, `actions`, `sidebarBehavior: "permanent" \| "hover"`, `defaultSidebarOpen`. Renders the color-mode toggle itself (not removable). Children = a `<Page>` |
+| `Page` | `import { Page, type PageBreadcrumb } from "@matteoaliano/forest-ui"` | **Mandatory page scaffold.** `title` (required, h5), `breadcrumbs: PageBreadcrumb[]` (`{ label, href?, onClick?, component? }`; last crumb = plain text), `actions` (right-aligned header node), `disableGutters`, `maxWidth`, `sx`. Owns `background.paper` + 24px gutters. Widgets/charts/tables inside go in `<Card>`s |
 | `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` |

package/skills/forest-alkemy-plus/references/patterns.md

@@ -1,5 +1,30 @@
 # Forest UI — Code Patterns & Anti-Patterns
 
+## Setup details (Next.js, fonts, dark mode)
+
+**Next.js config** — required so the bundler resolves the CSS subpath exports:
+
+```ts
+// next.config.ts
+const nextConfig = {
+  transpilePackages: ["@matteoaliano/forest-ui"],
+  experimental: {
+    optimizePackageImports: ["@matteoaliano/forest-ui", "@mui/material", "@mui/icons-material"],
+  },
+};
+```
+
+**Font verification** — after `next dev`, DevTools → Network (filter "font") must show `aeonik-*.woff2` loading `200 OK`, and a `<Typography>`'s computed font-family must read `"Aeonik", sans-serif` (Chrome → Rendered Fonts should say "Web font", not Arial/Helvetica). 404s on woff2 = missing `transpilePackages`. The AlkemyBETA family name is **one word** — `"Alkemy Beta"` will not resolve.
+
+**Dark mode wiring:**
+
+- Initial scheme: `<ForestProvider preset="forest-alkemy+" defaultMode="light" | "dark" | "system">`.
+- Programmatic: `const { mode, setMode } = useColorScheme()` (re-exported). MUI owns a `.dark` class on `<html>` — never toggle classes yourself, or portaled Modal/Menu/Tooltip content stays light.
+- Next.js App Router: render `<InitColorSchemeScript attribute="class" />` (re-exported) as the first child of `<body>` to avoid a flash of the wrong scheme.
+- The visible switch is built into `<AppShell>` — never mount a second toggle.
+
+**If a theme-only component renders like stock grey MUI** (Switch, Checkbox, Radio, ToggleButton): it was imported from `@mui/material` instead of `@matteoaliano/forest-ui`, or it's rendering outside `<ForestProvider>` (watch portals and nested non-Forest `ThemeProvider`s).
+
 ## Code Patterns
 
 ### Form Layout
@@ -134,142 +159,61 @@ function ConfirmDialog({ open, onClose, onConfirm }) {
 }
 ```
 
-### App Shell (AppBar + Sidebar Navigation) — MANDATORY layout
+### App Shell + Page (MANDATORY layout)
 
-**This is the required top-level layout for every authenticated Forest UI product surface.** Do not hand-roll a bespoke app chrome per project — start from this shell so brand, spacing, sidebar behavior, and the dark-mode toggle are consistent across all Forest apps. A full-width AppBar sits 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.
+**Every authenticated surface renders inside `<AppShell>`, and every routed page inside `<Page>`.** Both are real components — do not hand-roll app chrome or page scaffolds.
 
-Two requirements are non-negotiable:
-
-1. **The AppBar actions MUST include the color-mode toggle** (`ColorModeToggle` below, backed by `useColorScheme`). This is the single sanctioned dark-mode switch — do not scatter ad-hoc toggles elsewhere.
-2. **The brand is always the logomark**, and it flips to `color="negative"` when dark mode is active so it stays legible on the dark AppBar.
+- `<AppShell>` owns the sticky AppBar (brand / centered search / actions), the SidebarNav, responsive mobile drawer, and the **color-mode toggle (built in — never add your own)**. The brand auto-flips to negative artwork in dark mode.
+- `<Page>` owns the flat `background.paper` surface, the 24px gutters, breadcrumbs, the page title, and header actions.
+- **Every widget, chart, or table inside a `<Page>` must live in a `<Card>`.**
 
 ```tsx
-import { useState } from "react";
 import {
-  AppBar, Toolbar, Logo, Search, IconButton, Badge, Tooltip,
-  SidebarNav, SidebarItem, List, Typography, Box, Avatar,
-  useColorScheme,
+  AppShell, Page, Card, CardContent, IconButton, Badge, Avatar,
+  type AppShellNavItem,
 } from "@matteoaliano/forest-ui";
-import NotificationsOutlined from "@mui/icons-material/NotificationsOutlined";
-import SettingsOutlined from "@mui/icons-material/SettingsOutlined";
-import DarkModeOutlined from "@mui/icons-material/DarkModeOutlined";
-import LightModeOutlined from "@mui/icons-material/LightModeOutlined";
 import HomeOutlined from "@mui/icons-material/HomeOutlined";
 import BarChartOutlined from "@mui/icons-material/BarChartOutlined";
-import PeopleOutlined from "@mui/icons-material/PeopleOutlined";
-
-// Brand: always the logomark, negative artwork in dark mode.
-function AppShellLogo() {
-  const { mode, systemMode } = useColorScheme();
-  const resolved = mode === "system" ? systemMode : mode;
-  return (
-    <Logo
-      product="studio"
-      variant="logomark"
-      color={resolved === "dark" ? "negative" : "default"}
-    />
-  );
-}
-
-// Mandatory light/dark switch. `useColorScheme` toggles the `.dark` class on
-// <html> for you — the preset's dark tokens invert the whole palette.
-function ColorModeToggle() {
-  const { mode, systemMode, setMode } = useColorScheme();
-  const resolved = mode === "system" ? systemMode : mode;
-  const isDark = resolved === "dark";
-  return (
-    <Tooltip title={isDark ? "Switch to light mode" : "Switch to dark mode"}>
-      <IconButton
-        size="small"
-        color="inherit"
-        aria-label="Toggle color mode"
-        onClick={() => setMode(isDark ? "light" : "dark")}
-      >
-        {isDark ? <LightModeOutlined fontSize="small" /> : <DarkModeOutlined fontSize="small" />}
-      </IconButton>
-    </Tooltip>
-  );
-}
+import NotificationsOutlined from "@mui/icons-material/NotificationsOutlined";
 
-function AppShell({ children }) {
-  const [sidebarOpen, setSidebarOpen] = useState(true);
+const navItems: AppShellNavItem[] = [
+  // component/href/onClick are the router escape — plug in Next Link, React
+  // Router Link, or a plain onClick. `active` drives the selected state.
+  { label: "Home", icon: <HomeOutlined />, href: "/", active: true },
+  { label: "Analytics", icon: <BarChartOutlined />, href: "/analytics" },
+];
 
+export function Layout() {
   return (
-    <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 (centered over the 48px sidebar rail) */}
-          <Box sx={{ flex: 1, display: "flex", alignItems: "center" }}>
-            <Box sx={{ width: 48, ml: "-16px", display: "flex", justifyContent: "center" }}>
-              <AppShellLogo />
-            </Box>
-          </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 (ColorModeToggle is mandatory) */}
-          <Box sx={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "flex-end", gap: 1 }}>
-            <ColorModeToggle />
-            <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>
+    <AppShell
+      navItems={navItems}
+      search              // true = default centered Search; or pass a node
+      actions={
+        <>
+          <IconButton size="small" color="inherit">
+            <Badge badgeContent={3} color="error" variant="dot">
+              <NotificationsOutlined fontSize="small" />
+            </Badge>
+          </IconButton>
+          <Avatar sx={{ width: 28, height: 28, fontSize: 13 }}>MA</Avatar>
+        </>
+      }
+    >
+      <Page title="Home" breadcrumbs={[{ label: "Home" }]}>
+        <Card>
+          <CardContent>{/* every widget/chart/table goes in a Card */}</CardContent>
+        </Card>
+      </Page>
+    </AppShell>
   );
 }
 ```
 
-**Key patterns:**
-- `ColorModeToggle` in AppBar actions — mandatory, single sanctioned dark-mode switch
-- Logomark flips to `color="negative"` in dark mode — brand stays legible on the dark AppBar
-- `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
-
-See the **Patterns/App Shell** Storybook entry for the canonical, runnable version (Default / CollapsedSidebar / HoverSidebar / StudioBrand).
+**Key props:**
+- `AppShell`: `navItems` (data + `component`/`href`/`onClick` router escape, `endAdornment` for count chips), `nav` (full custom sidebar), `logoVariant` (`"logomark"` default | `"full"`), `brand` (custom node), `search` (bool/node), `actions`, `sidebarBehavior` (`"permanent"` | `"hover"`), `defaultSidebarOpen`.
+- `Page`: `title` (required), `breadcrumbs` (data + `component` router escape; last crumb renders as plain text), `actions`, `disableGutters`, `maxWidth`.
+
+The color-mode toggle is rendered by `<AppShell>` itself and is not removable — never mount a second theme switch. See the **Patterns/App Shell** and **Patterns/Page** Storybook entries for live variants.
 
 ### Detail Drawer
 

package/skills/forest-alkemy-plus/references/upgrading.md

@@ -6,10 +6,9 @@ How to keep `@matteoaliano/forest-ui` and its peer dependencies up to date.
 
 ```bash
 npm update @matteoaliano/forest-ui   # bump within the semver range
-npx @matteoaliano/forest-ui          # re-sync the Claude Code skill
 ```
 
-That's it for routine minor/patch updates. For majors, read the changelog first.
+That's it for routine minor/patch updates. The Claude Code skill + enforcement hook update through the Forest Design System plugin — no re-sync step. For majors, read the changelog first.
 
 ## Check the installed version
 
@@ -53,27 +52,11 @@ npm install @matteoaliano/forest-ui@latest
 
 Commit your lockfile before upgrading so a rollback is one `git checkout` away.
 
-## Re-sync the Claude Code skill
+## Keep the Claude Code plugin current
 
-The skill ships **inside** the package and evolves with it. After every upgrade:
+AI guidance ships as the Forest Design System **plugin** (skill + enforcement hook), not as files copied into your repo. Update it through Claude Code's plugin system — there's no per-upgrade re-sync step, and nothing to commit into `.claude/`.
 
-```bash
-npx @matteoaliano/forest-ui
-```
-
-This refreshes `.claude/skills/forest-alkemy-plus/` with the latest component list, prop signatures, and patterns. **Skipping this step means Claude is working from stale rules** — it may recommend components that no longer exist or miss new ones.
-
-Automate it by wiring `postinstall`:
-
-```json
-{
-  "scripts": {
-    "postinstall": "forest-ui"
-  }
-}
-```
-
-Commit `.claude/skills/` so every teammate (and CI) gets the same snapshot.
+If you still have a `.claude/skills/forest-alkemy-plus/` folder from the old `npx forest-ui sync` flow, delete it — the plugin replaces it, and a stale copy competes with it.
 
 ## Peer dependencies
 
@@ -102,8 +85,7 @@ Quick checklist after bumping:
 - [ ] No runtime console errors about missing theme tokens
 - [ ] `<ForestProvider>` still wraps the app root
 - [ ] Fonts still render (Aeonik / Aeonik Mono / Alkemy BETA)
-- [ ] Visual spot-check on one page per preset in use
-- [ ] `.claude/skills/forest-alkemy-plus/SKILL.md` `version` frontmatter matches the new package version
+- [ ] Visual spot-check on a representative page
 
 ## Rollback
 
@@ -112,7 +94,6 @@ If something breaks and you need to revert:
 ```bash
 git checkout -- package.json package-lock.json
 npm install
-npx @matteoaliano/forest-ui   # re-sync to restore older skill
 ```
 
 Or pin to a known-good version explicitly:
@@ -130,7 +111,7 @@ npm install @matteoaliano/forest-ui@0.5.2
 
 ## Never do this on upgrade
 
-- Don't skip `npx @matteoaliano/forest-ui` — stale skills are worse than no skills
+- Don't keep a stale `.claude/skills/forest-alkemy-plus/` copy alongside the plugin — it competes with the current rules
 - Don't upgrade MUI separately from forest-ui — they're paired
 - Don't mix two forest-ui majors in a monorepo without a shared hoist
 - Don't suppress peer-dep warnings — they're the early signal for theme breakage