Document canonical Next 16 + React 19 + ui-kit 0.9 frontend stack

commands/new-tool.md

@@ -1,10 +1,10 @@
 ---
-description: Scaffold a new PolicyEngine interactive tool (Next.js 14 + Tailwind 4 + ui-kit theme + embedding boilerplate)
+description: Scaffold a new PolicyEngine interactive tool (Next.js 16 + React 19 + Tailwind 4 + ui-kit 0.9 + embedding boilerplate)
 ---
 
 # New interactive tool scaffold
 
-Creates a complete project for a standalone PolicyEngine interactive tool that embeds in policyengine.org.
+Creates a complete project for a standalone PolicyEngine interactive tool that embeds in policyengine.org using the canonical frontend stack.
 
 ## Step 1: Gather requirements
 
@@ -20,21 +20,39 @@ Ask the user for:
 ## Step 2: Create the project
 
 ```bash
-# Create Next.js 14 + Tailwind project
-bunx create-next-app@14 TOOL_NAME --js --app --tailwind --eslint --no-src-dir --import-alias "@/*"
+# Create Next.js 16 + Tailwind project with canonical stack
+bunx create-next-app@latest TOOL_NAME --js --app --tailwind --eslint --no-src-dir --import-alias "@/*"
 cd TOOL_NAME
 
-# Install dependencies
-bun add @policyengine/ui-kit recharts
-bun add -D vitest
+# Install canonical dependencies
+bun add @policyengine/ui-kit@^0.9.0 recharts
+bun add -D vitest @tailwindcss/postcss@^4.2.4 postcss
 ```
 
+This creates a project with:
+- Next.js 16+ with App Router
+- React 19+
+- Tailwind CSS 4+
+- ESLint 9 flat config
+- ui-kit 0.9+
+
 Copy the favicon:
 ```bash
 mkdir -p public
 cp node_modules/@policyengine/ui-kit/src/assets/logos/policyengine/teal-square.svg public/favicon.svg
 ```
 
+Create PostCSS config for Tailwind v4:
+```bash
+cat > postcss.config.mjs << 'EOF'
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+EOF
+```
+
 If using code highlighting:
 ```bash
 bun add prism-react-renderer

skills/documentation/policyengine-standards-skill/SKILL.md

@@ -173,6 +173,31 @@ ruff format --check .
 
 ## JavaScript/React Standards
 
+### Canonical Frontend Stack (2026)
+
+All PolicyEngine frontend repositories should use the following versions as of the Phase 2F modernization:
+
+| Package | Version | Notes |
+|---------|---------|-------|
+| **Next.js** | `^16.2.6` | App Router required |
+| **React** | `^19.2.0` | With React DOM 19 |
+| **@policyengine/ui-kit** | `^0.9.0` | Design system |
+| **Tailwind CSS** | `^4.2.4` | CSS-first config (no .js config) |
+| **ESLint** | `^9` | Flat config (eslint.config.mjs) |
+
+**Stack features:**
+- Next.js 16 with App Router (not Pages Router)
+- React 19 with concurrent features
+- Tailwind v4 CSS-first configuration (no `tailwind.config.js`)
+- ESLint 9 flat config (`eslint.config.mjs` replaces `.eslintrc.json`)
+- ui-kit 0.9+ with full dark mode and accessibility improvements
+
+**When reviewing dependency upgrades:**
+- Verify all dependencies are at or above canonical versions
+- Check that legacy configs (`.eslintrc.json`, `tailwind.config.js`) are removed
+- Ensure `postcss.config.mjs` uses `@tailwindcss/postcss`
+- Confirm `globals.css` imports Tailwind v4 correctly
+
 ### Formatting
 - **Formatters**: Prettier + ESLint
 - **Command**: `bun run lint -- --fix && bunx prettier --write .`

skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md

@@ -184,9 +184,9 @@ The ui-kit ships `@source` directives to tell Tailwind to scan its components. I
 
 ## Framework-Specific Notes
 
-### Next.js 14 (App Router)
+### Next.js 16+ (Canonical Stack)
 
-Standard setup. Requires `@tailwindcss/postcss` in PostCSS config.
+The canonical PolicyEngine frontend stack uses Next.js 16+ with App Router. Requires `@tailwindcss/postcss` in PostCSS config.
 
 ```
 app/
@@ -195,9 +195,11 @@ app/
 postcss.config.mjs
 ```
 
-### Next.js 15+ / Next.js 16
+All PolicyEngine frontend repos should target Next.js ^16.2.6 as of the Phase 2F modernization.
 
-Same setup. Turbopack processes PostCSS normally. No changes needed.
+### Next.js 14/15 (Legacy)
+
+Same setup. Turbopack processes PostCSS normally. No changes needed. Consider upgrading to Next.js 16+.
 
 ### Vite (non-Next.js)