PolicyEngine · MaxGhenis · May 9, 2026 · May 9, 2026 · May 9, 2026
diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml
@@ -30,8 +30,13 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Run tests
-        run: bun run test
-
+      # Build first so the consumer-types harness in tests/consumer-types/
+      # can type-check the dist/ surface a real consumer sees. With this
+      # order the harness will fail loudly on regressions like the
+      # bundler-resolution drop fixed in 0.8.1/0.8.2; flipped (test before
+      # build), the harness silently skips.
       - name: Build package
         run: bun run build
+
+      - name: Run tests
+        run: bun run test
diff --git a/changelog.d/consumer-types-harness.added.md b/changelog.d/consumer-types-harness.added.md
@@ -0,0 +1 @@
+Consumer-style typecheck harness (`tests/consumer-types/`). Type-checks a representative consumer fixture against the *built* `dist/` surface using `moduleResolution: "bundler"`, so any regression on the export shape of the main entry, the `legacy/` subpath, or the per-feature subpaths fails CI loudly. Catches the silent `dist/<name>.js`-shadows-`dist/<name>/index.d.ts` resolution failure that 0.8.0/0.8.1 shipped before being fixed in 0.8.1/0.8.2. The PR check workflow now runs `bun run build` before `bun run test` so the harness exercises freshly-built artifacts.
diff --git a/changelog.d/legacy-blue-success-restored.fixed.md b/changelog.d/legacy-blue-success-restored.fixed.md
@@ -0,0 +1 @@
+`@policyengine/ui-kit/legacy` now exposes `colors.blue` (Tailwind sky 50–900) and `colors.success` (`#22C55E`), restoring parity with `@policyengine/design-system` 0.2.0/0.3.0. The snapshot copied into `src/legacy/` for 0.8.0 came from a later workspace build that had dropped both, forcing cbo-baseline-tracker and uk-spring-statement-2026 to backfill them locally. The legacy color tests now pin both values so future regressions fail CI.
diff --git a/changelog.d/legacy-migration-map-clarity.changed.md b/changelog.d/legacy-migration-map-clarity.changed.md
@@ -0,0 +1 @@
+JSDoc migration map in `src/legacy/index.ts` now flags which design-system → ui-kit mappings preserve hex values (most) and which shift them (`colors.gray[N]` → `palette.gray[N]` is Tailwind-3 → Slate; `colors.text.warning` → `--text-warning` is Mantine orange.9 → Tailwind orange-700, the latter for WCAG AA). Bulk `sed`-replace from design-system to canonical ui-kit names is unsafe for those two pairs without a visual review.
diff --git a/src/legacy/index.ts b/src/legacy/index.ts
@@ -1,10 +1,15 @@
 /**
  * @policyengine/ui-kit/legacy
  *
- * @deprecated Backwards-compatibility shim that re-exports the API surface of
- * the legacy `@policyengine/design-system` package. Use the canonical exports
- * from `@policyengine/ui-kit` (root) and the `tokens` / `theme.css` /
- * `quarto.scss` subpath exports for new code.
+ * @deprecated Backwards-compatibility shim that re-exports the API *shape* of
+ * the legacy `@policyengine/design-system` package. The keys are 1:1 with the
+ * latest design-system source (`policyengine-app-v2/packages/design-system`),
+ * and most values are bit-identical to design-system 0.3.0 — but a few values
+ * have shifted between 0.3.0 and 0.4.0 (notably `colors.info` blue → teal),
+ * and the shim added `colors.text.{warning,error,success}` accessibility-tuned
+ * variants that weren't in 0.3.0. Use the canonical exports from
+ * `@policyengine/ui-kit` (root) and the `tokens` / `theme.css` / `quarto.scss`
+ * subpath exports for new code.
  *
  * This module exists to make the migration from `@policyengine/design-system`
  * a pure import-path rename:
@@ -14,16 +19,45 @@
  *   - import … from '@policyengine/design-system/charts'    → '@policyengine/ui-kit/legacy/charts'
  *   - import … from '@policyengine/design-system/tokens/colors'  → '@policyengine/ui-kit/legacy/tokens/colors'
  *
- * Mapping to canonical ui-kit exports for net-new code:
+ * Mapping to canonical ui-kit exports for net-new code. ⚠ Several mappings
+ * shift visible color values (usually for WCAG accessibility). Don't bulk
+ * `sed`-replace — pick per usage:
  *
- *   colors.primary[N]        → palette.teal[N]
- *   colors.gray[N]           → palette.gray[N]
- *   colors.warning           → semanticFills.warning
- *   colors.error             → semanticFills.error
- *   colors.text.warning      → rootColorsLight['--text-warning']  (or `var(--text-warning)`)
- *   typography.fontFamily.primary → typography.fontFamily.sans
- *   spacing.{layout,…}       → namedSpacing  (only `header`, `sidebar`, `content` exposed today)
- *   chartColors / chartLayout → see charts/chartDefaults.ts (Recharts) or chartPalette (resolved hex)
+ *   colors.primary[N]        → palette.teal[N]                       (same hex)
+ *   colors.gray[N]           → palette.gray[N]                       (DIFFERENT hex —
+ *                                                                     legacy is Tailwind-3
+ *                                                                     gray, canonical is
+ *                                                                     Slate-flavored. e.g.
+ *                                                                     legacy gray.500
+ *                                                                     #6B7280 vs canonical
+ *                                                                     gray.500 #64748B)
+ *   colors.blue[N]           → palette.blue[N]                       (same hex)
+ *   colors.warning           → semanticFills.warning                 (same: #FEC601)
+ *   colors.error             → semanticFills.error                   (same: #EF4444)
+ *   colors.success           → semanticFills.success                 (same: #22C55E)
+ *   colors.info              → semanticFills.info                    (DIFFERENT hex —
+ *                                                                     0.3.0 was Ant blue
+ *                                                                     #1890FF; design-system
+ *                                                                     0.4.0+ and this shim
+ *                                                                     use PE teal-700
+ *                                                                     #2C7A7B for brand
+ *                                                                     consistency. Consumers
+ *                                                                     coming from 0.3.x will
+ *                                                                     see info change blue→
+ *                                                                     teal.)
+ *   colors.text.warning      → rootColorsLight['--text-warning']     (DIFFERENT hex —
+ *                                                                     legacy #d9480f
+ *                                                                     fails WCAG AA at
+ *                                                                     small text;
+ *                                                                     canonical #c2410c
+ *                                                                     clears 5.18:1)
+ *   typography.fontFamily.primary → typography.fontFamily.sans        (same stack)
+ *   spacing.{layout,…}       → namedSpacing                           (only `header`,
+ *                                                                     `sidebar`, `content`
+ *                                                                     exposed today —
+ *                                                                     scale values aren't)
+ *   chartColors / chartLayout → see charts/chartDefaults.ts (Recharts) or chartPalette
+ *                              (resolved hex)
  *
  * This module will be removed in a future major release once consumers migrate.
  */

