policyengine-design

PolicyEngine design system

Design tokens live as CSS custom properties in @policyengine/ui-kit/theme.css. Every frontend imports that one file. The canonical version is @policyengine/ui-kit ^0.4.0 — the version app-v2 pins. Ignore claims tied to 0.5/0.6/0.9; treat 0.4.0 as ground truth and re-check node_modules/@policyengine/ui-kit when precision matters.

Setup: the two imports

/* globals.css — order matters; Tailwind must come first */
@import "tailwindcss";
@import "@policyengine/ui-kit/theme.css";

Next.js needs postcss.config.mjs = { plugins: { "@tailwindcss/postcss": {} } } (install @tailwindcss/postcss + postcss). A Vite app uses the @tailwindcss/vite plugin instead — no PostCSS config. Do not add postcss-import or autoprefixer (@tailwindcss/postcss handles both), and do not add a second @import "tailwindcss" (theme.css does not import it). If the consumer's own utility classes go missing in a monorepo, scope source detection: @import "tailwindcss" source("./src");.

The three-layer theme.css

theme.css (source: ui-kit src/theme/tokens.css, vendored from design-system v0.3.0) has three layers:

Layer 1  :root { --primary: #2C7A7B; --chart-1: #319795; ... }   raw shadcn/ui semantic values
Layer 2  @theme inline { --color-primary: var(--primary); }       bridge :root → Tailwind utilities
Layer 3  @theme { --color-teal-500: #319795; --text-sm: 14px; }   brand palette, fonts, sizes, spacing

@theme vs @theme inline — the mechanism

• @theme inline keeps the var() reference, so the utility resolves it at runtime. Use it whenever a token points at a :root variable — that is what lets bg-primary follow a .dark override. All shadcn/ui semantic tokens use @theme inline.
• @theme bakes a literal value into the generated CSS at build time. Use it for the fixed brand palette (teal-500 is always #319795), font sizes, spacing, breakpoints.

Getting these backwards is the classic bug: @theme { --color-primary: var(--primary); } bakes the literal string var(--primary) and never re-resolves.