policyengine-design

PolicyEngine design system

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 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
<meta> 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 ui-kit theme

Install:

bun install @policyengine/ui-kit

Import the theme CSS in your globals.css:

@import "tailwindcss";
@import "@policyengine/ui-kit/theme.css";

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.

Source: PolicyEngine/policyengine-ui-kit/src/theme/tokens.css

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	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	#DC2626
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

These are the brand fill values — use for status dots, badges, and tinted surfaces. They are not WCAG-AA-compliant when set as text on a white background; for text, use the accessible-on-white variants below.

Color	Hex	Tailwind class
Success	#22C55E	text-success / bg-success
Error	#DC2626	text-destructive / bg-destructive
Warning	#FEC601	text-warning / bg-warning
Info	#1890FF	text-info / bg-info

Accessible-on-white text variants

Distinct from the brand fills above — these are the values you use when you actually need to render colored text on a white background and want to clear WCAG 2.2 AA (4.5:1 contrast at small text). Available since ui-kit 0.5.0 as --text-warning / --text-error / --text-success and the corresponding Tailwind utilities.

Token	Hex	Tailwind class	Contrast on white
--text-warning	#c2410c (Tailwind orange-700)	text-warning-foreground	5.18:1 ✓
--text-error	#B91C1C (Tailwind red-700)	text-error-foreground	5.94:1 ✓
--text-success	#285E61 (PE teal-700)	text-success-foreground	7.07:1 ✓

The plain text-warning / text-destructive / text-success brand classes are intentionally not AA on white — they're meant for soft-tinted backgrounds and badge fills, not paragraph text.

Dark mode

Available since ui-kit 0.6.0. Activate by adding class="dark" to any ancestor element — no JS or media query required. Every shadcn semantic token (--primary, --background, --card, --border, etc.) and accessible text variant has a dark-mode value pinned to clear AA on the dark page background #0B0E14. Dark-mode values are tested by tests/theme/contrast.test.ts in ui-kit and exposed under the :root.dark selector in theme.css.

<!-- consumer site dark-mode toggle: just toggle the .dark class on <html> -->
<html class="dark">
  ...
</html>

If you're rendering charts, prefer the CSS-var form (fill="var(--chart-1)") over a hex literal — that way the chart picks up dark-mode swaps automatically. For Plotly / Python where there's no CSS runtime, use chartPalette.light and chartPalette.dark from @policyengine/ui-kit and pick by detected theme.

Gray scale

ui-kit's palette.gray is Slate-flavored (matches the dashboard's neutral surfaces and --border / --muted tokens). The legacy @policyengine/ui-kit/legacy/tokens shim still exports the Tailwind-3 grays (#6B7280 for 500, #4B5563 for 600) for design-system migration parity, but new code should use the canonical Slate values below.

Token	Hex	Tailwind class
gray-50	#F0F9FF	bg-gray-50
gray-100	#F2F4F7	bg-gray-100
gray-200	#E2E8F0	bg-gray-200
gray-300	#CBD5E1	bg-gray-300
gray-400	#94A3B8	bg-gray-400
gray-500	#64748B	text-gray-500
gray-600	#475569	text-gray-600
gray-700	#344054	text-gray-700
gray-800	#1E293B	text-gray-800
gray-900	#101828	text-gray-900

Typography

Font families

Two font families only: Inter + JetBrains Mono. No serif fonts, no Roboto, no Public Sans.

Context	Font	CSS variable	Tailwind
Everything (UI, charts, blog, tools)	Inter	--font-sans	font-sans
Code	JetBrains Mono	--font-mono	font-mono

Loading Inter:

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">

Font sizes

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

All UI text uses sentence case — capitalize only the first word and proper nouns.

• "Your saved policies" not "Your Saved Policies"
• "Tax liability by income" not "Tax Liability by Income"
• Proper nouns stay capitalized: "Child Tax Credit", "PolicyEngine", "California"

Spacing

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

Tailwind class	Value
rounded-sm	4px
rounded-md	6px
rounded-lg	8px

Chart branding

Recharts (React tools)

import { BarChart, Bar, XAxis, YAxis, Tooltip } from "recharts";

<BarChart data={data}>
  <XAxis dataKey="name" niceTicks="snap125" domain={["auto", "auto"]} style={{ fontFamily: "var(--font-sans)" }} />
  <YAxis niceTicks="snap125" domain={["auto", "auto"]} style={{ fontFamily: "var(--font-sans)" }} />
  <Tooltip separator=": " />
  <Bar dataKey="value" fill="var(--chart-1)" />
</BarChart>

SVG fill and stroke attributes accept var() directly — no helper function needed.

Plotly (Python)

import plotly.graph_objects as go

TEAL = "#319795"  # --chart-1
CHART_FONT = "Inter"
LOGO_URL = "https://raw.githubusercontent.com/PolicyEngine/policyengine-app-v2/main/app/public/assets/logos/policyengine/teal.png"

def format_fig(fig):
    fig.update_layout(
        font=dict(family=CHART_FONT, color="black", size=14),
        plot_bgcolor="white",
        paper_bgcolor="white",
        template="plotly_white",
        height=600,
        width=800,
        margin=dict(l=60, r=40, t=40, b=60),
        modebar=dict(bgcolor="rgba(0,0,0,0)", color="rgba(0,0,0,0)"),
    )
    fig.add_layout_image(dict(
        source=LOGO_URL,
        xref="paper", yref="paper",
        x=1.0, y=-0.10,
        sizex=0.10, sizey=0.10,
        xanchor="right", yanchor="bottom",
    ))
    return fig

Chart color conventions

Meaning	CSS variable	Hex
Positive / bonus / gains	--chart-1	#319795
Negative / penalty / losses	--chart-5 or --destructive	#6B7280 or #DC2626
Neutral / baseline	--border	#E2E8F0
Multi-series	--chart-1 through --chart-5	See chart table above

Inverted metrics (taxes): When a positive delta means bad (higher taxes), use invertDelta logic to show "Penalty" label and swap colors.

Chart typography

• Axis labels and titles: var(--font-sans), 14px
• Tick labels: var(--font-sans), 12px
• Legend: var(--font-sans), horizontal, above chart

Favicon

Every PolicyEngine dashboard must include a favicon. The ui-kit exports the logo as a favicon-ready SVG:

1. Copy: cp node_modules/@policyengine/ui-kit/src/assets/logos/policyengine/teal-square.svg public/favicon.svg
2. Add to layout.tsx metadata:

   export const metadata: Metadata = {
     // ...
     icons: { icon: '/favicon.svg' },
   };
   

The ui-kit also exports logos.favicon (SVG) and logos.faviconPng (PNG fallback) for programmatic use.

Logos

All logo files in policyengine-app-v2/app/public/assets/logos/policyengine/:

File	Background	Format
teal.png / teal.svg	Light	Wide
teal-square.png / teal-square.svg	Light	Square (for chart watermarks)
white.png / white.svg	Dark	Wide
white-square.svg	Dark	Square

Raw URL for charts:

https://raw.githubusercontent.com/PolicyEngine/policyengine-app-v2/main/app/public/assets/logos/policyengine/teal.png

Using tokens by project type

Project type	Token source	Font setup
Standalone tool	@import "@policyengine/ui-kit/theme.css"	Google Fonts: Inter
app-v2	import { colors } from '@/designTokens'	Built-in (Mantine + Inter)
Python chart	Hardcode or load tokens.json from @policyengine/design-system	Inter for Plotly
Blog HTML	Hardcode from token values	Google Fonts: Inter

Accessibility

• Teal #319795 on white passes WCAG AA for large text (3.8:1)
• text-foreground (#000000) on white passes AAA (21:1)
• text-muted-foreground (#6B7280) on white passes AA (4.6:1)
• Never rely on color alone — use labels, patterns, or position to convey meaning
• Ensure chart data series are distinguishable in grayscale

Related skills

• policyengine-interactive-tools-skill — Building standalone tools that use these tokens
• policyengine-vercel-deployment-skill — Deploying standalone tools
• policyengine-app-skill — app-v2 development
• policyengine-writing-skill — Content style (complements visual style)