diff --git a/src/legacy/tokens/colors.ts b/src/legacy/tokens/colors.ts
@@ -39,10 +39,29 @@ export const colors = {
   },
 
   // Semantic colors
+  success: "#22C55E",
   warning: "#FEC601",
   error: "#EF4444",
   info: "#2C7A7B",
 
+  // Blue accent palette — restored from @policyengine/design-system 0.2.0/0.3.0.
+  // The snapshot copied into legacy/ in ui-kit 0.8.0 came from a later workspace
+  // build that had dropped this; consumer migrations from the published 0.3.x
+  // were silently losing colors.blue, forcing local backfills in
+  // cbo-baseline-tracker and uk-spring-statement-2026.
+  blue: {
+    50: "#F0F9FF",
+    100: "#E0F2FE",
+    200: "#BAE6FD",
+    300: "#7DD3FC",
+    400: "#38BDF8",
+    500: "#0EA5E9",
+    600: "#0284C7",
+    700: "#026AA2",
+    800: "#075985",
+    900: "#0C4A6E",
+  },
+
   // Neutral colors
   white: "#FFFFFF",
   black: "#000000",

diff --git a/tests/consumer-types/fixture.ts b/tests/consumer-types/fixture.ts
@@ -0,0 +1,177 @@
+/**
+ * Consumer-style import surface used by the typecheck harness in
+ * `tests/consumer-types/typecheck.test.ts`. Mirrors what real consumers
+ * write — the harness type-checks this file against the *built* package
+ * (via path mappings to dist/), so any regression that drops symbols from
+ * the main entry, the legacy/ subpath, or the per-feature subpaths fails
+ * the test loudly instead of silently shipping to consumers.
+ *
+ * If you add a new top-level export to ui-kit, add a use of it here too —
+ * otherwise the test won't catch a regression on it.
+ */
+
+// Main entry — primitives, layout, charts, visualization, theme, utils
+import {
+  // Primitives — main offenders for the dist/<name>.js vs dist/<name>/index.d.ts
+  // resolution bug, kept in alphabetical order to make additions easy
+  Accordion,
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Checkbox,
+  Collapsible,
+  Container,
+  Dialog,
+  DropdownMenu,
+  Input,
+  Label,
+  Popover,
+  Progress,
+  RadioGroup,
+  ScrollArea,
+  Select,
+  Separator,
+  Sheet,
+  Skeleton,
+  Spinner,
+  Switch,
+  Tabs,
+  Text,
+  Textarea,
+  Title,
+  Tooltip,
+  // Layout
+  DashboardShell,
+  Header,
+  Footer,
+  Stack,
+  Group,
+  // Inputs
+  CurrencyInput,
+  NumberInput,
+  // Display
+  DataTable,
+  MetricCard,
+  // Charts
+  ChartContainer,
+  PEBarChart,
+  PELineChart,
+  PEAreaChart,
+  PEWaterfallChart,
+  // Tokens (runtime)
+  palette,
+  semanticFills,
+  typography,
+  namedSpacing,
+  chartPalette,
+  rootColorsLight,
+  rootColorsDark,
+  // Utilities
+  cn,
+  formatCurrency,
+  formatPercent,
+  getNiceTicks,
+  // Assets
+  logos,
+} from "@policyengine/ui-kit";
+
+// Legacy compat — design-system migration target
+import {
+  colors as legacyColors,
+  typography as legacyTypography,
+  spacing as legacySpacing,
+  chartColors as legacyChartColors,
+} from "@policyengine/ui-kit/legacy";
+
+// Legacy subpath — explicit per-module resolution
+import { colors as legacyColors2 } from "@policyengine/ui-kit/legacy/tokens";
+import { colors as legacyColors3 } from "@policyengine/ui-kit/legacy/tokens/colors";
+import { typography as legacyTypography2 } from "@policyengine/ui-kit/legacy/tokens/typography";
+import { spacing as legacySpacing2 } from "@policyengine/ui-kit/legacy/tokens/spacing";
+import { chartColors as legacyChartColors2 } from "@policyengine/ui-kit/legacy/charts";
+
+// Per-feature subpaths — used by consumers that want narrow imports
+import { Badge as Badge2 } from "@policyengine/ui-kit/primitives";
+import { Container as Container2 } from "@policyengine/ui-kit/layout";
+import { ChartContainer as ChartContainer2 } from "@policyengine/ui-kit/charts";
+
+// Specific properties consumers depend on — separate use site so a missing
+// value (e.g. `colors.blue`/`colors.success` going missing in the legacy
+// shim, which forced two consumer migrations to add local backfills) gets
+// caught even though the top-level `colors` import already type-checks.
+export const _LegacyColorPaths = {
+  bluePalette: legacyColors.blue, // restored in 0.9.0; was missing in 0.8.x
+  successScalar: legacyColors.success, // ditto
+  textWarning: legacyColors.text.warning,
+  primaryBrand: legacyColors.primary[500],
+  grayMid: legacyColors.gray[500],
+};
+
+// Touch each binding so unused-import settings don't strip them.
+export type _SmokeTest =
+  | typeof Accordion
+  | typeof Alert
+  | typeof Badge
+  | typeof Button
+  | typeof Card
+  | typeof Checkbox
+  | typeof Collapsible
+  | typeof Container
+  | typeof Dialog
+  | typeof DropdownMenu
+  | typeof Input
+  | typeof Label
+  | typeof Popover
+  | typeof Progress
+  | typeof RadioGroup
+  | typeof ScrollArea
+  | typeof Select
+  | typeof Separator
+  | typeof Sheet
+  | typeof Skeleton
+  | typeof Spinner
+  | typeof Switch
+  | typeof Tabs
+  | typeof Text
+  | typeof Textarea
+  | typeof Title
+  | typeof Tooltip
+  | typeof DashboardShell
+  | typeof Header
+  | typeof Footer
+  | typeof Stack
+  | typeof Group
+  | typeof CurrencyInput
+  | typeof NumberInput
+  | typeof DataTable
+  | typeof MetricCard
+  | typeof ChartContainer
+  | typeof PEBarChart
+  | typeof PELineChart
+  | typeof PEAreaChart
+  | typeof PEWaterfallChart
+  | typeof palette
+  | typeof semanticFills
+  | typeof typography
+  | typeof namedSpacing
+  | typeof chartPalette
+  | typeof rootColorsLight
+  | typeof rootColorsDark
+  | typeof cn
+  | typeof formatCurrency
+  | typeof formatPercent
+  | typeof getNiceTicks
+  | typeof logos
+  | typeof legacyColors
+  | typeof legacyTypography
+  | typeof legacySpacing
+  | typeof legacyChartColors
+  | typeof legacyColors2
+  | typeof legacyColors3
+  | typeof legacyTypography2
+  | typeof legacySpacing2
+  | typeof legacyChartColors2
+  | typeof Badge2
+  | typeof Container2
+  | typeof ChartContainer2;
diff --git a/tests/consumer-types/tsconfig.json b/tests/consumer-types/tsconfig.json
@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "types": [],
+    "baseUrl": "../..",
+    "paths": {
+      "@policyengine/ui-kit": ["./dist/index.d.ts"],
+      "@policyengine/ui-kit/legacy": ["./dist/legacy/index.d.ts"],
+      "@policyengine/ui-kit/legacy/tokens": ["./dist/legacy/tokens/index.d.ts"],
+      "@policyengine/ui-kit/legacy/tokens/colors": ["./dist/legacy/tokens/colors.d.ts"],
+      "@policyengine/ui-kit/legacy/tokens/typography": ["./dist/legacy/tokens/typography.d.ts"],
+      "@policyengine/ui-kit/legacy/tokens/spacing": ["./dist/legacy/tokens/spacing.d.ts"],
+      "@policyengine/ui-kit/legacy/charts": ["./dist/legacy/charts/index.d.ts"],
+      "@policyengine/ui-kit/primitives": ["./dist/primitives/index.d.ts"],
+      "@policyengine/ui-kit/layout": ["./dist/layout/index.d.ts"],
+      "@policyengine/ui-kit/charts": ["./dist/charts/index.d.ts"]
+    }
+  },
+  "include": ["fixture.ts"]
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Consumer-style typecheck harness (`tests/consumer-types/`). Type-checks a representative consumer fixture against the built `dist/` surface using `moduleResolution: "bundler"`, so any regression on the export shape of the main entry, the `legacy/` subpath, or the per-feature subpaths fails CI loudly. Catches the silent `dist/<name>.js`-shadows-`dist/<name>/index.d.ts` resolution failure that 0.8.0/0.8.1 shipped before being fixed in 0.8.1/0.8.2. The PR check workflow now runs `bun run build` before `bun run test` so the harness exercises freshly-built artifacts.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		`@policyengine/ui-kit/legacy` now exposes `colors.blue` (Tailwind sky 50–900) and `colors.success` (`#22C55E`), restoring parity with `@policyengine/design-system` 0.2.0/0.3.0. The snapshot copied into `src/legacy/` for 0.8.0 came from a later workspace build that had dropped both, forcing cbo-baseline-tracker and uk-spring-statement-2026 to backfill them locally. The legacy color tests now pin both values so future regressions fail CI.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		JSDoc migration map in `src/legacy/index.ts` now flags which design-system → ui-kit mappings preserve hex values (most) and which shift them (`colors.gray[N]` → `palette.gray[N]` is Tailwind-3 → Slate; `colors.text.warning` → `--text-warning` is Mantine orange.9 → Tailwind orange-700, the latter for WCAG AA). Bulk `sed`-replace from design-system to canonical ui-kit names is unsafe for those two pairs without a visual review.