diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 000000000..a985f0c06
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,5 @@
+{
+ "enabledPlugins": {
+ "pr-review-toolkit@claude-plugins-official": true
+ }
+}
diff --git a/.claude/skills/chart-standards.md b/.claude/skills/chart-standards.md
new file mode 100644
index 000000000..13fb3b638
--- /dev/null
+++ b/.claude/skills/chart-standards.md
@@ -0,0 +1,316 @@
+# Chart and Visualization Standards
+
+This skill ensures consistent chart styling across PolicyEngine visualizations using Plotly.js via `react-plotly.js`.
+
+## Required Imports
+
+```tsx
+import type { Layout } from 'plotly.js';
+import Plot from 'react-plotly.js';
+import { colors } from '@/designTokens/colors';
+import { spacing } from '@/designTokens/spacing';
+import { ChartContainer } from '@/components/ChartContainer';
+import { DEFAULT_CHART_CONFIG, getClampedChartHeight } from '@/utils/chartUtils';
+```
+
+## Chart Container Pattern
+
+Always wrap charts in `ChartContainer` for consistent styling:
+
+```tsx
+
+
+
+ {description}
+
+
+```
+
+## Color Semantics
+
+### Bar/Data Colors
+| Scenario | Color Token | Hex |
+|----------|-------------|-----|
+| Positive change (gains, winners) | `colors.primary[500]` | `#319795` (teal) |
+| Negative change (losses, losers) | `colors.gray[600]` | `#4B5563` |
+| Neutral/baseline | `colors.gray[300]` | `#D1D5DB` |
+| Error/warning states | `colors.error` | `#EF4444` |
+| Success states | `colors.success` | `#22C55E` |
+
+### Dynamic Color Assignment
+```tsx
+marker: {
+ color: yArray.map((value) => (value < 0 ? colors.gray[600] : colors.primary[500])),
+}
+```
+
+### Multi-Series Colors
+Use the design system's series palette:
+```tsx
+import { chartColors } from '@policyengine/design-system/charts';
+
+// Series order: teal, blue, dark teal, dark blue, gray
+chartColors.series[0] // Primary teal
+chartColors.series[1] // Blue accent
+chartColors.series[2] // Dark teal
+chartColors.series[3] // Dark blue
+chartColors.series[4] // Gray
+```
+
+## Chart Configuration
+
+### Default Config (Always Use)
+```tsx
+import { DEFAULT_CHART_CONFIG } from '@/utils/chartUtils';
+
+config={{
+ ...DEFAULT_CHART_CONFIG,
+ locale: localeCode(countryId), // For currency/number formatting
+}}
+```
+
+This provides:
+- `displayModeBar: false` - Hides Plotly toolbar
+- `responsive: true` - Enables responsive sizing
+
+### Responsive Height
+```tsx
+import { useMediaQuery, useViewportSize } from '@mantine/hooks';
+import { getClampedChartHeight } from '@/utils/chartUtils';
+
+const mobile = useMediaQuery('(max-width: 768px)');
+const { height: viewportHeight } = useViewportSize();
+const chartHeight = getClampedChartHeight(viewportHeight, mobile);
+
+// Use in style
+style={{ width: '100%', height: chartHeight }}
+```
+
+## Standard Layout Properties
+
+### Base Layout
+```tsx
+const layout = {
+ xaxis: {
+ title: { text: 'X Axis Label' },
+ fixedrange: true, // Disable zoom/pan
+ },
+ yaxis: {
+ title: { text: 'Y Axis Label' },
+ tickprefix: currencySymbol(countryId), // For currency
+ tickformat: ',.0f', // Number format
+ fixedrange: true,
+ },
+ showlegend: false, // Or configure legend position
+ margin: {
+ t: 0, // Top (usually 0, title is outside chart)
+ b: 80, // Bottom (for x-axis labels)
+ l: 60, // Left (for y-axis labels)
+ r: 20, // Right
+ },
+} as Partial;
+```
+
+### Text on Bars (Uniform Text)
+```tsx
+uniformtext: {
+ mode: 'hide' as const, // Hide text that doesn't fit
+ minsize: mobile ? 4 : 8,
+},
+```
+
+### Legend Position (When Needed)
+```tsx
+legend: {
+ orientation: 'h',
+ yanchor: 'bottom',
+ y: 1.02,
+ xanchor: 'right',
+ x: 1,
+},
+```
+
+## Hover Templates
+
+Use custom hover templates for rich tooltips:
+
+```tsx
+{
+ customdata: xArray.map((x, i) => hoverMessage(x, yArray[i])),
+ hovertemplate: 'Decile %{x}
%{customdata}',
+}
+```
+
+The `` hides the trace name box.
+
+## Chart Title Pattern
+
+Generate dynamic titles that describe the reform's impact:
+
+```tsx
+const getChartTitle = () => {
+ const change = calculateChange();
+ const signTerm = change > 0 ? 'increase' : 'decrease';
+
+ if (change === 0) {
+ return `This reform would have no effect on ${metric}`;
+ }
+ return `This reform would ${signTerm} ${metric} by ${formatValue(change)}`;
+};
+```
+
+## CSV Export Pattern
+
+Always provide CSV download functionality:
+
+```tsx
+import { downloadCsv } from '@/utils/chartUtils';
+
+const handleDownloadCsv = () => {
+ const csvData = Object.entries(dataObject).map(([key, value]) => [
+ `Label ${key}`,
+ value.toString(),
+ ]);
+ downloadCsv(csvData, 'descriptive-filename.csv');
+};
+```
+
+## Description Pattern
+
+Add explanatory text below charts:
+
+```tsx
+const description = (
+
+ PolicyEngine sorts households into ten equally-populated groups...
+
+);
+```
+
+## Complete Chart Component Template
+
+```tsx
+import type { Layout } from 'plotly.js';
+import Plot from 'react-plotly.js';
+import { Stack, Text } from '@mantine/core';
+import { useMediaQuery, useViewportSize } from '@mantine/hooks';
+import { ChartContainer } from '@/components/ChartContainer';
+import { colors } from '@/designTokens/colors';
+import { spacing } from '@/designTokens/spacing';
+import { DEFAULT_CHART_CONFIG, downloadCsv, getClampedChartHeight } from '@/utils/chartUtils';
+
+interface Props {
+ output: OutputType;
+}
+
+export default function ChartSubPage({ output }: Props) {
+ const mobile = useMediaQuery('(max-width: 768px)');
+ const countryId = useCurrentCountry();
+ const { height: viewportHeight } = useViewportSize();
+ const chartHeight = getClampedChartHeight(viewportHeight, mobile);
+
+ // Extract and prepare data
+ const xArray = Object.keys(output.data);
+ const yArray = Object.values(output.data);
+
+ // Generate title
+ const getChartTitle = () => {
+ // Dynamic title based on data
+ };
+
+ // CSV export
+ const handleDownloadCsv = () => {
+ const csvData = xArray.map((x, i) => [x, yArray[i].toString()]);
+ downloadCsv(csvData, 'chart-name.csv');
+ };
+
+ // Chart data
+ const chartData = [{
+ x: xArray,
+ y: yArray,
+ type: 'bar' as const,
+ marker: {
+ color: yArray.map((v) => (v < 0 ? colors.gray[600] : colors.primary[500])),
+ },
+ }];
+
+ // Layout
+ const layout = {
+ xaxis: { title: { text: 'X Label' }, fixedrange: true },
+ yaxis: { title: { text: 'Y Label' }, fixedrange: true },
+ showlegend: false,
+ margin: { t: 0, b: 80, l: 60, r: 20 },
+ } as Partial;
+
+ return (
+
+
+
+
+ Explanatory description...
+
+
+
+ );
+}
+```
+
+## Watermark (For Research/Blog Charts)
+
+When charts need PolicyEngine branding (research posts, exported images):
+
+```tsx
+import { chartLogo } from '@policyengine/design-system/charts';
+
+layout: {
+ images: [chartLogo],
+}
+```
+
+Logo source: `/assets/logos/policyengine/teal-square.png`
+
+## Anti-Patterns
+
+### Never Do This
+```tsx
+// WRONG - Hardcoded colors
+marker: { color: '#319795' }
+marker: { color: value > 0 ? 'green' : 'red' }
+
+// WRONG - Hardcoded dimensions
+style={{ height: 500 }}
+
+// WRONG - Missing config
+
+
+// WRONG - No container
+ // Charts should be in ChartContainer
+```
+
+### Always Do This
+```tsx
+// CORRECT - Token colors
+marker: { color: colors.primary[500] }
+marker: { color: value < 0 ? colors.gray[600] : colors.primary[500] }
+
+// CORRECT - Responsive height
+style={{ height: chartHeight }}
+
+// CORRECT - With config
+
+
+// CORRECT - With container
+
+
+
+```
diff --git a/.claude/skills/design-tokens.md b/.claude/skills/design-tokens.md
new file mode 100644
index 000000000..a033bb666
--- /dev/null
+++ b/.claude/skills/design-tokens.md
@@ -0,0 +1,216 @@
+# Design Token Enforcement
+
+This skill ensures consistent use of PolicyEngine's design system tokens. **Never use hardcoded colors, spacing, or typography values.**
+
+## Text Casing: SENTENCE CASE IS THE STANDARD
+
+**CRITICAL: Almost all text in the app must use sentence case.**
+
+Sentence case means: Capitalize only the first letter of the first word (and proper nouns).
+
+| Text Type | Correct | Wrong |
+|-----------|---------|-------|
+| Page titles | "Your saved policies" | "Your Saved Policies" |
+| Button labels | "New simulation" | "New Simulation" |
+| Column headers | "Date created" | "Date Created" |
+| Tab labels | "Budgetary impact" | "Budgetary Impact" |
+| Menu items | "Rename" | "RENAME" |
+| Descriptions | "Configure your household settings" | "Configure Your Household Settings" |
+| Chart titles | "This reform would increase income by $500" | "This Reform Would Increase Income By $500" |
+
+### Exceptions (Title Case or Special Casing Allowed)
+- **Proper nouns**: "PolicyEngine", "United States", "California"
+- **Acronyms**: "IRS", "UK", "API", "CSV"
+- **Official program names**: "Child Tax Credit", "Universal Credit"
+- **Table header row**: May use UPPERCASE with `textTransform: 'uppercase'` (this is a styling choice, not the actual text)
+
+### Examples
+```tsx
+// CORRECT - Sentence case
+title="Your saved simulations"
+subtitle="Build and save tax policy scenarios for quick access."
+buttonLabel="New household"
+header="Parameter changes"
+
+// WRONG - Title Case
+title="Your Saved Simulations"
+subtitle="Build And Save Tax Policy Scenarios For Quick Access."
+buttonLabel="New Household"
+header="Parameter Changes"
+```
+
+## Import Pattern
+
+Always import from `@/designTokens`:
+
+```tsx
+import { colors, spacing, typography } from '@/designTokens';
+```
+
+## Color Tokens
+
+### Brand Colors (Teal - Primary)
+| Token | Value | Use For |
+|-------|-------|---------|
+| `colors.primary[500]` | `#319795` | Main brand color, primary buttons, links |
+| `colors.primary[600]` | `#2C7A7B` | Hover states |
+| `colors.primary[700]` | `#285E61` | Active/pressed states |
+| `colors.primary[50]` | `#E6FFFA` | Light teal backgrounds |
+
+### Text Colors
+| Token | Use For |
+|-------|---------|
+| `colors.text.primary` | Main body text, headings |
+| `colors.text.secondary` | Helper text, descriptions, labels |
+| `colors.text.tertiary` | Disabled text, placeholders |
+| `colors.text.title` | Page titles (same as primary) |
+| `colors.text.inverse` | Text on dark backgrounds |
+
+### Semantic Colors
+| Token | Use For |
+|-------|---------|
+| `colors.success` (`#22C55E`) | Positive changes, gains, winners |
+| `colors.error` (`#EF4444`) | Negative changes, losses, errors |
+| `colors.warning` (`#FEC601`) | Warnings, cautions |
+| `colors.info` (`#1890FF`) | Informational highlights |
+
+### Background Colors
+| Token | Use For |
+|-------|---------|
+| `colors.background.primary` | Main content area (white) |
+| `colors.background.secondary` | Sidebar, secondary panels |
+| `colors.background.tertiary` | Tertiary backgrounds |
+| `colors.gray[50]` | Table headers, subtle backgrounds |
+| `colors.blue[50]` | Selected row highlights |
+
+### Border Colors
+| Token | Use For |
+|-------|---------|
+| `colors.border.light` | Standard borders, dividers |
+| `colors.border.medium` | Emphasized borders |
+| `colors.border.dark` | Strong contrast borders |
+
+## Spacing Tokens
+
+### Base Scale
+```tsx
+spacing.xs // 4px - Tight spacing (icon gaps)
+spacing.sm // 8px - Small gaps
+spacing.md // 12px - Medium gaps
+spacing.lg // 16px - Standard component gaps
+spacing.xl // 20px - Section gaps
+spacing['2xl'] // 24px - Large section gaps
+spacing['3xl'] // 32px - Major sections
+spacing['4xl'] // 48px - Page sections
+```
+
+### Border Radius
+```tsx
+spacing.radius.sm // 4px - Buttons, inputs
+spacing.radius.md // 6px - Cards, small panels
+spacing.radius.lg // 8px - Standard panels
+spacing.radius.xl // 12px - Large cards
+```
+
+## Typography Tokens
+
+### Font Families
+```tsx
+typography.fontFamily.primary // Inter - UI elements
+typography.fontFamily.body // Roboto - Body text
+typography.fontFamily.chart // Roboto Serif - Charts
+typography.fontFamily.mono // JetBrains Mono - Code
+```
+
+### Font Weights
+```tsx
+typography.fontWeight.normal // 400 - Body text
+typography.fontWeight.medium // 500 - Emphasized text
+typography.fontWeight.semibold // 600 - Subheadings
+typography.fontWeight.bold // 700 - Headings
+```
+
+### Font Sizes
+```tsx
+typography.fontSize.xs // 12px - Small labels
+typography.fontSize.sm // 14px - Body text
+typography.fontSize.base // 16px - Large body
+typography.fontSize.lg // 18px - Subheadings
+typography.fontSize.xl // 20px - Section titles
+typography.fontSize['2xl'] // 24px - Page titles
+```
+
+## Anti-Patterns to Avoid
+
+### Never Do This
+```tsx
+// WRONG - Hardcoded values
+
+
+
+```
+
+### Always Do This
+```tsx
+// CORRECT - Token usage
+
+
+
+```
+
+## Common Patterns
+
+### Page Title
+```tsx
+
+ {title}
+
+```
+
+### Subtitle/Description
+```tsx
+
+ {description}
+
+```
+
+### Card/Panel Container
+```tsx
+
+```
+
+### Table Header
+```tsx
+
+```
+
+### Selected State
+```tsx
+style={{
+ backgroundColor: selected ? colors.blue[50] : 'transparent',
+ borderLeft: selected
+ ? `3px solid ${colors.primary[500]}`
+ : '3px solid transparent',
+}}
+```
diff --git a/.claude/skills/ingredient-patterns.md b/.claude/skills/ingredient-patterns.md
new file mode 100644
index 000000000..d94c7360a
--- /dev/null
+++ b/.claude/skills/ingredient-patterns.md
@@ -0,0 +1,369 @@
+# Ingredient CRUD Patterns
+
+This skill documents the standard patterns for ingredient list pages (Policies, Reports, Simulations, Populations). All ingredient pages follow the same structure for consistency.
+
+## Page Structure Overview
+
+Every ingredient page has:
+1. **Data fetching** via React Query hooks
+2. **State management** for search, selection, and rename modal
+3. **Column configuration** defining table structure
+4. **Data transformation** from API types to `IngredientRecord[]`
+5. **`IngredientReadView` component** for rendering
+6. **`RenameIngredientModal`** for rename functionality
+
+## Required Imports
+
+```tsx
+import { useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Stack } from '@mantine/core';
+import { useDisclosure } from '@mantine/hooks';
+import { ColumnConfig, IngredientRecord, TextValue, BulletsValue } from '@/components/columns';
+import { RenameIngredientModal } from '@/components/common/RenameIngredientModal';
+import IngredientReadView from '@/components/IngredientReadView';
+import { MOCK_USER_ID } from '@/constants';
+import { useCurrentCountry } from '@/hooks/useCurrentCountry';
+import { formatDate } from '@/utils/dateUtils';
+```
+
+## Standard Page Template
+
+```tsx
+export default function [Ingredient]sPage() {
+ // 1. HOOKS
+ const userId = MOCK_USER_ID.toString();
+ const { data, isLoading, isError, error } = use[Ingredient]s(userId);
+ const navigate = useNavigate();
+ const countryId = useCurrentCountry();
+
+ // 2. STATE
+ const [searchValue, setSearchValue] = useState('');
+ const [selectedIds, setSelectedIds] = useState([]);
+
+ // 3. RENAME MODAL STATE
+ const [renamingId, setRenamingId] = useState(null);
+ const [renameOpened, { open: openRename, close: closeRename }] = useDisclosure(false);
+ const updateAssociation = useUpdate[Ingredient]Association();
+
+ // 4. HANDLERS
+ const handleBuild = () => navigate(`/${countryId}/[ingredients]/create`);
+
+ const handleSelectionChange = (recordId: string, selected: boolean) => {
+ setSelectedIds((prev) =>
+ selected ? [...prev, recordId] : prev.filter((id) => id !== recordId)
+ );
+ };
+
+ const isSelected = (recordId: string) => selectedIds.includes(recordId);
+
+ const handleOpenRename = (id: string) => {
+ setRenamingId(id);
+ openRename();
+ };
+
+ const handleCloseRename = () => {
+ closeRename();
+ setRenamingId(null);
+ };
+
+ const handleRename = async (newLabel: string) => {
+ if (!renamingId) return;
+ try {
+ await updateAssociation.mutateAsync({
+ user[Ingredient]Id: renamingId,
+ updates: { label: newLabel },
+ });
+ handleCloseRename();
+ } catch (error) {
+ console.error(`[${Ingredient}sPage] Failed to rename:`, error);
+ }
+ };
+
+ // 5. CURRENT LABEL FOR MODAL
+ const renamingItem = data?.find((item) => item.association.id === renamingId);
+ const currentLabel = renamingItem?.association.label || `[Ingredient] #${renamingItem?.association.[ingredient]Id}`;
+
+ // 6. COLUMN CONFIG
+ const columns: ColumnConfig[] = [
+ { key: 'name', header: '[Ingredient] name', type: 'text' },
+ { key: 'dateCreated', header: 'Date created', type: 'text' },
+ // ... additional columns
+ {
+ key: 'actions',
+ header: '',
+ type: 'menu',
+ actions: [{ label: 'Rename', action: 'rename' }],
+ onAction: (action: string, recordId: string) => {
+ if (action === 'rename') handleOpenRename(recordId);
+ },
+ },
+ ];
+
+ // 7. DATA TRANSFORMATION
+ const transformedData: IngredientRecord[] = data?.map((item) => ({
+ id: item.association.id?.toString() || item.association.[ingredient]Id.toString(),
+ name: { text: item.association.label || `[Ingredient] #${item.association.[ingredient]Id}` } as TextValue,
+ dateCreated: {
+ text: item.association.createdAt
+ ? formatDate(item.association.createdAt, 'short-month-day-year', item.association.countryId, true)
+ : '',
+ } as TextValue,
+ })) || [];
+
+ // 8. RENDER
+ return (
+ <>
+
+
+
+
+
+
+ );
+}
+```
+
+## Column Types
+
+### Text Column
+```tsx
+{
+ key: 'fieldName',
+ header: 'Column Header',
+ type: 'text',
+}
+
+// Data format:
+{ text: 'Display value' } as TextValue
+```
+
+### Link Column
+```tsx
+{
+ key: 'fieldName',
+ header: 'Column Header',
+ type: 'link',
+}
+
+// Data format:
+{ text: 'Link text', url: '/path/to/resource' } as LinkValue
+```
+
+### Bullets Column
+For multi-line details (e.g., simulation info, population details):
+```tsx
+{
+ key: 'details',
+ header: 'Details',
+ type: 'bullets',
+ items: [{ textKey: 'text', badgeKey: 'badge' }],
+}
+
+// Data format:
+{
+ items: [
+ { text: '3 persons', badge: '' },
+ { text: 'California', badge: '' },
+ ]
+} as BulletsValue
+```
+
+### Menu Column (Actions)
+```tsx
+{
+ key: 'actions',
+ header: '',
+ type: 'menu',
+ actions: [
+ { label: 'Rename', action: 'rename' },
+ { label: 'Delete', action: 'delete', color: 'red' },
+ ],
+ onAction: (action: string, recordId: string) => {
+ if (action === 'rename') handleOpenRename(recordId);
+ if (action === 'delete') handleDelete(recordId);
+ },
+}
+```
+
+## Data Transformation Patterns
+
+### Basic Transformation
+```tsx
+const transformedData: IngredientRecord[] = data?.map((item) => ({
+ id: item.association.id?.toString() || item.association.policyId.toString(),
+ policyName: {
+ text: item.association.label || `Policy #${item.association.policyId}`,
+ } as TextValue,
+ dateCreated: {
+ text: item.association.createdAt
+ ? formatDate(item.association.createdAt, 'short-month-day-year', item.association.countryId, true)
+ : '',
+ } as TextValue,
+})) || [];
+```
+
+### With Computed Values
+```tsx
+const transformedData: IngredientRecord[] = data?.map((item) => {
+ const paramCount = countPolicyModifications(item.policy);
+
+ return {
+ id: item.association.id?.toString(),
+ // ...
+ provisions: {
+ text: `${paramCount} parameter change${paramCount !== 1 ? 's' : ''}`,
+ } as TextValue,
+ };
+}) || [];
+```
+
+### Combining Multiple Data Sources
+```tsx
+// For pages like Populations that combine households + geographies
+const householdRecords: IngredientRecord[] = householdData?.map(/* ... */) || [];
+const geographicRecords: IngredientRecord[] = geographicData?.map(/* ... */) || [];
+const transformedData = [...householdRecords, ...geographicRecords];
+```
+
+## Rename Modal Integration
+
+### Modal State Pattern
+```tsx
+const [renamingId, setRenamingId] = useState(null);
+const [renameOpened, { open: openRename, close: closeRename }] = useDisclosure(false);
+```
+
+### Opening the Modal
+```tsx
+const handleOpenRename = (userAssociationId: string) => {
+ setRenamingId(userAssociationId);
+ openRename();
+};
+```
+
+### Handling Rename
+```tsx
+const handleRename = async (newLabel: string) => {
+ if (!renamingId) return;
+
+ try {
+ await updateAssociation.mutateAsync({
+ userPolicyId: renamingId, // Use correct ID field
+ updates: { label: newLabel },
+ });
+ handleCloseRename();
+ } catch (error) {
+ console.error('[PoliciesPage] Failed to rename policy:', error);
+ }
+};
+```
+
+### Getting Current Label
+```tsx
+const renamingItem = data?.find((item) => item.association.id === renamingId);
+const currentLabel = renamingItem?.association.label || `Policy #${renamingItem?.association.policyId}`;
+```
+
+## IngredientReadView Props
+
+```tsx
+interface IngredientReadViewProps {
+ ingredient: string; // Singular name for button text
+ title: string; // Page title
+ subtitle?: string; // Description text
+ buttonLabel?: string; // Custom button label (default: "New {ingredient}")
+ onBuild?: () => void; // Handler for create button
+ isLoading: boolean; // Show loading state
+ isError: boolean; // Show error state
+ error?: unknown; // Error object for message
+ data: IngredientRecord[]; // Transformed data
+ columns: ColumnConfig[]; // Column definitions
+ searchValue?: string; // Current search value
+ onSearchChange?: (value: string) => void;
+ enableSelection?: boolean; // Enable row selection
+ isSelected?: (recordId: string) => boolean;
+ onSelectionChange?: (recordId: string, selected: boolean) => void;
+}
+```
+
+## Error Logging Convention
+
+Always prefix console errors with the component name:
+```tsx
+console.error('[PoliciesPage] Failed to rename policy:', error);
+console.error('[ReportsPage] Failed to rename report:', error);
+console.error('[SimulationsPage] Failed to rename simulation:', error);
+```
+
+## Existing Ingredient Pages
+
+| Page | Ingredients | Special Features |
+|------|-------------|------------------|
+| `Policies.page.tsx` | Policies | Parameter change count |
+| `Reports.page.tsx` | Reports | Status cell, simulations list (bullets), link column |
+| `Simulations.page.tsx` | Simulations | Policy + Population text columns |
+| `Populations.page.tsx` | Households + Geographies | Combined data sources, bullets for details |
+
+## Anti-Patterns
+
+### Don't
+```tsx
+// WRONG - Direct mutation without try/catch
+const handleRename = async (newLabel: string) => {
+ await updateAssociation.mutateAsync({ ... }); // No error handling
+};
+
+// WRONG - Hardcoded user ID
+const userId = '1';
+
+// WRONG - Missing null check
+const currentLabel = data.find(...).association.label; // May crash
+
+// WRONG - Inconsistent ID usage
+id: item.policyId // Should use association.id when available
+```
+
+### Do
+```tsx
+// CORRECT - Error handling with logging
+const handleRename = async (newLabel: string) => {
+ try {
+ await updateAssociation.mutateAsync({ ... });
+ handleCloseRename();
+ } catch (error) {
+ console.error('[PageName] Failed to rename:', error);
+ }
+};
+
+// CORRECT - Use mock constant
+const userId = MOCK_USER_ID.toString();
+
+// CORRECT - Null-safe access
+const currentLabel = renamingItem?.association.label || `Policy #${renamingItem?.association.policyId}`;
+
+// CORRECT - Prefer user association ID, fallback to base ID
+id: item.association.id?.toString() || item.association.policyId.toString()
+```
diff --git a/CLAUDE.md b/CLAUDE.md
index 697d42584..b0728cf4e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,40 @@
# PolicyEngine App v2 Development Guidelines
+## Visual Standards (MUST READ)
+
+Detailed visual standards are documented in `.claude/skills/`. **These are mandatory for all UI code:**
+
+- `.claude/skills/design-tokens.md` - Color, spacing, typography tokens
+- `.claude/skills/chart-standards.md` - Plotly chart patterns
+- `.claude/skills/ingredient-patterns.md` - CRUD page patterns
+
+### Critical Rules
+
+1. **SENTENCE CASE EVERYWHERE** - All UI text must use sentence case (capitalize only first word and proper nouns). No Title Case.
+ - Correct: "Your saved policies", "Date created", "New simulation"
+ - Wrong: "Your Saved Policies", "Date Created", "New Simulation"
+ - Exceptions: Proper nouns (PolicyEngine, California), acronyms (IRS, UK), official program names (Child Tax Credit)
+
+2. **USE DESIGN TOKENS** - Never hardcode colors, spacing, or typography values.
+ ```tsx
+ // WRONG
+ style={{ color: '#319795', marginBottom: '16px' }}
+
+ // CORRECT
+ import { colors, spacing } from '@/designTokens';
+ style={{ color: colors.primary[500], marginBottom: spacing.lg }}
+ ```
+
+3. **CHART COLORS** - Use semantic colors for data:
+ - Positive/gains: `colors.primary[500]` (teal)
+ - Negative/losses: `colors.gray[600]`
+ - Always wrap charts in ``
+
+4. **INGREDIENT PAGES** - Follow the standard pattern in `ingredient-patterns.md`:
+ - Use `IngredientReadView` component
+ - Use `RenameIngredientModal` for rename
+ - Transform data to `IngredientRecord[]`
+
## Branding & Logos
### Color Palette
diff --git a/app/src/CalculatorRouter.tsx b/app/src/CalculatorRouter.tsx
index e1f4964db..e28e04783 100644
--- a/app/src/CalculatorRouter.tsx
+++ b/app/src/CalculatorRouter.tsx
@@ -20,6 +20,19 @@ import { MetadataGuard } from './routing/guards/MetadataGuard';
import { MetadataLazyLoader } from './routing/guards/MetadataLazyLoader';
import { RedirectToCountry } from './routing/RedirectToCountry';
+/**
+ * Layout wrapper that renders StandardLayout with Outlet for nested routes.
+ * This allows the app shell (header, sidebar) to remain visible while
+ * child guards like MetadataGuard show their loading states.
+ */
+function StandardLayoutOutlet() {
+ return (
+
+
+
+ );
+}
+
const router = createBrowserRouter(
[
{
@@ -30,16 +43,13 @@ const router = createBrowserRouter(
path: '/:countryId',
element: ,
children: [
- // Routes that need metadata immediately (blocking guard)
+ // Routes with standard layout that need metadata (blocking)
+ // Layout is OUTSIDE the guard so app shell remains visible during loading
{
- element: ,
+ element: ,
children: [
{
- element: (
-
-
-
- ),
+ element: ,
children: [
{
path: 'report-output/:reportId/:subpage?/:view?',
@@ -49,17 +59,41 @@ const router = createBrowserRouter(
},
],
},
+ // Pathway routes that need metadata (blocking)
+ // Pathways manage their own AppShell layouts - do NOT wrap in StandardLayoutOutlet
+ // This allows views like PolicyParameterSelectorView to use custom AppShell configurations
+ {
+ element: ,
+ children: [
+ {
+ element: ,
+ children: [
+ {
+ path: 'reports/create',
+ element: ,
+ },
+ {
+ path: 'simulations/create',
+ element: ,
+ },
+ {
+ path: 'households/create',
+ element: ,
+ },
+ {
+ path: 'policies/create',
+ element: ,
+ },
+ ],
+ },
+ ],
+ },
// Routes that benefit from metadata but don't require it (lazy loader)
{
element: ,
children: [
- // Regular routes with standard layout
{
- element: (
-
-
-
- ),
+ element: ,
children: [
{
index: true,
@@ -91,28 +125,6 @@ const router = createBrowserRouter(
},
],
},
- // Pathway routes that manage their own layouts
- {
- element: ,
- children: [
- {
- path: 'reports/create',
- element: ,
- },
- {
- path: 'simulations/create',
- element: ,
- },
- {
- path: 'households/create',
- element: ,
- },
- {
- path: 'policies/create',
- element: