From 7b060d8f90f03242fdee87c34757e5db0adcb199 Mon Sep 17 00:00:00 2001 From: policyengine-bot Date: Sat, 9 May 2026 18:07:46 +0000 Subject: [PATCH] Document canonical Next 16 + React 19 + ui-kit 0.9 frontend stack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add version specifications for the canonical PolicyEngine frontend stack to help future Claude Code sessions working on frontend upgrades and new tool scaffolding. Changes: - Add canonical stack version table to policyengine-standards-skill (Next ^16.2.6, React ^19.2.0, ui-kit ^0.9.0, Tailwind ^4.2.4, ESLint ^9) - Update /new-tool command to use Next 16+ and specify canonical versions - Add PostCSS config step to new-tool scaffolding - Update ui-kit-consumer-skill to highlight Next 16+ as canonical Based on learnings from reviewing deduction-repeal-analysis PR #4. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- commands/new-tool.md | 32 +++++++++++++++---- .../policyengine-standards-skill/SKILL.md | 25 +++++++++++++++ .../SKILL.md | 10 +++--- 3 files changed, 56 insertions(+), 11 deletions(-) diff --git a/commands/new-tool.md b/commands/new-tool.md index 9e983c8..af4deae 100644 --- a/commands/new-tool.md +++ b/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 diff --git a/skills/documentation/policyengine-standards-skill/SKILL.md b/skills/documentation/policyengine-standards-skill/SKILL.md index 2eecb67..143f2a7 100644 --- a/skills/documentation/policyengine-standards-skill/SKILL.md +++ b/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 .` diff --git a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md b/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md index eb65902..318f119 100644 --- a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md +++ b/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)