@matteoaliano/forest-ui 0.8.4 → 0.8.5

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

@@ -1,141 +1,141 @@
----
-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: 0.8.4
----
-
-# Forest UI — Alkemy+ Preset
-
-## Golden Rules
-
-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.
-
-## 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:
-
-```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
-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:
-
-```ts
-// next.config.ts
-const nextConfig = {
-  transpilePackages: ["@matteoaliano/forest-ui"],
-  experimental: {
-    optimizePackageImports: [
-      "@matteoaliano/forest-ui",
-      "@mui/material",
-      "@mui/icons-material",
-    ],
-  },
-};
-export default nextConfig;
-```
-
-**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`.
-
-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
-
-```tsx
-import { ForestProvider } from "@matteoaliano/forest-ui";
-
-function App() {
-  return (
-    <ForestProvider preset="forest-alkemy+">
-      {/* All app content here */}
-    </ForestProvider>
-  );
-}
-```
-
-## 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.
-
-## Tooltip vs Popover
-
-- **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.
-
-**Rule of thumb:** If the overlay content is just a string, use `<Tooltip>`. If it contains components, use `<Popover>`.
-
-## Common Anti-Patterns
-
-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
+---
+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: 0.8.4
+---
+
+# Forest UI — Alkemy+ Preset
+
+## Golden Rules
+
+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.
+
+## 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:
+
+```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
+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:
+
+```ts
+// next.config.ts
+const nextConfig = {
+  transpilePackages: ["@matteoaliano/forest-ui"],
+  experimental: {
+    optimizePackageImports: [
+      "@matteoaliano/forest-ui",
+      "@mui/material",
+      "@mui/icons-material",
+    ],
+  },
+};
+export default nextConfig;
+```
+
+**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`.
+
+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
+
+```tsx
+import { ForestProvider } from "@matteoaliano/forest-ui";
+
+function App() {
+  return (
+    <ForestProvider preset="forest-alkemy+">
+      {/* All app content here */}
+    </ForestProvider>
+  );
+}
+```
+
+## 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.
+
+## Tooltip vs Popover
+
+- **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.
+
+**Rule of thumb:** If the overlay content is just a string, use `<Tooltip>`. If it contains components, use `<Popover>`.
+
+## Common Anti-Patterns
+
+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