@matteoaliano/forest-ui 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matteoaliano/forest-ui",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Forest Design System — themed MUI components",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

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

@@ -3,7 +3,7 @@ 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.2
+  version: 0.8.4
 ---
 
 # Forest UI — Alkemy+ Preset
@@ -11,14 +11,17 @@ metadata:
 ## 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 wrap your app root with `<ForestProvider>`** — it applies the theme and CSS baseline.
-3. **NEVER use inline colors or spacing values.** Use design tokens or MUI's `sx` prop with theme values (`p: 4`, `backgroundColor: "primary.main"`).
-4. **NEVER create custom component wrappers** for things Forest UI already provides.
-5. **TypeScript is required.** All components export their prop types (e.g. `type ButtonProps`).
-6. **ALWAYS use the Outlined variant of MUI icons.** Import from `@mui/icons-material/*Outlined` (e.g. `CloseOutlined`, `MailOutlined`). Never use filled, Rounded, Sharp, or TwoTone variants.
+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 \
@@ -28,6 +31,48 @@ npm install @matteoaliano/forest-ui \
 
 > **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";
 
@@ -42,17 +87,14 @@ function App() {
 
 ## Typography & Fonts
 
-- **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** — use for page titles (h1/hero headings). Not for general UI text
-
-Import the font CSS files you need in your app entry point:
+- **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>
+  ```
 
-```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";
-```
+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
 
@@ -89,9 +131,11 @@ See `references/components.md` for full API details, `references/patterns.md` fo
 
 ## Common Anti-Patterns
 
-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
-5. **Using filled MUI icons** (`Close`) instead of Outlined (`CloseOutlined`)
-6. **Building custom multi-select** instead of using the `<MultiSelect>` component
+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