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:

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

Semantic (shadcn/ui)

Charts

Additional semantic colors

Gray scale

Typography

Font families

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

Loading Inter:

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

Font sizes

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:

Border radius

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

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:
   tsxCopy

   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/:

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

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)