+
+ Calculating...
+
+)}
+```
+
+**Error state:**
+```tsx
+{mutation.isError && (
+
+
+)}
+```
+
+**Empty/initial state:**
+```tsx
+{!mutation.data && !mutation.isPending && (
+ Something went wrong. Please try again.
+ +
+
+)}
+```
+
+### Step 6: Variation Calculations (if applicable)
+
+If the plan includes charts that vary a parameter (e.g., "tax by income"), implement the variation logic:
+
+```typescript
+export function useIncomeVariation(baseValues: FormValues, countryId: string) {
+ return useQuery({
+ queryKey: ['income-variation', baseValues],
+ queryFn: async () => {
+ const incomePoints = generateRange(0, 500000, 25); // 20 points
+ const results = await Promise.all(
+ incomePoints.map(income =>
+ simulateHousehold(
+ buildHouseholdRequest({ ...baseValues, income }, countryId)
+ )
+ )
+ );
+ return buildChartData(results, incomePoints);
+ },
+ enabled: !!baseValues.state, // Only run when required inputs are set
+ });
+}
+```
+
+### Step 7: Smoke Check
+
+```bash
+bun run dev # Start dev server — verify no runtime crashes
+```
+
+## Quality Checklist
+
+- [ ] Every API call has loading, error, and empty state handling
+- [ ] Request builder correctly maps form state to API request
+- [ ] Response transformer correctly extracts data for each component
+- [ ] No type mismatches between API client and component props
+- [ ] Cache keys prevent unnecessary re-fetches
+- [ ] Variation queries (if any) batch efficiently
+
+Do NOT run build or tests — that is the validator's job in Phase 5.
diff --git a/agents/dashboard/dashboard-overview-updater.md b/agents/dashboard/dashboard-overview-updater.md
new file mode 100644
index 0000000..20145b8
--- /dev/null
+++ b/agents/dashboard/dashboard-overview-updater.md
@@ -0,0 +1,74 @@
+---
+name: dashboard-overview-updater
+description: Checks if dashboard ecosystem components changed during a create-dashboard run and updates the dashboard-overview command accordingly
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+## Thinking Mode
+
+**IMPORTANT**: Use careful, step-by-step reasoning before taking any action. Think through:
+1. What the current overview command lists
+2. What the marketplace.json currently registers
+3. Whether there are any differences
+4. What specific updates are needed
+
+# Dashboard Overview Updater Agent
+
+Runs at the end of the `/create-dashboard` workflow. Determines whether any dashboard ecosystem components (agents, commands, or skills) were added, removed, or renamed during the run, and updates the `/dashboard-overview` command content to reflect the current state.
+
+## Input
+
+- The dashboard builder ecosystem after a `/create-dashboard` run has completed
+
+## Output
+
+- Either "Overview is up to date" (no changes needed) or an updated `commands/dashboard-overview.md`
+
+## Workflow
+
+### Step 1: Read Current Ecosystem from Marketplace
+
+Read `.claude-plugin/marketplace.json` and extract the `dashboard-builder` plugin entry. Collect:
+- All agents listed in the `agents` array
+- All commands listed in the `commands` array
+- All skills listed in the `skills` array
+
+Also check the `complete` plugin entry for any dashboard-related items that might only appear there.
+
+### Step 2: Read Current Overview
+
+Read `commands/dashboard-overview.md` and extract:
+- All agents listed in the Agents table
+- All commands listed in the Commands table
+- All skills listed in the Skills table
+
+### Step 3: Compare
+
+Diff the marketplace.json entries against what the overview command lists. Identify:
+- New agents not listed in the overview
+- New commands not listed in the overview
+- New skills not listed in the overview
+- Items in the overview that no longer exist in the marketplace
+- Items whose descriptions may have changed
+
+### Step 4: Update if Needed
+
+**If changes detected:**
+1. Read the frontmatter/description of each new agent, command, or skill file to get its description
+2. Update the appropriate table(s) in `commands/dashboard-overview.md`:
+ - Add new items in the correct position
+ - Remove items no longer in the marketplace
+ - Update descriptions if they changed
+3. Preserve the existing formatting and table structure
+
+**If no changes detected:**
+Report "Overview is up to date" and exit without modifying any files.
+
+## DO NOT
+
+- Create the overview from scratch — only update the existing content
+- Modify any files other than `commands/dashboard-overview.md`
+- Change the overall structure or layout of the overview
+- Run the `/dashboard-overview` command itself
+- Add items that are not registered in marketplace.json
diff --git a/agents/dashboard/dashboard-plan-validator.md b/agents/dashboard/dashboard-plan-validator.md
new file mode 100644
index 0000000..f954d89
--- /dev/null
+++ b/agents/dashboard/dashboard-plan-validator.md
@@ -0,0 +1,115 @@
+---
+name: dashboard-plan-validator
+description: Validates that the implementation matches plan.yaml — API contract, component completeness, embedding, and state handling
+tools: Read, Grep, Glob
+model: opus
+---
+
+# Dashboard Plan Validator
+
+Checks that the dashboard implementation matches everything specified in `plan.yaml`.
+
+## Skills Used
+
+- **policyengine-interactive-tools-skill** — Embedding compliance
+- **policyengine-recharts-skill** — Chart implementation quality
+
+## First: Load Required Skills
+
+1. `Skill: policyengine-interactive-tools-skill`
+2. `Skill: policyengine-recharts-skill`
+
+## Workflow
+
+### Step 1: Read the Plan
+
+Read `plan.yaml` and extract:
+- All components (inputs, charts, metrics, tables)
+- API endpoints or data sources
+- Embedding configuration
+- Test specifications
+
+### Step 2: Run Checks
+
+#### 1. API Contract Compliance
+
+For each endpoint/data source in the plan:
+- Verify a corresponding client function exists in `lib/api/`
+- Verify TypeScript types in `lib/api/types.ts` match what components expect
+- Verify every variable in the plan has a path from data source to component prop
+
+#### 2. Component Completeness
+
+For each component in `plan.yaml`:
+- Does the file exist?
+- Does it render the correct type (chart, input, metric)?
+- Does it accept the correct data shape?
+- Does it have a test?
+
+#### 3. Embedding Compliance
+
+```
+# Country detection from hash
+grep -rn 'getCountryFromHash|country.*hash' app/ lib/ components/ --include='*.ts' --include='*.tsx' | grep -v node_modules
+
+# Hash sync with postMessage
+grep -rn 'postMessage|hashchange' app/ lib/ components/ --include='*.ts' --include='*.tsx' | grep -v node_modules
+
+# Share URLs pointing to policyengine.org
+grep -rn 'policyengine.org' app/ lib/ components/ --include='*.ts' --include='*.tsx' | grep -v node_modules
+```
+
+All three embedding features must be present.
+
+#### 4. Loading and Error States
+
+```
+# Loading state handling
+grep -rn 'isPending|isLoading|loading' app/ components/ --include='*.tsx' | grep -v node_modules | grep -v '.test.'
+
+# Error state handling
+grep -rn 'isError|error' app/ components/ --include='*.tsx' | grep -v node_modules | grep -v '.test.'
+```
+
+Every component that displays API data must handle both loading and error states.
+
+#### 5. Chart Quality
+
+For each chart component:
+- Uses `ResponsiveContainer` wrapper
+- Uses CSS variables for colors (`var(--chart-N)`), not hardcoded hex
+- Axes use appropriate formatting
+
+## Report Format
+
+```
+## Plan Compliance Report
+
+### Summary
+- PASS: X/5 checks
+- FAIL: Y/5 checks
+
+### Results
+
+| # | Check | Status | Details |
+|---|-------|--------|---------|
+| 1 | API contract | PASS/FAIL | X/Y endpoints connected |
+| 2 | Component completeness | PASS/FAIL | X/Y components implemented |
+| 3 | Embedding | PASS/FAIL | ... |
+| 4 | Loading/error states | PASS/FAIL | ... |
+| 5 | Chart quality | PASS/FAIL | ... |
+
+### Failures (if any)
+
+#### Check N: [name]
+- **Plan requires**: [what the plan says]
+- **Found**: [what the implementation has]
+- **Missing**: [specific gap]
+```
+
+## DO NOT
+
+- Fix any issues — report only
+- Modify any files
+- Modify plan.yaml
+- Skip reading plan.yaml — every check is relative to the plan
diff --git a/agents/dashboard/dashboard-planner.md b/agents/dashboard/dashboard-planner.md
new file mode 100644
index 0000000..f6a610b
--- /dev/null
+++ b/agents/dashboard/dashboard-planner.md
@@ -0,0 +1,346 @@
+---
+name: dashboard-planner
+description: Analyzes natural-language dashboard descriptions and produces structured implementation plans
+tools: Read, Write, Grep, Glob, WebSearch, WebFetch, Bash, Skill
+model: opus
+---
+
+## Thinking Mode
+
+**IMPORTANT**: Use careful, step-by-step reasoning before taking any action. Think through:
+1. What the dashboard needs to do
+2. Which PolicyEngine variables and API endpoints are relevant
+3. What components and charts are needed
+4. Which data pattern is appropriate and why
+
+Take time to analyze thoroughly before producing the plan.
+
+# Dashboard Planner Agent
+
+Produces a structured YAML implementation plan from a natural-language dashboard description.
+
+## Skills Used
+
+- **policyengine-interactive-tools-skill** - Architecture patterns, data patterns, embedding
+- **policyengine-design-skill** - Design tokens, visual identity, color palette
+- **policyengine-us-skill** - US tax/benefit variables and programs
+- **policyengine-uk-skill** - UK tax/benefit variables and programs
+- **policyengine-api-v2-skill** - API v2 endpoint catalog and design hierarchy
+
+## First: Load Required Skills
+
+**Before starting ANY work, use the Skill tool to load each required skill:**
+
+1. `Skill: policyengine-interactive-tools-skill`
+2. `Skill: policyengine-design-skill`
+3. `Skill: policyengine-us-skill` (if US dashboard)
+4. `Skill: policyengine-uk-skill` (if UK dashboard)
+5. `Skill: policyengine-api-v2-skill`
+
+## Input
+
+You receive a natural-language description of the desired dashboard (typically 2-3 paragraphs). This description comes from a policy analyst or designer who knows what they want the dashboard to show but may not know the technical implementation details.
+
+## Output
+
+A complete `plan.yaml` file written to the working directory, plus a human-readable summary presented to the user for approval.
+
+## Workflow
+
+### Step 1: Analyze the Description
+
+Extract from the natural-language input:
+- **Purpose**: What policy question does this dashboard answer?
+- **Audience**: Who will use it? (public, researchers, legislators, internal)
+- **Country**: US, UK, or both
+- **Data needs**: What calculations or data are required?
+- **Interactions**: What can users change or explore?
+- **Outputs**: What visualizations, metrics, or tables should be shown?
+
+### Step 2: Research Existing Dashboards
+
+Search the PolicyEngine GitHub organization for similar existing tools:
+
+```bash
+gh api 'orgs/PolicyEngine/repos?per_page=100&sort=updated' --jq '.[].name'
+```
+
+For any that look related, check their structure to learn from existing patterns. This helps identify:
+- Reusable patterns from similar tools
+- PolicyEngine variables already available
+- API endpoints that match the needs
+
+### Step 3: Map to PolicyEngine Variables
+
+Based on the description, identify:
+- Which PolicyEngine variables are needed (e.g., `income_tax`, `household_net_income`, `snap`)
+- Which entity levels are involved (person, household, tax_unit, spm_unit)
+- Whether household-level or economy-wide simulation is needed
+- What reform parameters might be varied
+
+### Step 4: Determine Data Pattern
+
+Choose from the data patterns defined in the `policyengine-interactive-tools-skill` (loaded in the First step). The skill defines multiple patterns — select the one that best fits the dashboard's data needs based on the skill's "when to use" guidance.
+
+**Decision hierarchy (most preferred first):**
+
+1. `precomputed` / `precomputed-csv` — if parameter space is finite
+2. `policyengine-api` — if household-level calculations suffice (always prefer this for standard household tools)
+3. `custom-modal` — ONLY if microsimulation or custom reforms are needed
+
+Write the chosen pattern into `data_pattern` in plan.yaml using these identifiers:
+
+| Skill pattern | `data_pattern` value |
+|---------------|----------------------|
+| Pattern A: Precomputed JSON | `precomputed` |
+| Pattern B: PolicyEngine API | `policyengine-api` |
+| Pattern C: Custom API on Modal (gateway + polling) | `custom-modal` |
+| Pattern D: Precomputed CSV | `precomputed-csv` |
+
+If the chosen pattern is `custom-modal`, the plan **must document why** the simpler patterns are insufficient. The plan must also specify which endpoints need long-running computation (microsimulation) vs. fast computation (household), as this determines worker timeout and memory allocation.
+
+### Step 5: Design Components
+
+For each visualization or interaction:
+- Specify chart type and which app-v2 pattern to follow
+- Map data fields to chart axes
+- Use design token color references (e.g., `primary-500`, not `#319795`)
+- Specify responsive behavior
+
+**Chart patterns must reference app-v2 components:**
+- Line/bar/area charts: Follow `ChartContainer` patterns from policyengine-app-v2
+- Choropleth maps: Follow map patterns from policyengine-app-v2
+- Metric cards: Follow existing card patterns from policyengine-app-v2
+
+### Step 6: Define Test Criteria
+
+For each component and endpoint, define what "working correctly" means:
+- API response shape and value ranges
+- Component render checks
+- Known-input/known-output benchmark cases
+- Design compliance checks
+
+### Step 7: Write the Plan
+
+Write `plan.yaml` to the working directory with this structure:
+
+```yaml
+# Dashboard Implementation Plan
+# Generated by dashboard-planner agent
+
+dashboard:
+ name: "Enter your details and click Calculate to see results.
+
+ {children}
+
+ ),
+);
+ComponentName.displayName = 'ComponentName';
+```
+
+**Rules:**
+- ALL colors, spacing, font sizes, and radii must reference design tokens — no hardcoded hex values, no arbitrary pixel values
+- Use semantic classes (`bg-primary`, `text-foreground`) or brand palette classes (`bg-teal-500`, `text-gray-600`)
+- Export the component and its props interface from the category barrel (`src/ComponentName
+
+ {/* Render every variant, size, and state */}
+ Example
+ Large primary
+ {/* ... all combinations */}
+
+-
+ - Props:
-
+
+## Testing
+- Unit tests written with Vitest + React Testing Library
+- Tests cover: rendering, all variants, props, interaction, ref forwarding
+- All tests passing
+
+## Design token compliance
+- All colors reference design tokens (no hardcoded hex)
+- All spacing uses standard Tailwind classes
+- All typography uses token scale
+- Validated by design-token-validator agent
+
+## Test plan
+- [ ] Run `bun run dev:demo` and verify components render correctly
+- [ ] Run `bun run test` and verify all tests pass
+- [ ] Review component API matches existing ui-kit conventions
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Report the PR URL to the user.
+
+## Reference
+
+See these skills and agents for detailed guidance:
+- `policyengine-design-skill` — Design token values and usage
+- `policyengine-app-skill` — app-v2 component patterns to reference
+- `agents/app/design-token-validator.md` — Automated design token compliance
+- `agents/app/component-test-writer.md` — Automated test writing
diff --git a/commands/dashboard-overview.md b/commands/dashboard-overview.md
new file mode 100644
index 0000000..3c22539
--- /dev/null
+++ b/commands/dashboard-overview.md
@@ -0,0 +1,78 @@
+---
+description: Lists all available tools, commands, skills, and agents in the dashboard builder ecosystem
+---
+
+# Dashboard builder ecosystem overview
+
+Display a complete inventory of all tools, commands, skills, and agents available in the PolicyEngine dashboard builder workflow.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/create-dashboard` | Orchestrates multi-agent workflow: creates repo, plans, scaffolds, implements, validates, and commits a dashboard |
+| `/deploy-dashboard` | Deploys a completed dashboard to Vercel (and optionally Modal) and registers it in the app |
+| `/dashboard-overview` | This command — lists all dashboard builder ecosystem components |
+
+## Agents
+
+| Agent | Phase | Description |
+|-------|-------|-------------|
+| `dashboard-planner` | 1 — Plan | Analyzes natural-language descriptions and produces structured plan YAML |
+| `dashboard-scaffold` | 2 — Scaffold | Generates Next.js + Tailwind project structure into the current repo |
+| `backend-builder` | 3A — Implement | Builds API stubs for v2 alpha integration or custom Modal backends |
+| `frontend-builder` | 3B — Implement | Builds React components with Tailwind + PE design tokens |
+| `dashboard-integrator` | 4 — Integrate | Wires frontend components to backend API client, handles data flow |
+| `dashboard-build-validator` | 5 — Validate | Runs build and test suite |
+| `dashboard-design-validator` | 5 — Validate | Checks design tokens, typography, sentence case, responsive |
+| `dashboard-architecture-validator` | 5 — Validate | Checks Tailwind v4, Next.js, ui-kit, package manager |
+| `dashboard-plan-validator` | 5 — Validate | Checks API contract, components, embedding, states vs plan |
+| `dashboard-overview-updater` | Post — Update | Updates this overview if ecosystem components changed |
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `policyengine-frontend-builder-spec-skill` | Mandatory frontend technology requirements (Next.js, Tailwind CSS, design tokens) |
+| `policyengine-dashboard-workflow-skill` | Reference for the create/deploy dashboard workflow |
+| `policyengine-interactive-tools-skill` | Embedding patterns, hash sync, country detection |
+| `policyengine-design-skill` | Design tokens, visual identity, colors, typography, spacing |
+| `policyengine-recharts-skill` | Recharts chart component patterns and styling |
+| `policyengine-app-skill` | app-v2 component architecture reference |
+| `policyengine-api-v2-skill` | API v2 endpoint catalog and async patterns |
+| `policyengine-vercel-deployment-skill` | Vercel deployment configuration |
+| `policyengine-modal-deployment-skill` | Modal deployment for custom dashboard backends |
+| `policyengine-standards-skill` | Code quality and CI/CD standards |
+| `policyengine-writing-skill` | PolicyEngine writing style for blog posts, documentation, and reports |
+| `policyengine-us-skill` | US tax/benefit variables and programs |
+| `policyengine-uk-skill` | UK tax/benefit variables and programs |
+| `policyengine-tailwind-shadcn-skill` | Tailwind CSS v4 + shadcn/ui integration patterns and conventions |
+| `policyengine-ui-kit-consumer-skill` | @policyengine/ui-kit consumer setup, CSS configuration, and troubleshooting |
+
+## Workflow phases
+
+```
+Phase 0: Init repo (creates GitHub repo + clones locally, or uses existing)
+Phase 1: Plan (dashboard-planner) → HUMAN APPROVAL
+Phase 2: Scaffold (dashboard-scaffold) → quality gates (build + test)
+Phase 3: Backend + Frontend (PARALLEL)
+Phase 4: Integrate (dashboard-integrator)
+Phase 5: Validate (4 validators in parallel) ─┐
+ build, design, architecture, plan │ ← max 3 fix cycles
+ Fix → re-validate ───────────────────┘
+Phase 6: Human review → commit and push
+Phase 7: Update overview (dashboard-overview-updater, silent)
+
+Separately: /deploy-dashboard (after merge to main)
+```
+
+## Tech stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js (App Router) + TypeScript |
+| Styling | Tailwind CSS + `@policyengine/ui-kit` tokens |
+| Charts | Recharts (line, bar, area) + Plotly (choropleths) |
+| Data fetching | TanStack React Query |
+| Testing | Vitest + React Testing Library |
+| Deployment | Vercel (frontend) + Modal (backend, if custom) |
diff --git a/commands/deploy-dashboard.md b/commands/deploy-dashboard.md
new file mode 100644
index 0000000..6266444
--- /dev/null
+++ b/commands/deploy-dashboard.md
@@ -0,0 +1,281 @@
+---
+description: Deploys a PolicyEngine dashboard to Vercel (and optionally Modal) and registers it in the app
+---
+
+# Deploying dashboard: $ARGUMENTS
+
+Deploy a completed PolicyEngine dashboard to production. Run this AFTER merging your feature branch into `main`.
+
+**Precondition:** The user should be on the `main` branch with a clean working tree and the dashboard code merged.
+
+## Skills Used
+
+- **policyengine-vercel-deployment-skill** — Frontend deployment (all dashboards)
+- **policyengine-modal-deployment-skill** — Backend deployment (only if `custom-backend` pattern)
+
+## Step 1: Verify Prerequisites
+
+```bash
+# Check we're on main
+git branch --show-current
+
+# Check for clean working tree
+git status
+
+# Verify build passes
+bun install --frozen-lockfile && bun run build && bunx vitest run
+```
+
+**If not on main:** Tell the user to merge their feature branch first:
+> You're currently on branch `{branch}`. Please merge into `main` first:
+> ```bash
+> git checkout main
+> git merge {branch}
+> git push
+> ```
+> Then run `/deploy-dashboard` again.
+
+**If build fails:** Report the error and STOP. Do not deploy broken code.
+
+## Step 2: Read the Plan
+
+```bash
+cat plan.yaml
+```
+
+Extract:
+- `dashboard.name` — for Vercel project and Modal app names
+- `data_pattern` — determines if Modal deploy is needed (`custom-backend` vs `api-v2-alpha`)
+- `tech_stack.framework` — should be `react-nextjs` (env var prefix: `NEXT_PUBLIC_*`)
+- `embedding.register_in_apps_json` — determines if apps.json update is needed
+- `embedding.slug` — the URL slug for policyengine.org
+
+## Step 3: Deploy Backend (if custom-backend)
+
+**Only if `data_pattern: custom-backend`.** If `api-v2-alpha`, skip to Step 4.
+
+See `policyengine-modal-deployment-skill` for the full Modal deployment reference.
+
+### 3a. Authentication check (human gate)
+
+```bash
+modal token info
+modal profile list
+```
+
+Present the output to the user. Verify:
+- Active profile is `policyengine`
+- Workspace is `policyengine`
+
+**If authentication fails or shows wrong workspace:** Stop and display instructions:
+
+> **Modal authentication required.** Your CLI is not configured for the `policyengine` workspace.
+>
+> Please run:
+> ```bash
+> modal token new --profile policyengine
+> modal profile activate policyengine
+> ```
+>
+> If you don't have access, ask a PolicyEngine workspace owner for an invite.
+
+**Do NOT proceed until `modal token info` shows `Workspace: policyengine`.**
+
+**If authentication succeeds**, use `AskUserQuestion` to confirm before proceeding:
+
+```
+question: "Modal is authenticated to the policyengine workspace. Proceed with deployment?"
+header: "Modal auth"
+options:
+ - label: "Proceed"
+ description: "Continue to environment selection and deploy"
+ - label: "Cancel"
+ description: "Stop deployment"
+```
+
+### 3b. Environment selection (human gate)
+
+Use `AskUserQuestion` to select the Modal environment:
+
+```
+question: "Which Modal environment should this deploy to?"
+header: "Environment"
+options:
+ - label: "main (Recommended)"
+ description: "Production — policyengine--app-func.modal.run"
+ - label: "staging"
+ description: "Pre-production testing — policyengine-staging--app-func.modal.run"
+ - label: "testing"
+ description: "Development/CI — policyengine-testing--app-func.modal.run"
+```
+
+### 3c. Deploy
+
+```bash
+# Guard against env var override
+unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET
+
+# Deploy to the selected environment
+modal deploy modal_app.py --env SELECTED_ENV
+```
+
+### 3d. Verify endpoint
+
+Construct the URL from the app name and function name in `modal_app.py`:
+
+- Pattern: `https://policyengine--APP_NAME-FUNCTION_NAME.modal.run`
+- With non-main environment: `https://policyengine-ENV--APP_NAME-FUNCTION_NAME.modal.run`
+
+```bash
+# Health check (if endpoint exists)
+curl -s -w "\n%{http_code}" https://policyengine--DASHBOARD_NAME-health.modal.run
+
+# Test the calculation endpoint
+curl -s -X POST https://policyengine--DASHBOARD_NAME-calculate.modal.run \
+ -H "Content-Type: application/json" \
+ -d '{"test": true}'
+```
+
+**If deploy fails:** Report error and STOP. See the `policyengine-modal-deployment-skill` troubleshooting table.
+
+### 3e. Set API URL in Vercel
+
+After successful Modal deploy, set the API URL as a Vercel environment variable.
+
+```bash
+vercel env add NEXT_PUBLIC_API_URL production
+# Enter: https://policyengine--DASHBOARD_NAME-calculate.modal.run
+```
+
+## Step 4: Deploy Frontend to Vercel
+
+See `policyengine-vercel-deployment-skill` for the full Vercel deployment reference.
+
+```bash
+# Link to Vercel under PolicyEngine team (if not already linked)
+vercel link --scope policy-engine
+
+# Deploy to production
+vercel --prod --yes --scope policy-engine
+```
+
+If a Modal backend was deployed in Step 3, force-rebuild to pick up the new env var:
+```bash
+vercel --prod --force --yes --scope policy-engine
+```
+
+Capture the production URL from the output.
+
+Verify the deployment:
+```bash
+curl -s -o /dev/null -w "%{http_code}" https://VERCEL_PRODUCTION_URL/
+```
+
+**IMPORTANT:** Use the auto-assigned Vercel production URL, not a custom alias. Custom aliases may have deployment protection issues.
+
+## Step 5: Register in apps.json (if applicable)
+
+**Only if `embedding.register_in_apps_json: true`:**
+
+This requires a PR to `PolicyEngine/policyengine-app-v2`.
+
+```bash
+# Clone app-v2 if not already available
+gh repo clone PolicyEngine/policyengine-app-v2 /tmp/policyengine-app-v2
+
+cd /tmp/policyengine-app-v2
+git checkout main
+git checkout -b add-DASHBOARD_NAME-tool
+```
+
+Add entry to `app/src/data/apps/apps.json`:
+
+```json
+{
+ "type": "iframe",
+ "slug": "SLUG",
+ "title": "TITLE",
+ "description": "DESCRIPTION",
+ "source": "VERCEL_PRODUCTION_URL",
+ "tags": ["COUNTRY", "policy", "interactives"],
+ "countryId": "COUNTRY",
+ "displayWithResearch": true,
+ "image": "SLUG-cover.png",
+ "date": "CURRENT_DATE 12:00:00",
+ "authors": ["AUTHOR_SLUG"]
+}
+```
+
+Use `AskUserQuestion` to gather required metadata:
+
+```
+question: "What is the author slug for the apps.json entry? (Check existing entries in apps.json for format, e.g., 'max-ghenis')"
+header: "Author"
+options: [] (free text — let the user type via "Other")
+```
+
+If `displayWithResearch: true`, also ask:
+
+```
+question: "Do you have a cover image for the apps.json listing?"
+header: "Cover image"
+options:
+ - label: "I'll provide one"
+ description: "You'll give me the image file or path"
+ - label: "Skip for now"
+ description: "Use a placeholder — you can add a cover image later"
+```
+
+```bash
+git add app/src/data/apps/apps.json
+git commit -m "Register DASHBOARD_NAME interactive tool"
+git push -u origin add-DASHBOARD_NAME-tool
+
+gh pr create --repo PolicyEngine/policyengine-app-v2 \
+ --title "Register DASHBOARD_NAME tool" \
+ --body "Adds DASHBOARD_NAME to the interactive tools listing.
+
+Source: VERCEL_PRODUCTION_URL
+Slug: /COUNTRY/SLUG"
+```
+
+## Step 6: Smoke Test
+
+After deployment:
+
+1. **Direct URL:** Visit the Vercel production URL, verify the dashboard loads
+2. **Embedded (if registered):** After apps.json PR merges, verify at `policyengine.org/COUNTRY/SLUG`
+3. **Hash sync:** Test that URL parameters work (add `#income=50000` etc.)
+4. **Country detection:** Test with `#country=uk` if the dashboard supports multiple countries
+
+## Step 7: Report
+
+Present deployment summary to the user:
+
+> ## Dashboard deployed
+>
+> - **Live URL:** VERCEL_PRODUCTION_URL
+> - **Vercel project:** DASHBOARD_NAME
+> [If custom backend:]
+> - **API endpoint:** https://policyengine--DASHBOARD_NAME-calculate.modal.run
+> - **Modal environment:** SELECTED_ENV
+> [If registered:]
+> - **apps.json PR:** PR_URL (will be available at policyengine.org/COUNTRY/SLUG after merge)
+>
+> ### Verify
+> - [ ] Dashboard loads at the Vercel URL
+> - [ ] Calculations work (or stubs respond correctly)
+> - [ ] Hash parameters are preserved on refresh
+> [If registered:]
+> - [ ] After apps.json PR merges, dashboard embeds correctly in policyengine.org
+
+## Error Recovery
+
+| Issue | Fix | Reference |
+|-------|-----|-----------|
+| Vercel deploy fails | Check `vercel.json` config, ensure project builds | `policyengine-vercel-deployment-skill` |
+| Modal deploy fails | Check Python deps, Modal auth, function timeouts | `policyengine-modal-deployment-skill` |
+| Wrong Modal workspace | `modal profile activate policyengine` | `policyengine-modal-deployment-skill` |
+| 404 on Vercel URL | Wait 30s for propagation, check Vercel dashboard | `policyengine-vercel-deployment-skill` |
+| API returns errors | Check Modal logs: `modal app logs DASHBOARD_NAME` | `policyengine-modal-deployment-skill` |
+| Hash sync broken | Check postMessage calls in embedding.ts | `policyengine-interactive-tools-skill` |
diff --git a/commands/new-tool.md b/commands/new-tool.md
index fa43230..9e983c8 100644
--- a/commands/new-tool.md
+++ b/commands/new-tool.md
@@ -1,5 +1,5 @@
---
-description: Scaffold a new PolicyEngine interactive tool (Next.js 14 + Tailwind 4 + design system + embedding boilerplate)
+description: Scaffold a new PolicyEngine interactive tool (Next.js 14 + Tailwind 4 + ui-kit theme + embedding boilerplate)
---
# New interactive tool scaffold
@@ -25,10 +25,16 @@ bunx create-next-app@14 TOOL_NAME --js --app --tailwind --eslint --no-src-dir --
cd TOOL_NAME
# Install dependencies
-bun add @policyengine/design-system recharts
+bun add @policyengine/ui-kit recharts
bun add -D vitest
```
+Copy the favicon:
+```bash
+mkdir -p public
+cp node_modules/@policyengine/ui-kit/src/assets/logos/policyengine/teal-square.svg public/favicon.svg
+```
+
If using code highlighting:
```bash
bun add prism-react-renderer
@@ -46,16 +52,13 @@ import "./globals.css";
export const metadata = {
title: "TOOL_TITLE | PolicyEngine",
description: "DESCRIPTION",
+ icons: { icon: "/favicon.svg" },
};
export default function RootLayout({ children }) {
return (
-
` in ``. The `@import` from `node_modules` does not work with the Next.js CSS pipeline.
-
### app/globals.css
```css
@import "tailwindcss";
-
-@theme {
- --color-pe-primary-50: var(--pe-color-primary-50);
- --color-pe-primary-500: var(--pe-color-primary-500);
- --color-pe-primary-600: var(--pe-color-primary-600);
- --color-pe-primary-700: var(--pe-color-primary-700);
-
- --color-pe-gray-50: var(--pe-color-gray-50);
- --color-pe-gray-100: var(--pe-color-gray-100);
- --color-pe-gray-200: var(--pe-color-gray-200);
-
- --color-pe-error: var(--pe-color-error);
-
- --color-pe-bg-primary: var(--pe-color-bg-primary);
- --color-pe-text-primary: var(--pe-color-text-primary);
- --color-pe-text-secondary: var(--pe-color-text-secondary);
- --color-pe-text-tertiary: var(--pe-color-text-tertiary);
-
- --color-pe-border-light: var(--pe-color-border-light);
-}
+@import "@policyengine/ui-kit/theme.css";
body {
- font-family: var(--pe-font-family-primary);
- color: var(--pe-color-text-primary);
- background: var(--pe-color-bg-primary);
+ font-family: var(--font-sans);
+ color: var(--foreground);
+ background: var(--background);
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
```
+The single `@import "@policyengine/ui-kit/theme.css"` provides all design tokens (colors, spacing, typography, chart colors) as CSS variables that Tailwind 4 picks up automatically. No manual `@theme` block needed.
+
### app/page.jsx
```jsx
"use client";
import { useState } from "react";
-
-const PE_LOGO_URL =
- "https://raw.githubusercontent.com/PolicyEngine/policyengine-app-v2/main/app/public/assets/logos/policyengine/white.png";
+import { DashboardShell, Header, logos } from "@policyengine/ui-kit";
function getCountryFromHash() {
if (typeof window === "undefined") return "us";
@@ -144,25 +126,17 @@ export default function Home() {
}
return (
-
-
+
+ TOOL_TITLE
+
{/* Your tool UI goes here */}
-
+
);
}
```
@@ -177,6 +151,10 @@ export default function Home() {
## Step 4: Data pattern boilerplate
+> **Prefer Pattern B** (PolicyEngine API) unless the tool needs microsimulation,
+> custom reforms, or variables not in the API. Pattern C is significantly more complex
+> and should be the last resort.
+
Based on the user's choice, add the appropriate data fetching code.
**For Pattern B (PolicyEngine API):** Create `lib/api.js`:
@@ -195,38 +173,127 @@ export async function calculate(countryId, household) {
}
```
-**For Pattern C (Modal API):** Create `modal_app.py`:
+**For Pattern C (Custom Modal API — gateway + polling):**
+
+Pattern C uses a **three-file backend structure** mirroring policyengine-api-v2's simulation service: a standalone image setup, a worker app, and pure simulation logic. A lightweight gateway manages job submission/polling. This avoids Modal's ~150s gateway timeout and a common crash-loop where module-level imports fail.
+
+First, look up the latest package version from PyPI. Do NOT guess or use a version from memory:
+
+```bash
+pip index versions policyengine-us 2>/dev/null | head -1
+# or for UK: pip index versions policyengine-uk 2>/dev/null | head -1
+```
+
+Create `backend/_image_setup.py` (standalone snapshot function, no package imports at module level):
+
+```python
+def snapshot_models():
+ """Pre-load models at image build time for fast cold starts."""
+ import logging
+ logging.basicConfig(level=logging.INFO)
+ logger = logging.getLogger(__name__)
+ logger.info("Pre-loading tax-benefit system...")
+ from policyengine_us import CountryTaxBenefitSystem # or policyengine_uk
+ CountryTaxBenefitSystem()
+ logger.info("Models pre-loaded into image snapshot")
+```
+
+Create `backend/simulation.py` (pure logic, policyengine at module level — captured in snapshot):
+
+```python
+from policyengine_us import Simulation # Snapshotted at build time
+
+def run_compute(params: dict) -> dict:
+ sim = Simulation(situation=params["household"])
+ return {"result": float(sim.calculate("variable_name", 2025).sum())}
+```
+
+Create `backend/app.py` (worker app, only `modal` at module level):
```python
import modal
+from pathlib import Path
+from _image_setup import snapshot_models
+
+_BACKEND_DIR = Path(__file__).parent
+app = modal.App("TOOL_NAME-workers")
+image = (
+ modal.Image.debian_slim(python_version="3.11")
+ .pip_install("policyengine-us==LATEST_VERSION", "pydantic")
+ .run_function(snapshot_models)
+ .add_local_file(str(_BACKEND_DIR / "simulation.py"), remote_path="/root/simulation.py")
+)
+
+@app.function(image=image, cpu=8.0, memory=32768, timeout=3600)
+def compute(params: dict) -> dict:
+ from simulation import run_compute
+ return run_compute(params)
+```
+
+Create `backend/modal_app.py` (lightweight gateway, no policyengine):
+
+```python
+import modal
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
app = modal.App("TOOL_NAME")
-image = modal.Image.debian_slim().pip_install("policyengine-us==X.Y.Z")
-
-@app.function(image=image, timeout=300)
-@modal.web_endpoint(method="POST")
-def calculate(params: dict):
- from policyengine_us import Simulation
- # Build household from params
- sim = Simulation(situation=household)
- return {"result": float(sim.calculate("variable_name", 2025).sum())}
+gateway_image = modal.Image.debian_slim(python_version="3.11").pip_install("fastapi", "pydantic")
+WORKER_APP = "TOOL_NAME-workers"
+FUNCTION_MAP = {"calculate": "compute"}
+
+web_app = FastAPI()
+web_app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+@web_app.post("/submit/{endpoint}")
+def submit(endpoint: str, params: dict):
+ if endpoint not in FUNCTION_MAP:
+ raise HTTPException(status_code=404, detail=f"Unknown endpoint: {endpoint}")
+ fn = modal.Function.from_name(WORKER_APP, FUNCTION_MAP[endpoint])
+ call = fn.spawn(params)
+ return {"job_id": call.object_id}
+
+@web_app.get("/status/{job_id}")
+def status(job_id: str):
+ from modal.functions import FunctionCall
+ call = FunctionCall.from_id(job_id)
+ try:
+ result = call.get(timeout=0)
+ return {"status": "ok", "result": result}
+ except TimeoutError:
+ return {"status": "computing"}
+ except Exception as e:
+ return {"status": "error", "message": str(e)}
+
+@app.function(image=gateway_image)
+@modal.asgi_app()
+def fastapi_app():
+ return web_app
```
-And `lib/api.js`:
+And `lib/api.js` (polling client):
```js
const API_URL =
process.env.NEXT_PUBLIC_API_URL ||
- "https://policyengine--TOOL_NAME-calculate.modal.run";
+ "https://policyengine--TOOL_NAME-fastapi-app.modal.run";
-export async function calculate(params) {
- const res = await fetch(API_URL, {
+export async function submitJob(endpoint, params) {
+ const res = await fetch(`${API_URL}/submit/${endpoint}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
- if (!res.ok) throw new Error(`API error: ${res.status}`);
- return res.json();
+ if (!res.ok) throw new Error(`Submit failed: ${res.status}`);
+ const data = await res.json();
+ return data.job_id;
+}
+
+export async function pollStatus(jobId) {
+ const res = await fetch(`${API_URL}/status/${jobId}`);
+ if (!res.ok) throw new Error(`Status check failed: ${res.status}`);
+ return res.json(); // { status: "computing" | "ok" | "error", result?, message? }
}
```
@@ -247,12 +314,15 @@ vercel link --scope policy-engine
vercel --prod --yes
```
-If using Pattern C (Modal):
+If using Pattern C (Modal gateway + worker):
```bash
unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET
-modal deploy modal_app.py
+# Deploy worker first (includes image snapshot — first build takes ~5 min)
+modal deploy backend/app.py
+# Deploy gateway (lightweight job submission/polling)
+modal deploy backend/modal_app.py
vercel env add NEXT_PUBLIC_API_URL production
-# Enter the Modal URL
+# Enter: https://policyengine--TOOL_NAME-fastapi-app.modal.run
vercel --prod --force --yes --scope policy-engine
```
diff --git a/skills/documentation/policyengine-design-skill/SKILL.md b/skills/documentation/policyengine-design-skill/SKILL.md
index d59b34b..26d558f 100644
--- a/skills/documentation/policyengine-design-skill/SKILL.md
+++ b/skills/documentation/policyengine-design-skill/SKILL.md
@@ -2,114 +2,104 @@
name: policyengine-design
description: |
PolicyEngine design system — tokens, typography, colors, charts, and branding for all project types.
- Triggers: "brand colors", "design tokens", "PolicyEngine colors", "typography", "font", "color palette", "CSS variables", "pe-color", "design system", "branding guidelines"
+ Triggers: "brand colors", "design tokens", "PolicyEngine colors", "typography", "font", "color palette", "CSS variables", "design system", "branding guidelines"
---
# PolicyEngine design system
-Single source of truth for PolicyEngine's visual identity. All tokens live in `@policyengine/design-system`. Every project — app-v2, standalone tools, charts — should reference these tokens, never hardcode hex values.
+Single source of truth for PolicyEngine's visual identity. Design tokens are defined as CSS custom properties in `@policyengine/ui-kit/theme.css`. Every frontend project imports this single CSS file.
**When to use which format:**
| Context | Approach | Example |
|---------|----------|---------|
-| **React/Next.js components** | CSS vars or TS imports | `style={{ color: "var(--pe-color-primary-500)" }}` or `colors.primary[500]` |
-| **Recharts (SVG)** | Resolve CSS vars at render time via `getCssVar()` | `const teal = getCssVar("--pe-color-primary-500")` |
-| **Tailwind** | Use `theme.extend.colors` mapped to CSS vars | `className="text-pe-primary-500"` |
-| **Python charts (Plotly/matplotlib)** | Hex values with CSS var name in comment | `TEAL = "#319795" # --pe-color-primary-500` |
+| **React components** | Tailwind semantic classes | `className="bg-primary text-foreground"` |
+| **Brand palette** | Tailwind direct classes | `className="bg-teal-500 text-gray-600"` |
+| **Recharts (SVG)** | CSS vars directly in fill/stroke | `fill="var(--chart-1)"` |
+| **Inline styles** | CSS vars | `style={{ color: "var(--primary)" }}` |
+| **Python (Plotly)** | Hex with CSS var comment | `TEAL = "#319795" # --chart-1` |
| **`` tags, static HTML** | Hex values with CSS var name in comment | `content="#319795"` |
Python has no CSS runtime, so hex values are acceptable — but always comment with the CSS var name so values stay traceable to the design system.
-## The design system package
+## The ui-kit theme
**Install:**
```bash
-bun install @policyengine/design-system
+bun install @policyengine/ui-kit
```
-**Three export formats:**
+**Import the theme CSS in your `globals.css`:**
+```css
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+```
-| Format | Import | Use case |
-|--------|--------|----------|
-| TypeScript | `import { colors } from '@policyengine/design-system/tokens'` | app-v2, any TS/JS project |
-| JSON | `import tokens from '@policyengine/design-system/tokens.json'` | Python scripts, config files |
-| CSS | `import '@policyengine/design-system/tokens.css'` | Standalone tools, plain HTML |
+The first line enables Tailwind v4 utilities. The second provides all PE design tokens, `@theme` configuration, and base styles. Both are required — see `policyengine-ui-kit-consumer-skill` for details.
-**CDN (no install):**
-```html
-
-```
+**Source:** `PolicyEngine/policyengine-ui-kit/src/theme/tokens.css`
-**Source:** `PolicyEngine/policyengine-app-v2/packages/design-system/`
+The theme CSS has three layers:
+1. **`:root`** — shadcn/ui semantic variables (`--primary`, `--background`, `--chart-1`, etc.)
+2. **`@theme inline`** — Bridges `:root` vars to Tailwind utilities (`bg-primary`, `text-foreground`)
+3. **`@theme`** — Brand palette (`bg-teal-500`, `text-gray-600`), font sizes, spacing, breakpoints
## Colors
### Primary — teal
-| Token | Hex | Usage |
-|-------|-----|-------|
-| `primary.500` | `#319795` | **Main brand color** — buttons, links, active states |
-| `primary.400` | `#38B2AC` | Lighter interactive elements |
-| `primary.600` | `#2C7A7B` | Hover state |
-| `primary.700` | `#285E61` | Active/pressed state |
-| `primary.50` | `#E6FFFA` | Tinted backgrounds |
-| `primary.800` | `#234E52` | Dark text on light teal |
-
-CSS: `var(--pe-color-primary-500)` through `var(--pe-color-primary-900)`
-
-### Gray
-
-| Token | Hex | Usage |
-|-------|-----|-------|
-| `gray.50` | `#F9FAFB` | Subtle backgrounds |
-| `gray.100` | `#F2F4F7` | Card backgrounds |
-| `gray.200` | `#E2E8F0` | Borders, dividers |
-| `gray.500` | `#6B7280` | Secondary text |
-| `gray.600` | `#4B5563` | Chart secondary series |
-| `gray.700` | `#344054` | Dark UI text |
-
-### Blue (accent)
-
-| Token | Hex | Usage |
-|-------|-----|-------|
-| `blue.500` | `#0EA5E9` | Informational highlights |
-| `blue.700` | `#026AA2` | Chart secondary series |
-
-### Semantic
-
-| Color | Hex | CSS variable | Usage |
-|-------|-----|-------------|-------|
-| Success | `#22C55E` | `--pe-color-success` | Positive changes, gains |
-| Error | `#EF4444` | `--pe-color-error` | Negative changes, losses |
-| Warning | `#FEC601` | `--pe-color-warning` | Cautions, alerts |
-| Info | `#1890FF` | `--pe-color-info` | Informational |
-
-### Text
-
-| Token | Hex | CSS variable |
-|-------|-----|-------------|
-| `text.primary` | `#000000` | `--pe-color-text-primary` |
-| `text.secondary` | `#5A5A5A` | `--pe-color-text-secondary` |
-| `text.tertiary` | `#9CA3AF` | `--pe-color-text-tertiary` |
-
-### Background
-
-| Token | Hex | CSS variable |
-|-------|-----|-------------|
-| `background.primary` | `#FFFFFF` | `--pe-color-bg-primary` |
-| `background.secondary` | `#F5F9FF` | `--pe-color-bg-secondary` |
-| `background.tertiary` | `#F1F5F9` | `--pe-color-bg-tertiary` |
-
-### Legacy colors (deprecated)
-
-These appear in older projects. Migrate to the values above.
-
-| Old | Hex | Replacement |
-|-----|-----|-------------|
-| `TEAL_ACCENT` | `#319795` | `primary.500` (`#319795`) |
-| `BLUE_PRIMARY` | `#026AA2` | `blue.700` (`#026AA2`) |
-| `DARK_GRAY` | `#5A5A5A` | `text.secondary` (`#5A5A5A`) |
+| Token | Hex | Tailwind class | Usage |
+|-------|-----|---------------|-------|
+| `teal-500` | `#319795` | `bg-teal-500` | **Main brand color** — charts, highlights |
+| `teal-400` | `#38B2AC` | `bg-teal-400` | Lighter interactive elements |
+| `teal-600` | `#2C7A7B` | `bg-teal-600` / `bg-primary` | Hover state, buttons |
+| `teal-700` | `#285E61` | `bg-teal-700` | Active/pressed state |
+| `teal-50` | `#E6FFFA` | `bg-teal-50` | Tinted backgrounds |
+| `teal-800` | `#234E52` | `bg-teal-800` | Dark text on light teal |
+
+### Semantic (shadcn/ui)
+
+| Role | CSS variable | Tailwind class | Hex |
+|------|-------------|---------------|-----|
+| Primary | `--primary` | `bg-primary` | `#2C7A7B` |
+| Background | `--background` | `bg-background` | `#FFFFFF` |
+| Foreground | `--foreground` | `text-foreground` | `#000000` |
+| Muted | `--muted` | `bg-muted` | `#F2F4F7` |
+| Muted foreground | `--muted-foreground` | `text-muted-foreground` | `#6B7280` |
+| Border | `--border` | `border-border` | `#E2E8F0` |
+| Destructive | `--destructive` | `bg-destructive` | `#EF4444` |
+| Card | `--card` | `bg-card` | `#FFFFFF` |
+| Ring | `--ring` | `ring-ring` | `#319795` |
+
+### Charts
+
+| CSS variable | Tailwind class | Hex | Usage |
+|-------------|---------------|-----|-------|
+| `--chart-1` | `fill-chart-1` | `#319795` | Primary series (teal) |
+| `--chart-2` | `fill-chart-2` | `#0EA5E9` | Secondary series (blue) |
+| `--chart-3` | `fill-chart-3` | `#285E61` | Tertiary series (dark teal) |
+| `--chart-4` | `fill-chart-4` | `#026AA2` | Quaternary series (dark blue) |
+| `--chart-5` | `fill-chart-5` | `#6B7280` | Quinary series (gray) |
+
+### Additional semantic colors
+
+| Color | Hex | Tailwind class |
+|-------|-----|---------------|
+| Success | `#22C55E` | `text-success` / `bg-success` |
+| Error | `#EF4444` | `text-destructive` / `bg-destructive` |
+| Warning | `#FEC601` | `text-warning` / `bg-warning` |
+| Info | `#1890FF` | `text-info` / `bg-info` |
+
+### Gray scale
+
+| Token | Hex | Tailwind class |
+|-------|-----|---------------|
+| `gray-50` | `#F9FAFB` | `bg-gray-50` |
+| `gray-100` | `#F2F4F7` | `bg-gray-100` |
+| `gray-200` | `#E2E8F0` | `bg-gray-200` |
+| `gray-500` | `#6B7280` | `text-gray-500` |
+| `gray-600` | `#4B5563` | `text-gray-600` |
+| `gray-700` | `#344054` | `text-gray-700` |
## Typography
@@ -117,12 +107,10 @@ These appear in older projects. Migrate to the values above.
**Two font families only: Inter + JetBrains Mono.** No serif fonts, no Roboto, no Public Sans.
-| Context | Font | CSS variable |
-|---------|------|-------------|
-| **Everything** (UI, charts, blog, tools) | Inter | `--pe-font-family-primary` |
-| **Code** | JetBrains Mono | `--pe-font-family-mono` |
-
-Legacy aliases (`--pe-font-family-chart`, `--pe-font-family-body`, `--pe-font-family-prose`, `--pe-font-family-secondary`) all resolve to Inter for backward compatibility.
+| Context | Font | CSS variable | Tailwind |
+|---------|------|-------------|----------|
+| **Everything** (UI, charts, blog, tools) | Inter | `--font-sans` | `font-sans` |
+| **Code** | JetBrains Mono | `--font-mono` | `font-mono` |
**Loading Inter:**
```html
@@ -131,15 +119,15 @@ Legacy aliases (`--pe-font-family-chart`, `--pe-font-family-body`, `--pe-font-fa
### Font sizes
-| Token | Size | Usage |
-|-------|------|-------|
-| `xs` | 12px | Small labels, captions |
-| `sm` | 14px | Body text, form labels |
-| `base` | 16px | Large body text |
-| `lg` | 18px | Subheadings |
-| `xl` | 20px | Section titles |
-| `2xl` | 24px | Page titles |
-| `3xl` | 28px | Large headings |
+| Tailwind class | Size | Usage |
+|---------------|------|-------|
+| `text-xs` | 12px | Small labels, captions |
+| `text-sm` | 14px | Body text, form labels |
+| `text-base` | 16px | Large body text |
+| `text-lg` | 18px | Subheadings |
+| `text-xl` | 20px | Section titles |
+| `text-2xl` | 24px | Page titles |
+| `text-3xl` | 28px | Large headings |
### Sentence case
@@ -151,34 +139,45 @@ All UI text uses sentence case — capitalize only the first word and proper nou
## Spacing
-| Token | Value | CSS variable |
-|-------|-------|-------------|
-| `xs` | 4px | `--pe-space-xs` |
-| `sm` | 8px | `--pe-space-sm` |
-| `md` | 12px | `--pe-space-md` |
-| `lg` | 16px | `--pe-space-lg` |
-| `xl` | 20px | `--pe-space-xl` |
-| `2xl` | 24px | `--pe-space-2xl` |
-| `3xl` | 32px | `--pe-space-3xl` |
-| `4xl` | 48px | `--pe-space-4xl` |
+Standard Tailwind spacing classes (`p-4`, `gap-2`, `m-6`) use the default Tailwind scale. Named spacing tokens:
+
+| Token | Value | Tailwind class |
+|-------|-------|---------------|
+| Header | 58px | `h-header` |
+| Sidebar | 280px | `w-sidebar` |
+| Content | 976px | `max-w-content` |
### Border radius
-| Token | Value | CSS variable |
-|-------|-------|-------------|
-| `sm` | 4px | `--pe-radius-sm` |
-| `md` | 6px | `--pe-radius-md` |
-| `lg` | 8px | `--pe-radius-lg` |
+| Tailwind class | Value |
+|---------------|-------|
+| `rounded-sm` | 4px |
+| `rounded-md` | 6px |
+| `rounded-lg` | 8px |
## Chart branding
+### Recharts (React tools)
+
+```tsx
+import { BarChart, Bar, XAxis, YAxis, Tooltip } from "recharts";
+
+
-
-
- 
-
- TOOL_TITLE
-
+
+// CORRECT — use Tailwind class
+
+
+// CORRECT — use CSS var for inline styles
+
+```
+
+### 5. Creating tailwind.config.ts
+
+Tailwind v4 does NOT use `tailwind.config.ts`. All configuration is in CSS via `@theme` blocks. The ui-kit theme CSS file handles this.
+
+### 6. Using old pe-* prefixed classes
+
+```tsx
+// WRONG — old convention
+
+
+// CORRECT — standard Tailwind/shadcn classes
+
+```
+
+## Related skills
+
+- `policyengine-design-skill` — Token values, color tables, chart branding
+- `policyengine-frontend-builder-spec-skill` — Mandatory technology requirements
+- `policyengine-recharts-skill` — Chart-specific patterns
+- `policyengine-interactive-tools-skill` — Standalone tool scaffolding
diff --git a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md b/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md
new file mode 100644
index 0000000..8e7021b
--- /dev/null
+++ b/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md
@@ -0,0 +1,246 @@
+---
+name: policyengine-ui-kit-consumer
+description: |
+ This skill should be used when setting up a new project that uses @policyengine/ui-kit,
+ debugging CSS or styling issues in a consumer app, or when Tailwind utility classes are not
+ being generated. Also use when creating globals.css, configuring PostCSS, or troubleshooting
+ "no styles", "no spacing", or "no layout" problems.
+ Triggers: "ui-kit import", "globals.css setup", "Tailwind not working", "styles not applying",
+ "utility classes missing", "setup ui-kit", "PostCSS config", "no styling", "CSS broken",
+ "import ui-kit", "theme.css", "no layout", "no spacing", "@tailwindcss/postcss"
+---
+
+# Consuming @policyengine/ui-kit
+
+How to correctly import and use the PolicyEngine UI kit's design system in any consumer application. This skill covers the required setup, the correct import order, and common mistakes that cause styling to break.
+
+## Required Consumer Setup
+
+Every app using `@policyengine/ui-kit` needs exactly three things:
+
+### 1. Install dependencies
+
+```bash
+bun add @policyengine/ui-kit
+bun add -D @tailwindcss/postcss postcss
+```
+
+### 2. Create `postcss.config.mjs`
+
+```js
+export default {
+ plugins: {
+ "@tailwindcss/postcss": {},
+ },
+};
+```
+
+No other PostCSS plugins needed — `@tailwindcss/postcss` handles imports, vendor prefixes, and nesting internally.
+
+### 3. Create `app/globals.css` with two imports
+
+```css
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+```
+
+**Both lines are required. The order matters.** Tailwind must come first because the ui-kit's `@theme` blocks extend it.
+
+This provides:
+- All Tailwind v4 utility classes (`flex`, `grid`, `p-4`, `text-sm`, etc.)
+- All PolicyEngine design tokens (colors, fonts, spacing, breakpoints)
+- shadcn/ui semantic tokens (`bg-primary`, `text-foreground`, `border-border`)
+- Brand palette (`bg-teal-500`, `text-gray-600`, `bg-blue-500`)
+- Base element styles (body font, border defaults, slider styling)
+
+## How It Works
+
+Understanding the flow prevents debugging confusion:
+
+1. The consumer's build tool (Next.js/Vite) processes `globals.css` through `@tailwindcss/postcss`
+2. `@import "tailwindcss"` establishes the cascade layers and enables utility class generation
+3. Tailwind's automatic source detection scans from `process.cwd()` (the consumer's project root) — this is why the consumer's utility classes get generated
+4. `@import "@policyengine/ui-kit/theme.css"` is inlined by Tailwind's import bundler
+5. The ui-kit's `@theme` and `@theme inline` blocks merge into the consumer's Tailwind build
+6. The ui-kit's `@source` directive tells Tailwind to also scan the ui-kit's own component files
+7. The ui-kit's `@layer base` styles apply within the existing cascade
+
+## What NOT to Do
+
+### Do NOT skip the Tailwind import
+
+```css
+/* WRONG — utility classes will not be generated */
+@import "@policyengine/ui-kit/theme.css";
+```
+
+```css
+/* CORRECT */
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+```
+
+Without `@import "tailwindcss"`, there is no Tailwind build. The ui-kit's `@theme` blocks have nothing to extend. No utility classes (`flex`, `p-4`, `grid`) will exist.
+
+### Do NOT add a duplicate Tailwind import
+
+```css
+/* WRONG — double Tailwind causes conflicting resets and broken styles */
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+@import "tailwindcss";
+```
+
+The ui-kit does NOT contain `@import "tailwindcss"` inside it. One import at the top of `globals.css` is all that's needed.
+
+### Do NOT create tailwind.config.ts
+
+```
+/* WRONG — Tailwind v4 does not use JavaScript config */
+tailwind.config.ts ← DELETE THIS
+```
+
+Tailwind v4 is CSS-first. All configuration comes from `@theme` blocks in the ui-kit's theme CSS. There is no `content` array, no `theme.extend`, no JavaScript config.
+
+### Do NOT add postcss-import or autoprefixer
+
+```js
+/* WRONG — these conflict with @tailwindcss/postcss */
+export default {
+ plugins: {
+ "postcss-import": {},
+ "@tailwindcss/postcss": {},
+ "autoprefixer": {},
+ },
+};
+```
+
+```js
+/* CORRECT — @tailwindcss/postcss handles both internally */
+export default {
+ plugins: {
+ "@tailwindcss/postcss": {},
+ },
+};
+```
+
+### Do NOT put `@import "tailwindcss"` inside the ui-kit package
+
+If working on the ui-kit itself, never add `@import "tailwindcss"` to `tokens.css`. The consumer owns that import. See `tailwind-design-system-authoring` skill for details.
+
+### Do NOT hardcode hex colors or font names
+
+```tsx
+/* WRONG */
+
+
+/* CORRECT — use Tailwind classes */
+
+
+/* CORRECT — use CSS variables for inline styles */
+
+```
+
+## Troubleshooting
+
+### "No styles at all" — page is unstyled
+
+1. Verify `globals.css` has `@import "tailwindcss"` as the first line
+2. Verify `postcss.config.mjs` exists with `@tailwindcss/postcss`
+3. Verify `@tailwindcss/postcss` and `postcss` are installed as devDependencies
+4. Verify `globals.css` is imported in `app/layout.tsx` (or `pages/_app.tsx`)
+
+### "Tokens load but no utility classes" — colors work but no flex/grid/padding
+
+This means `@theme` tokens are being processed but Tailwind's utility generation isn't scanning files correctly.
+
+**If missing classes are from the consumer's own components** (`app/`, `components/`):
+1. Verify `@import "tailwindcss"` comes BEFORE the ui-kit import (order matters)
+2. Check that `process.cwd()` is the project root when the build runs
+3. If in a monorepo, add `source()` to the import: `@import "tailwindcss" source("./src")`
+
+**If missing classes are from ui-kit components** (`DashboardShell`, `Header`, `InputPanel`, etc.):
+The ui-kit's `@source` directive in `tokens.css` may not match the actual directory structure. This is a ui-kit-side fix — the `@source` glob must cover all directories containing `.tsx` files with `className=` attributes. See the `tailwind-design-system-authoring` skill for the verification procedure.
+
+### "Double styling / Tailwind defaults override tokens"
+
+This means Tailwind is being imported twice.
+
+1. Check that the ui-kit's `tokens.css` does NOT contain `@import "tailwindcss"`
+2. Check that `globals.css` has only ONE `@import "tailwindcss"` line
+3. Check for other CSS files that might import Tailwind
+
+### "Utility classes from ui-kit components missing"
+
+The ui-kit ships `@source` directives to tell Tailwind to scan its components. If this fails:
+
+1. Add a manual `@source` in `globals.css`:
+ ```css
+ @import "tailwindcss";
+ @import "@policyengine/ui-kit/theme.css";
+ @source "../node_modules/@policyengine/ui-kit/src";
+ ```
+2. If using `bun link` (symlinked package), the path resolves differently — check the actual resolved path
+
+## Framework-Specific Notes
+
+### Next.js 14 (App Router)
+
+Standard setup. Requires `@tailwindcss/postcss` in PostCSS config.
+
+```
+app/
+ globals.css ← @import "tailwindcss"; @import ui-kit theme
+ layout.tsx ← import "./globals.css";
+postcss.config.mjs
+```
+
+### Next.js 15+ / Next.js 16
+
+Same setup. Turbopack processes PostCSS normally. No changes needed.
+
+### Vite (non-Next.js)
+
+Use `@tailwindcss/vite` instead of `@tailwindcss/postcss`:
+
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+export default defineConfig({ plugins: [tailwindcss()] })
+```
+
+No `postcss.config.mjs` needed — the Vite plugin handles everything.
+
+`globals.css` is the same two imports.
+
+## Quick Reference
+
+| What | Where | Content |
+|------|-------|---------|
+| PostCSS config | `postcss.config.mjs` | `{ plugins: { "@tailwindcss/postcss": {} } }` |
+| Entry CSS | `app/globals.css` | `@import "tailwindcss"; @import "@policyengine/ui-kit/theme.css";` |
+| Dependencies | `package.json` devDeps | `@tailwindcss/postcss`, `postcss` |
+| Dependencies | `package.json` deps | `@policyengine/ui-kit` |
+
+## What the Theme Provides
+
+After the two-line import, these are available:
+
+| Category | Examples | Source |
+|----------|---------|--------|
+| Semantic colors | `bg-primary`, `text-foreground`, `border-border` | `:root` + `@theme inline` |
+| Brand palette | `bg-teal-500`, `text-gray-600`, `bg-blue-500` | `@theme` |
+| Status colors | `text-success`, `bg-warning`, `text-error` | `@theme` |
+| Chart colors | `fill-chart-1` through `fill-chart-5` | `:root` + `@theme inline` |
+| Typography | `text-sm` (14px), `text-base` (16px), `font-sans` | `@theme` |
+| Spacing | `h-header` (58px), `w-sidebar` (280px), `max-w-content` (976px) | `@theme` |
+| Breakpoints | `xs:`, `sm:`, `md:`, `lg:`, `xl:`, `2xl:` | `@theme` |
+| Radius | `rounded-sm` (4px), `rounded-md` (6px), `rounded-lg` (8px) | `@theme inline` |
+| All Tailwind utilities | `flex`, `grid`, `p-4`, `gap-2`, `hidden`, etc. | `@import "tailwindcss"` |
+
+## Related Skills
+
+- `policyengine-design-skill` — Full token reference (hex values, usage guidelines)
+- `policyengine-tailwind-shadcn-skill` — `@theme` namespace mechanics, SVG var() usage
+- `policyengine-interactive-tools-skill` — Full tool scaffolding checklist
+- `policyengine-vercel-deployment-skill` — Deploying consumer apps
diff --git a/skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-broken-setup.md b/skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-broken-setup.md
new file mode 100644
index 0000000..79ed348
--- /dev/null
+++ b/skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-broken-setup.md
@@ -0,0 +1,127 @@
+# Migrating from a Broken Tailwind + ui-kit Setup
+
+Step-by-step guide for fixing projects where the ui-kit was imported incorrectly and styles are broken.
+
+## Symptoms of a Broken Setup
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| No styles at all (unstyled HTML) | Missing `@import "tailwindcss"` or missing PostCSS config |
+| Colors load but no layout (no flex/grid/padding) | `@import "tailwindcss"` is inside the ui-kit, not in consumer's CSS |
+| Tailwind defaults override PE tokens | Double `@import "tailwindcss"` (once in consumer, once in ui-kit) |
+| Correct on first load, wrong after hot reload | PostCSS processing order issue — check import order |
+| Works with Tailwind CLI but not with Next.js | Missing `@tailwindcss/postcss` in PostCSS config |
+
+## Fix Procedure
+
+### Step 1: Verify the ui-kit's tokens.css
+
+Read `node_modules/@policyengine/ui-kit/src/theme/tokens.css`. It must NOT contain `@import "tailwindcss"`.
+
+If it does, the ui-kit itself needs to be fixed (remove that line). If using a local/linked version, fix it there.
+
+### Step 2: Clean globals.css
+
+Replace the entire contents of `app/globals.css` with exactly:
+
+```css
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+```
+
+Remove any:
+- Additional `@import "tailwindcss"` lines
+- Manual `@theme` blocks that duplicate ui-kit tokens
+- Manual `:root` blocks with PE colors
+- `@tailwind base; @tailwind components; @tailwind utilities;` (v3 syntax)
+- `@config` directives
+- `postcss-import` related imports
+
+### Step 3: Verify postcss.config.mjs
+
+Replace with exactly:
+
+```js
+export default {
+ plugins: {
+ "@tailwindcss/postcss": {},
+ },
+};
+```
+
+Remove any:
+- `postcss-import` (Tailwind handles imports)
+- `autoprefixer` (Tailwind handles prefixing)
+- `tailwindcss` (v3 plugin name — v4 uses `@tailwindcss/postcss`)
+- `postcss-nested` (Tailwind uses Lightning CSS for nesting)
+
+### Step 4: Delete stale config files
+
+Remove if present:
+- `tailwind.config.ts` / `tailwind.config.js` (v4 is CSS-first)
+- `tailwind.config.cjs` / `tailwind.config.mjs`
+
+### Step 5: Verify dependencies
+
+```bash
+# Required
+bun add @policyengine/ui-kit
+bun add -D @tailwindcss/postcss postcss
+
+# Remove stale deps if present
+bun remove tailwindcss-animate # replaced by tw-animate-css (bundled in ui-kit)
+bun remove postcss-import # handled by @tailwindcss/postcss
+bun remove autoprefixer # handled by @tailwindcss/postcss
+```
+
+Note: `tailwindcss` itself should still be installed (it's a peer dep of `@tailwindcss/postcss`).
+
+### Step 6: Clear caches and restart
+
+```bash
+rm -rf .next node_modules/.cache
+bun dev
+```
+
+### Step 7: Verify
+
+Open the app in a browser. Check that:
+1. Page has the correct background color (white, `--background`)
+2. Text is in Inter font
+3. Teal brand colors are present
+4. Layout utilities work (`flex`, `grid`, `p-4`, `gap-2`)
+5. No Tailwind default blue/indigo colors leaking through
+
+## If `@source` Scanning Fails
+
+If ui-kit component styles are missing (components render but with wrong styling), the `@source` directive inside the ui-kit's CSS may not be reaching the consumer's build.
+
+Add a manual fallback in `globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+@source "../node_modules/@policyengine/ui-kit/src";
+```
+
+For `bun link`'d packages, find the real path:
+
+```bash
+readlink -f node_modules/@policyengine/ui-kit
+```
+
+And use that absolute path or adjust the relative path accordingly.
+
+## History of This Issue
+
+The original problem: `tokens.css` in the ui-kit contained `@import "tailwindcss"`. This caused Tailwind's source detection to scan from the ui-kit's directory inside `node_modules` instead of the consumer's project. Design tokens loaded (because `@theme` blocks are processed regardless of scan directory), but utility classes for the consumer's components were not generated (because the scanner only found files inside the ui-kit package).
+
+Multiple fix attempts failed:
+- Adding `@source` directives in the consumer — path resolution was fragile
+- Inlining all tokens in the consumer's CSS — user rejected (ui-kit should own styling)
+- Removing `@import "tailwindcss"` from tokens.css but not adding it to the consumer — no Tailwind at all
+
+The correct fix (confirmed by Tailwind maintainers and every major Tailwind-based library):
+1. Remove `@import "tailwindcss"` from the library
+2. Consumer writes `@import "tailwindcss"` first, then imports the library's theme
+3. Library includes `@source` for its own components
diff --git a/skills/technical-patterns/policyengine-recharts-skill/SKILL.md b/skills/technical-patterns/policyengine-recharts-skill/SKILL.md
index 7b76e9c..62ec443 100644
--- a/skills/technical-patterns/policyengine-recharts-skill/SKILL.md
+++ b/skills/technical-patterns/policyengine-recharts-skill/SKILL.md
@@ -100,15 +100,13 @@ Recharts default tooltip separator is ` : ` (with leading space). Always set `se
## Standard chart template
-Recharts renders to SVG, which cannot read CSS custom properties. Resolve design tokens at render time with a helper (see `policyengine-interactive-tools-skill` for the `getCssVar` utility):
+SVG `fill` and `stroke` attributes accept `var()` directly -- no helper function is needed to resolve CSS custom properties. Use the shadcn/ui chart color variables (`--chart-1` through `--chart-5`) for series colors and standard semantic variables for UI elements:
```tsx
-import { useMemo } from "react";
import {
LineChart, Line, XAxis, YAxis, CartesianGrid,
Tooltip, ResponsiveContainer, Label, ReferenceDot,
} from "recharts";
-import getCssVar from "@/lib/getCssVar"; // reads CSS custom properties
interface DataPoint { x: number; y: number; }
@@ -116,14 +114,6 @@ export default function MyChart({ data, highlightX }: {
data: DataPoint[];
highlightX?: number;
}) {
- // Resolve design tokens for SVG (never hardcode hex values)
- const { primaryColor, darkTeal, gridColor, fontFamily } = useMemo(() => ({
- primaryColor: getCssVar("--pe-color-primary-500"),
- darkTeal: getCssVar("--pe-color-primary-900"),
- gridColor: getCssVar("--pe-color-gray-200"),
- fontFamily: getCssVar("--pe-font-family-primary") || "Inter, sans-serif",
- }), []);
-
const fmt = (v: number) => v.toLocaleString("en-US", {
style: "currency", currency: "USD", maximumFractionDigits: 0,
});
@@ -141,27 +131,27 @@ export default function MyChart({ data, highlightX }: {
return (
-
[fmt(v), "Value"]} />
-
@@ -182,28 +172,40 @@ export default function MyChart({ data, highlightX }: {
## PolicyEngine styling
-Never hardcode hex colors in frontend chart code. Resolve from CSS custom properties at render time:
+Never hardcode hex colors in frontend chart code. Use CSS custom properties directly via `var()` in SVG attributes:
```typescript
-import getCssVar from "@/lib/getCssVar";
-
-// Resolve design tokens once per render (useMemo in components)
-const primaryColor = getCssVar("--pe-color-primary-500"); // Primary series
-const darkTeal = getCssVar("--pe-color-primary-900"); // Reference dots
-const gridColor = getCssVar("--pe-color-gray-200"); // Grid lines
-const lightFill = getCssVar("--pe-color-primary-alpha-40"); // Light fill
-const fontFamily = getCssVar("--pe-font-family-primary"); // Font
-
-// Tooltip
+// Chart series colors (shadcn/ui chart palette)
+// Use these for data series — lines, areas, bars, dots
+// --chart-1 Primary series (first line/bar)
+// --chart-2 Secondary series
+// --chart-3 Tertiary series / reference dots
+// --chart-4 Fourth series
+// --chart-5 Fifth series
+
+// Semantic UI colors — use for chart chrome (grids, borders, backgrounds)
+// --border Grid lines, axis lines
+// --background Tooltip background
+// --foreground Axis labels, tick text
+// --primary Interactive UI elements (buttons, links)
+// --font-sans Font family
+
+// Usage in JSX — pass var() directly to SVG attributes:
+
{/* Primary teal */}
+
{/* Hover state */}
+ {/* Body text */}
+ {/* Muted text */}
+
{/* Backgrounds */}
+
{/* Borders */}
+
+// Spacing — standard Tailwind classes
+
+
+// Typography (font sizes from ui-kit theme — use standard text-xs, text-sm, etc.)
+
+
+// Border radius
+
+```
+
+**Never hardcode hex colors, pixel spacing, or font values.** The Phase 5 validators check for violations.
+
+### Chart Patterns
+
+Charts use CSS variables directly from the ui-kit theme:
+
+```tsx
+// Standard Recharts pattern
+import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+
+
+
+
+
+```
+
+## Plan YAML Schema
+
+The plan is the contract between the planner and all other agents:
+
+```yaml
+dashboard:
+ name: string # kebab-case, becomes repo name
+ title: string # Human-readable title
+ description: string # One paragraph
+ country: string # us, uk, or both
+ audience: string # public, researchers, legislators, internal
+
+data_pattern: string # api-v2-alpha or custom-backend
+
+api_v2_integration: # Only if api-v2-alpha
+ endpoints_needed: [{ endpoint, purpose, variables_requested }]
+ stub_fixtures: [{ name, description, expected_outputs }]
+
+custom_backend: # Only if custom-backend
+ reason: string # WHY v2 alpha is insufficient
+ framework: string
+ policyengine_package: string
+ endpoints: [{ name, method, inputs, outputs, policyengine_variables }]
+
+tech_stack: # Fixed values, included for documentation
+ framework: react-nextjs
+ ui: "@policyengine/ui-kit"
+ styling: tailwind-with-ui-kit-theme
+ charts: recharts
+ testing: vitest
+
+components: # What to build
+ - type: input_form | chart | metric_card | data_table
+ id: string
+ # Type-specific fields...
+
+embedding:
+ register_in_apps_json: boolean
+ display_with_research: boolean
+ slug: string
+ tags: string[]
+
+tests:
+ api_tests: [{ name, description, input, expected }]
+ frontend_tests: [{ name, description }]
+ design_compliance: [{ name, description }]
+ embedding_tests: [{ name, description }]
+```
+
+## Embedding
+
+All dashboards are built to embed in policyengine.org via iframe:
+
+1. **Country detection:** Read `#country=` from URL hash
+2. **Hash sync:** Update hash on input change, `postMessage` to parent
+3. **Share URLs:** Point to `policyengine.org/{country}/{slug}`, not Vercel URL
+4. **Country toggle:** Hidden when embedded (country comes from route)
+
+See `policyengine-interactive-tools-skill` for full embedding documentation.
+
+## Validation Checklist
+
+Phase 5 runs four validators in parallel:
+
+**Build validator:** Build compiles, all tests pass.
+
+**Design validator:** No hardcoded colors/spacing/fonts, no `pe-*` classes, no `getCssVar`, Inter font loaded, sentence case headings, responsive at 768px and 480px, chart `ResponsiveContainer` wrappers.
+
+**Architecture validator:** Tailwind CSS v4 (`@import "tailwindcss"`, no config files), Next.js App Router (no Vite, no Pages Router), `@policyengine/ui-kit` installed and imported, bun as package manager.
+
+**Plan validator:** API contract matches plan, all plan components implemented, embedding features (country detection, hash sync, share URLs), loading and error states handled.
+
+## Deployment
+
+After the user merges the feature branch to `main`:
+
+```bash
+/deploy-dashboard
+```
+
+This handles:
+- Vercel frontend deployment
+- Modal backend deployment (if custom-backend)
+- Registration in policyengine-app-v2's apps.json (via PR)
+- Smoke testing
+
+## Future: API v2 Alpha Alignment
+
+When the API v2 alpha is production-ready, an alignment agent will:
+1. Read the plan's `api_v2_integration` section
+2. Replace stub functions in `client.ts` with real v2 alpha HTTP calls
+3. Implement the async job polling pattern
+4. Run the full validation suite against live API responses
+5. Update fixture data with real response shapes
+
+This is a planned future addition, not yet implemented.
diff --git a/skills/tools-and-apis/policyengine-frontend-builder-spec-skill/SKILL.md b/skills/tools-and-apis/policyengine-frontend-builder-spec-skill/SKILL.md
new file mode 100644
index 0000000..21ae0b1
--- /dev/null
+++ b/skills/tools-and-apis/policyengine-frontend-builder-spec-skill/SKILL.md
@@ -0,0 +1,311 @@
+---
+name: policyengine-frontend-builder-spec
+description: Mandatory frontend technology requirements for PolicyEngine dashboards and interactive tools — Tailwind CSS v4, Next.js (App Router), @policyengine/ui-kit theme, Vercel deployment
+---
+
+# Frontend builder spec
+
+Authoritative specification for all PolicyEngine frontend projects (dashboards and interactive tools). Any agent building or validating a frontend MUST load this skill and follow every requirement below. Where another agent's instructions conflict with this spec, **this spec wins**.
+
+## Mandatory requirements
+
+### 1. Tailwind CSS (v4+)
+
+The application MUST use **Tailwind CSS v4** for all styling. Tailwind utility classes are the primary styling mechanism.
+
+- MUST install `tailwindcss` (v4+)
+- MUST have a `globals.css` containing:
+ ```css
+ @import "tailwindcss";
+ @import "@policyengine/ui-kit/theme.css";
+ ```
+- MUST NOT have a `tailwind.config.ts` or `tailwind.config.js` — Tailwind v4 uses `@theme` in CSS instead
+- MUST NOT have a `postcss.config.js` or `postcss.config.mjs` — Tailwind v4 does not require PostCSS
+- MUST NOT use `@tailwind base; @tailwind components; @tailwind utilities;` — use `@import "tailwindcss"` instead
+- MUST NOT use plain CSS files or CSS modules (`*.module.css`) for layout or styling
+- MUST NOT use other CSS-in-JS libraries (styled-components, emotion, vanilla-extract)
+- MUST NOT use other component frameworks for styling (Mantine, Chakra UI, Material UI)
+- The only CSS files allowed are `globals.css` (which imports ui-kit theme)
+
+### 2. @policyengine/ui-kit (component library + theme)
+
+The application MUST install `@policyengine/ui-kit` and use it as the primary component library and design token source. **MUST use ui-kit components when an equivalent exists** — do NOT rebuild components that ui-kit already provides.
+
+- MUST install: `bun add @policyengine/ui-kit`
+- MUST import theme in `globals.css`: `@import "@policyengine/ui-kit/theme.css";`
+- MUST use ui-kit components for all standard UI patterns (see availability table below)
+- MAY build custom components only when no ui-kit equivalent exists
+
+**Component availability table:**
+
+| Dashboard need | ui-kit component |
+|---|---|
+| Page shell | `DashboardShell` |
+| Header with logo + nav | `Header` (light/dark variants, `navLinks` prop) |
+| Two-column layout | `SidebarLayout` + `InputPanel` + `ResultsPanel` |
+| Single-column narrative | `SingleColumnLayout` |
+| Buttons | `Button` (4 variants, 3 sizes) |
+| Cards | `Card`, `CardHeader`, `CardTitle`, `CardContent`, `CardFooter` |
+| Badges | `Badge` (6 variants) |
+| Tab navigation | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
+| Currency input | `CurrencyInput` |
+| Number input | `NumberInput` |
+| Select dropdown | `SelectInput` |
+| Checkbox | `CheckboxInput` |
+| Slider | `SliderInput` |
+| Input grouping | `InputGroup` |
+| KPI display | `MetricCard` (currency/percent, trends) |
+| Summary text | `SummaryText` |
+| Data tables | `DataTable` |
+| Charts | `ChartContainer`, `PEBarChart`, `PELineChart`, `PEAreaChart`, `PEWaterfallChart` |
+| Branding | `PolicyEngineWatermark`, `logos.*` |
+| Utilities | `formatCurrency`, `formatPercent`, `formatNumber` |
+
+**Component precedence rule:** When building UI:
+1. **First**: Use `@policyengine/ui-kit` if it has the component
+2. **Second**: Use [shadcn/ui](https://ui.shadcn.com) primitives (Dialog, Popover, Tooltip, Select, DropdownMenu, etc.) styled with Tailwind semantic classes
+3. **Third**: Build custom from scratch with Tailwind utility classes
+
+### 3. Design tokens via ui-kit theme
+
+The application MUST load design tokens from `@policyengine/ui-kit/theme.css`. This single CSS import provides all colors, spacing, typography, and chart tokens.
+
+- MUST import theme in `globals.css`: `@import "@policyengine/ui-kit/theme.css";`
+- MUST NOT load tokens via CDN `` — the theme is bundled with ui-kit
+- MUST NOT hardcode hex color values when a design token exists
+- MUST NOT hardcode pixel spacing values when a Tailwind spacing class exists
+- MUST NOT hardcode font-family values — use `var(--font-sans)`
+- MAY use custom values when no token covers the need (e.g., chart-specific dimensions, animation durations)
+
+**Token usage patterns:**
+
+| Context | Approach | Example |
+|---------|----------|---------|
+| React components | Tailwind semantic classes | `className="bg-primary text-foreground"` |
+| Brand palette | Tailwind direct classes | `className="bg-teal-500 text-gray-600"` |
+| Recharts (SVG) | CSS vars directly in fill/stroke | `fill="var(--chart-1)"` |
+| Inline styles | CSS vars | `style={{ color: "var(--primary)" }}` |
+
+### 4. Framework: Next.js (App Router)
+
+The application MUST use **Next.js with the App Router**.
+
+- MUST use `create-next-app` or equivalent to scaffold with App Router
+- MUST have `next.config.ts` at the project root
+- MUST have an `app/` directory with `layout.tsx` and `page.tsx`
+- MUST use TypeScript (`.ts`/`.tsx` files, `tsconfig.json`)
+- MUST NOT use the Pages Router (`pages/` directory)
+- MUST NOT use Vite as the application bundler (Vite is only used by Vitest for testing)
+- MUST NOT use other bundlers (Webpack, Parcel, esbuild, etc.)
+- MUST NOT use other meta-frameworks (Remix, Gatsby, Astro, etc.)
+
+### 5. Package manager: bun
+
+The application MUST use **bun** as the package manager.
+
+- MUST use `bun install` instead of `npm install`
+- MUST use `bun run dev`, `bun run build` instead of `npm run dev`, `npm run build`
+- MUST use `bunx vitest run` instead of `npx vitest run`
+- MUST have a `bun.lock` lockfile (not `package-lock.json`)
+- MUST NOT use npm, yarn, or pnpm
+
+### 6. Vercel deployment
+
+The application MUST be deployed using **Vercel**.
+
+- MUST have a `vercel.json` at the project root with appropriate configuration
+- MUST use `output: 'export'` in `next.config.ts` for static export, unless the dashboard requires server-side rendering
+- MUST configure the Vercel project to build from the repository root (not a subdirectory)
+- MUST set any required environment variables in the Vercel project settings using the `NEXT_PUBLIC_*` prefix
+- MUST deploy under the `policy-engine` Vercel scope
+- MUST NOT deploy using other hosting platforms (Netlify, AWS Amplify, GitHub Pages, etc.) for the frontend
+
+### 7. shadcn/ui for custom components
+
+When building custom components not available in `@policyengine/ui-kit`, the application SHOULD use [shadcn/ui](https://ui.shadcn.com) primitives as the base layer.
+
+- SHOULD initialize shadcn/ui: `bunx shadcn@latest init`
+- SHOULD use shadcn/ui for: Dialog, Popover, Tooltip, Select, DropdownMenu, Accordion, Sheet, and other interaction primitives
+- MUST style shadcn/ui components with Tailwind semantic classes (the ui-kit theme already defines shadcn/ui semantic tokens like `background`, `foreground`, `primary`, `muted`)
+- MUST NOT use shadcn/ui when an equivalent `@policyengine/ui-kit` component exists
+
+## Tailwind v4 + ui-kit theme integration pattern
+
+### globals.css
+
+```css
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+
+body {
+ font-family: var(--font-sans);
+ color: var(--foreground);
+ background: var(--background);
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+```
+
+The single `@import "@policyengine/ui-kit/theme.css"` provides:
+1. **`:root` variables** — shadcn/ui semantic tokens (`--primary`, `--background`, `--chart-1`, etc.)
+2. **`@theme inline`** — Bridges `:root` vars to Tailwind utilities (`bg-primary`, `text-foreground`)
+3. **`@theme`** — Brand palette (`bg-teal-500`, `text-gray-600`), font sizes, spacing, breakpoints
+
+### Next.js: app/layout.tsx
+
+```tsx
+import './globals.css'
+import { Inter } from 'next/font/google'
+import type { Metadata } from 'next'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export const metadata: Metadata = {
+ title: 'DASHBOARD_TITLE - PolicyEngine',
+ description: 'DASHBOARD_DESCRIPTION',
+ icons: { icon: '/favicon.svg' },
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ )
+}
+```
+
+### Usage in components
+
+```tsx
+// Prefer ui-kit components:
+import { MetricCard, Button, Card, CardContent } from '@policyengine/ui-kit';
+import { formatCurrency } from '@policyengine/ui-kit';
+
+// Use Tailwind classes with semantic and brand tokens for custom layouts:
+
+
+
+// Recharts uses CSS vars directly:
+ {
+ const res = await fetch(`${API_URL}/submit/${endpoint}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
- return res.json();
+ if (!res.ok) throw new Error(`Submit failed: ${res.status}`);
+ const data = await res.json();
+ return data.job_id;
+}
+
+export async function pollStatus(jobId: string) {
+ const res = await fetch(`${API_URL}/status/${jobId}`);
+ if (!res.ok) throw new Error(`Status check failed: ${res.status}`);
+ return res.json(); // { status: "computing" | "ok" | "error", result?, message? }
}
```
+#### React Query polling hook
+
+```typescript
+import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { submitJob, pollStatus } from "../api/client";
+
+export function useAsyncCalculation(queryKey: unknown[], endpoint: string, params: unknown, enabled = true) {
+ const [jobId, setJobId] = useState(null);
+
+ // Step 1: Submit job when params change
+ const submit = useQuery({
+ queryKey: [...queryKey, "submit"],
+ queryFn: async () => {
+ const id = await submitJob(endpoint, params);
+ setJobId(id);
+ return id;
+ },
+ enabled,
+ });
+
+ // Step 2: Poll for results
+ const poll = useQuery({
+ queryKey: [...queryKey, "poll", jobId],
+ queryFn: () => pollStatus(jobId!),
+ enabled: !!jobId,
+ refetchInterval: (query) =>
+ query.state.data?.status === "computing" ? 2000 : false,
+ });
+
+ return {
+ isLoading: submit.isLoading || (!!jobId && poll.isLoading),
+ isComputing: poll.data?.status === "computing",
+ isError: submit.isError || poll.data?.status === "error",
+ data: poll.data?.status === "ok" ? poll.data.result : undefined,
+ error: poll.data?.message || submit.error?.message,
+ };
+}
+```
+
+**Deploy:**
+```bash
+# Deploy the worker functions first (includes image snapshot — first build takes ~5 min)
+unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET
+modal deploy backend/app.py
+
+# Deploy the gateway
+modal deploy backend/modal_app.py
+```
+
+**URL pattern:** `https://policyengine--my-tool-fastapi-app.modal.run`
+
**Set Vercel env var:**
```bash
vercel env add NEXT_PUBLIC_API_URL production
-# Enter: https://policyengine--my-tool-calculate.modal.run
+# Enter: https://policyengine--my-tool-fastapi-app.modal.run
vercel --prod --force --yes --scope policy-engine
```
-**Pros:** Full control over calculations, can use any policyengine variables/reforms, can do microsimulation. **Cons:** Cold starts (5-15s first call), Modal costs, must pin policyengine version, must redeploy when policy rules update.
+**Pros:** Full control over calculations, can use any policyengine variables/reforms, can do microsimulation, no timeout issues. **Cons:** Fast cold starts (~2s thanks to model pre-loading via `.run_function()`; without snapshot, cold starts take 3-5 minutes), Modal costs, must pin policyengine version, must redeploy when policy rules update, more complex architecture (four files).
**Failure mode:** Modal apps can silently disappear. If frontend gets network errors, `curl` the Modal URL — if 404, redeploy.
+#### Modal timeout reference
+
+| Context | Default timeout | Max timeout | Notes |
+|---------|----------------|-------------|-------|
+| `@app.function(timeout=...)` | 300s | 86,400s (24h) | Set per-function |
+| `modal serve` dev gateway | ~150s | Not configurable | Returns HTTP 303 on timeout |
+| `modal deploy` prod gateway | ~150s | Not configurable | Returns HTTP 303 on timeout |
+
+**US statewide microsimulations take 2-5+ minutes.** This exceeds the gateway timeout, which is why synchronous HTTP calls fail for microsimulation endpoints. The gateway + polling architecture avoids this by using non-blocking job submission. Household-level simulations typically complete in 10-40s, within the gateway timeout, but polling is still recommended for consistency.
+
### Pattern D: Precomputed CSV dashboard
For analysis repos that precompute data with Python microsimulation pipelines:
@@ -240,7 +433,7 @@ For analysis repos that precompute data with Python microsimulation pipelines:
```bash
bunx create-next-app@14 my-tool --js --app --tailwind --eslint --no-src-dir --import-alias "@/*"
cd my-tool
-bun add @policyengine/design-system recharts
+bun add @policyengine/ui-kit recharts
bun add -D vitest
```
@@ -258,10 +451,6 @@ export default function RootLayout({ children }) {
return (
-
` in ``. The `@import` from `node_modules` does not work with the Next.js CSS pipeline.
-
-### app/globals.css — map PE tokens into Tailwind `@theme`
+### app/globals.css — import ui-kit theme
```css
@import "tailwindcss";
-
-@theme {
- --color-pe-primary-50: var(--pe-color-primary-50);
- --color-pe-primary-500: var(--pe-color-primary-500);
- --color-pe-primary-600: var(--pe-color-primary-600);
- --color-pe-primary-700: var(--pe-color-primary-700);
-
- --color-pe-gray-50: var(--pe-color-gray-50);
- --color-pe-gray-100: var(--pe-color-gray-100);
- --color-pe-gray-200: var(--pe-color-gray-200);
-
- --color-pe-error: var(--pe-color-error);
-
- --color-pe-bg-primary: var(--pe-color-bg-primary);
- --color-pe-text-primary: var(--pe-color-text-primary);
- --color-pe-text-secondary: var(--pe-color-text-secondary);
- --color-pe-text-tertiary: var(--pe-color-text-tertiary);
-
- --color-pe-border-light: var(--pe-color-border-light);
-}
+@import "@policyengine/ui-kit/theme.css";
body {
- font-family: var(--pe-font-family-primary);
- color: var(--pe-color-text-primary);
- background: var(--pe-color-bg-primary);
+ font-family: var(--font-sans);
+ color: var(--foreground);
+ background: var(--background);
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
```
-### Using PE tokens in components
+The single `@import "@policyengine/ui-kit/theme.css"` replaces the entire manual `@theme` block. It provides all color, spacing, and typography tokens as CSS variables that Tailwind 4 picks up automatically.
+
+### Using tokens in components
-Use `style=` with `var()` for dynamic PE token values:
+Use Tailwind classes from the ui-kit theme:
```jsx
-
+ Metric title
+ {formatCurrency(1234)}
+
+
+// Brand colors when needed:
+Primary teal
+
+// Responsive design uses Tailwind breakpoint prefixes:
+
+ {/* sidebar collapses at md breakpoint */}
+
+
+
```
-Or use Tailwind classes that reference the `@theme` mappings:
+Or use `style=` with `var()` for inline styles:
```jsx
-
+
```
## Embedding in policyengine.org
@@ -429,36 +599,22 @@ bun add recharts
**For simple visualizations:** Use SVG directly. The marriage calculator uses hand-rolled SVG heatmaps.
**Color conventions:**
-- Positive/bonus: `var(--pe-color-primary-500)`
-- Negative/penalty: `var(--pe-color-gray-600)` or `var(--pe-color-error)`
-- Neutral: `var(--pe-color-gray-200)`
+- Positive/bonus: `var(--chart-1)`
+- Negative/penalty: `var(--chart-3)` or `var(--destructive)`
+- Neutral: `var(--border)`
**Inverted metrics (taxes):** When positive delta means bad (more taxes), pass `invertDelta` to your chart component to flip labels and colors.
-### Recharts + PE tokens
+### Recharts + ui-kit tokens
-Recharts renders SVG, which **cannot inherit CSS custom properties** via `style=`. You must resolve token values at render time:
+Recharts accepts CSS variables directly via `fill` and `stroke` props:
```jsx
-/* Helper to read PE tokens for Recharts SVG props */
-function getCssVar(name) {
- if (typeof window === "undefined") return "";
- return getComputedStyle(document.documentElement)
- .getPropertyValue(name)
- .trim();
-}
-
-// In your chart component:
-const primaryColor = getCssVar("--pe-color-primary-500");
-const errorColor = getCssVar("--pe-color-error");
-const gridColor = getCssVar("--pe-color-border-light");
-const fontFamily = getCssVar("--pe-font-family-primary");
-
-
```
@@ -471,7 +627,7 @@ const fontFamily = getCssVar("--pe-font-family-primary");
tickFormatter={(v) => v < 0 ? `-$${Math.abs(v)}` : `$${v}`}
```
-**Never pass hardcoded hex values** like `fill="#319795"` to Recharts — always resolve from CSS variables.
+**Never pass hardcoded hex values** like `fill="#319795"` to Recharts — always use CSS variables (e.g., `fill="var(--chart-1)"`).
## Code highlighting
@@ -513,12 +669,12 @@ Test API responses against Python fixtures for numerical accuracy. See `PolicyEn
## Checklist for new tools
- [ ] Next.js 14 + Tailwind 4 scaffold
-- [ ] `@policyengine/design-system` tokens loaded via CDN `` in layout.jsx
-- [ ] PE tokens mapped in `globals.css` `@theme` block
+- [ ] `@policyengine/ui-kit` installed (`bun add @policyengine/ui-kit`)
+- [ ] `@import "@policyengine/ui-kit/theme.css"` in `globals.css`
- [ ] Inter font loaded via Google Fonts CDN
-- [ ] **Zero hardcoded hex colors** — all colors via `var(--pe-color-*)`
-- [ ] **Zero hardcoded font names** — all fonts via `var(--pe-font-family-primary)`
-- [ ] Recharts charts use `getCssVar()` helper for SVG props (font, colors)
+- [ ] **Use Tailwind classes from ui-kit theme** — no hardcoded hex colors
+- [ ] **Zero hardcoded font names** — all fonts via `var(--font-sans)`
+- [ ] Recharts charts use `fill="var(--chart-1)"` pattern for SVG props (font, colors)
- [ ] Recharts axes use `niceTicks` with `domain={["auto", "auto"]}` for human-friendly tick values
- [ ] Negative dollar values formatted as `-$100` not `$-100`
- [ ] PE logo is an actual image, not styled text
diff --git a/skills/tools-and-apis/policyengine-modal-deployment-skill/SKILL.md b/skills/tools-and-apis/policyengine-modal-deployment-skill/SKILL.md
new file mode 100644
index 0000000..2208326
--- /dev/null
+++ b/skills/tools-and-apis/policyengine-modal-deployment-skill/SKILL.md
@@ -0,0 +1,320 @@
+---
+name: policyengine-modal-deployment
+description: Deploying PolicyEngine backend APIs to Modal — workspace setup, authentication, deployment commands, environments, and troubleshooting
+---
+
+# PolicyEngine Modal deployment
+
+How to deploy PolicyEngine backend APIs (custom Modal backends for dashboards and interactive tools) to Modal under the PolicyEngine organizational workspace.
+
+**This skill applies only when a dashboard or tool uses the `custom-backend` data pattern.** If the project uses `api-v2-alpha` (stub data or direct API calls), no Modal deployment is needed.
+
+## Workspace
+
+PolicyEngine uses a shared Modal workspace called `policyengine`. All backend deployments MUST target this workspace — never a personal workspace.
+
+### Environments
+
+The `policyengine` workspace has three environments:
+
+| Environment | Web suffix | URL pattern | Purpose |
+|-------------|-----------|-------------|---------|
+| `main` | _(empty)_ | `policyengine---.modal.run` | Production |
+| `staging` | `staging` | `policyengine-staging---.modal.run` | Pre-production testing |
+| `testing` | `testing` | `policyengine-testing---.modal.run` | Development/CI |
+
+Default to `main` for production deployments.
+
+## Authentication
+
+### Prerequisites
+
+1. A Modal account linked to the PolicyEngine workspace (ask a workspace owner for an invite)
+2. The Modal CLI installed: `pip install modal`
+3. A token for the `policyengine` workspace stored in a local profile
+
+### Setting up authentication
+
+```bash
+# Create a token for the policyengine workspace (opens browser)
+modal token new --profile policyengine
+
+# Activate the profile
+modal profile activate policyengine
+
+# Verify — must show "Workspace: policyengine"
+modal token info
+```
+
+### Verifying authentication before deploy
+
+**HUMAN GATE:** Before any deployment, verify the active workspace:
+
+```bash
+modal token info
+modal profile list
+```
+
+Expected output from `modal profile list`:
+```
+┏━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
+┃ ┃ Profile ┃ Workspace ┃
+┡━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
+│ • │ policyengine │ policyengine │
+└───┴──────────────┴──────────────┘
+```
+
+The `•` indicates the active profile. If `policyengine` is not active or not present:
+
+> **Authentication required.** Your Modal CLI is not configured for the `policyengine` workspace.
+>
+> Run:
+> ```bash
+> modal token new --profile policyengine
+> modal profile activate policyengine
+> ```
+>
+> If you don't have access to the PolicyEngine workspace, ask a workspace owner to invite you at https://modal.com/settings/policyengine
+
+**Do NOT proceed with deployment until `modal token info` shows `Workspace: policyengine`.**
+
+### Critical: environment variable override
+
+Modal CLI respects `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` environment variables, which **override** the profile. If these are set (e.g., from a CI environment), the CLI will deploy to whatever workspace those tokens belong to — potentially a personal workspace.
+
+**Always unset before deploying:**
+```bash
+unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET
+```
+
+## App structure
+
+### Naming convention
+
+The Modal app name MUST match the dashboard/tool repo name in kebab-case:
+
+```python
+app = modal.App("my-dashboard-name")
+```
+
+This keeps the app name consistent with the GitHub repo and Vercel project.
+
+### Image and dependencies
+
+Build a container image with the required Python packages:
+
+```python
+image = (
+ modal.Image.debian_slim(python_version="3.12")
+ .pip_install(
+ "policyengine-us>=1.155.0", # Pin minimum version
+ "fastapi[standard]",
+ "numpy",
+ "pandas",
+ )
+ .env({"NUMEXPR_MAX_THREADS": "4"})
+ .add_local_dir("api", "/root/api") # Local source code
+ .add_local_file("config.yaml", "/root/config.yaml") # Config files
+)
+```
+
+**Guidelines:**
+- Use `debian_slim` with Python 3.12 or 3.13
+- Pin minimum versions for `policyengine-us` / `policyengine-uk`
+- Use `.add_local_dir()` / `.add_local_file()` for project source code
+- Use `.env()` for non-secret environment variables
+- Set memory and timeout on the function, not the image
+
+### Web endpoint patterns
+
+#### Simple endpoint (single function)
+
+For tools with one calculation endpoint:
+
+```python
+@app.function(image=image, timeout=300, memory=2048)
+@modal.web_endpoint(method="POST")
+def calculate(data: dict) -> dict:
+ from policyengine_us import Simulation
+ # Build simulation from data, return results
+ return {"result": value}
+```
+
+URL: `https://policyengine---calculate.modal.run`
+
+#### Full FastAPI app (multiple endpoints)
+
+For dashboards with multiple API routes:
+
+```python
+@app.function(image=image, timeout=300, memory=2048)
+@modal.concurrent(max_inputs=100)
+@modal.asgi_app()
+def fastapi_app():
+ from api.main import app as api
+ return api
+```
+
+URL: `https://policyengine---fastapi-app.modal.run`
+
+#### Health check endpoint
+
+Every Modal backend SHOULD include a health check:
+
+```python
+@app.function(image=image)
+@modal.web_endpoint(method="GET")
+def health():
+ return {"status": "ok"}
+```
+
+### Function configuration
+
+| Parameter | Default | Recommended for PE | Purpose |
+|-----------|---------|-------------------|---------|
+| `timeout` | 60s | 300 | PolicyEngine simulations can take minutes |
+| `memory` | 128MB | 2048 | PE models are memory-intensive |
+| `@modal.concurrent(max_inputs=N)` | 1 | 100 | Handle concurrent requests without cold starts |
+
+### Secrets
+
+Store sensitive values as Modal Secrets (not in code or `.env` files):
+
+```bash
+# Create a secret
+modal secret create my-secret API_KEY=abc123
+
+# List secrets
+modal secret list
+```
+
+Reference in code:
+```python
+@app.function(
+ image=image,
+ secrets=[modal.Secret.from_name("my-secret")],
+)
+def my_function():
+ import os
+ api_key = os.environ["API_KEY"] # Injected by Modal
+```
+
+Existing secrets in the `policyengine` workspace:
+- `policyengine-logfire` — logging/observability
+- `gcp-credentials` — Google Cloud access
+- `huggingface-token` — HuggingFace model access
+- `anthropic-api-key` — Anthropic API access
+
+## Deployment
+
+### Deploy command
+
+```bash
+# 1. Ensure correct workspace
+unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET
+modal token info # Verify "Workspace: policyengine"
+
+# 2. Deploy to production
+modal deploy modal_app.py --env main
+
+# 3. Deploy to staging (for testing)
+modal deploy modal_app.py --env staging
+```
+
+**Flags:**
+- `--env main` / `--env staging` / `--env testing` — target environment
+- `--name TEXT` — override the deployment name (rarely needed)
+- `--tag TEXT` — tag the deployment with a version string
+- `--stream-logs` — stream container logs during deployment
+
+### Verify deployment
+
+```bash
+# List deployed apps
+modal app list --env main
+
+# Health check
+curl -s -w "\n%{http_code}" https://policyengine--DASHBOARD_NAME-health.modal.run
+
+# Test the endpoint
+curl -X POST https://policyengine--DASHBOARD_NAME-calculate.modal.run \
+ -H "Content-Type: application/json" \
+ -d '{"test": true}'
+```
+
+### Connecting to Vercel frontend
+
+After Modal deployment, set the API URL as an environment variable in the Vercel project:
+
+```bash
+vercel env add NEXT_PUBLIC_API_URL production
+# Enter: https://policyengine--DASHBOARD_NAME-calculate.modal.run
+vercel --prod --force --yes --scope policy-engine
+```
+
+The `--force` flag is required to rebuild with the new environment variable.
+
+### Redeployment
+
+Redeploying an existing app is the same command — Modal handles zero-downtime transitions:
+1. New containers build while old ones handle requests
+2. New containers start accepting requests
+3. Old containers finish in-flight requests then terminate
+
+```bash
+modal deploy modal_app.py --env main
+```
+
+### Stopping an app
+
+**WARNING: This is destructive and irreversible.** A stopped app cannot be restarted; you must redeploy.
+
+```bash
+modal app stop
+```
+
+## Monitoring
+
+```bash
+# View logs for a deployed app
+modal app logs
+
+# List all apps and their status
+modal app list --env main
+```
+
+App states:
+- `deployed` — running and accepting requests
+- `ephemeral` — temporary (from `modal serve`)
+- `stopped` — permanently stopped
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `modal token info` shows wrong workspace | Wrong profile active | `modal profile activate policyengine` |
+| Deploy goes to personal workspace | `MODAL_TOKEN_ID` env var set | `unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET` |
+| 404 on endpoint URL | App stopped or never deployed | `modal deploy modal_app.py --env main` |
+| Cold start latency (5-15s) | No warm containers | Add `@modal.concurrent(max_inputs=100)` |
+| `MemoryError` during simulation | Container memory too low | Increase `memory=` (try 4096) |
+| Timeout error | Simulation exceeds limit | Increase `timeout=` (try 600) |
+| Python dependency conflict | Version mismatch | Pin exact versions in `.pip_install()` |
+| Missing local files in container | Forgot `.add_local_dir()` | Add source dirs to image definition |
+| Modal app silently disappeared | Unknown — can happen | `curl` the URL; if 404, redeploy |
+
+## What NOT to do
+
+- MUST NOT deploy to a personal workspace — always use the `policyengine` workspace
+- MUST NOT leave `MODAL_TOKEN_ID` / `MODAL_TOKEN_SECRET` env vars set when deploying via profile
+- MUST NOT use `modal run` for production deployments — use `modal deploy`
+- MUST NOT use `modal serve` for production — it creates ephemeral apps that stop when you close your terminal
+- MUST NOT skip health check verification after deployment
+- MUST NOT use generic app names — always match the dashboard/tool repo name
+- MUST NOT hardcode secrets in Python code — use Modal Secrets
+- MUST NOT deploy without confirming the target workspace with `modal token info`
+
+## Related skills
+
+- **policyengine-vercel-deployment-skill** — Frontend deployment to Vercel
+- **policyengine-interactive-tools-skill** — Pattern C (custom Modal API) for interactive tools
+- **policyengine-dashboard-workflow-skill** — Full dashboard creation workflow
diff --git a/skills/tools-and-apis/policyengine-vercel-deployment-skill/SKILL.md b/skills/tools-and-apis/policyengine-vercel-deployment-skill/SKILL.md
index 16ef0e1..c4484bb 100644
--- a/skills/tools-and-apis/policyengine-vercel-deployment-skill/SKILL.md
+++ b/skills/tools-and-apis/policyengine-vercel-deployment-skill/SKILL.md
@@ -53,14 +53,14 @@ vercel --prod --yes --scope policy-engine
For apps with API backends (e.g., Modal):
```bash
-# Set env var
-vercel env add VITE_API_URL production
+# Set env var (Next.js uses NEXT_PUBLIC_* prefix)
+vercel env add NEXT_PUBLIC_API_URL production
# Must force-redeploy after changing env vars
vercel --prod --force --yes --scope policy-engine
```
-Vite apps access env vars via `import.meta.env.VITE_API_URL`.
+Next.js apps access env vars via `process.env.NEXT_PUBLIC_API_URL`.
### Verify deployment
@@ -82,13 +82,9 @@ vercel --prod --yes
**Generic project names:** Never use generic names like `app` or `site` — they can steal domains from other projects. Always use descriptive names.
-### Vite base path
+### vercel.json
-For Vercel, always use `base: "/"` in vite.config.js (unlike GitHub Pages which needs a subpath).
-
-### vercel.json (optional)
-
-Must be at repo root. For SPAs:
+Must be at repo root. For Next.js static exports, configure rewrites as needed:
```json
{
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]