Policyengine Design

PolicyEngine design system

Single source of truth for PolicyEngine's visual identity. All tokens live in @policyengine/design-system (npm). Every project — app-v2, standalone tools, charts, Streamlit — should reference these values rather than hardcoding hex codes.

The design system package

Install:

npm install @policyengine/design-system

Three export formats:

CDN (no install):

<link rel="stylesheet" href="https://unpkg.com/@policyengine/design-system/dist/tokens.css">

Source: PolicyEngine/policyengine-app-v2/packages/design-system/

Colors

Primary — teal

CSS: var(--pe-color-primary-500) through var(--pe-color-primary-900)

Gray

Blue (accent)

Semantic

Text

Background

Legacy colors (deprecated)

These appear in older projects. Migrate to the values above.

Typography

Font families

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

Legacy aliases (--pe-font-family-chart, --pe-font-family-body, --pe-font-family-prose, --pe-font-family-secondary) all resolve to Inter for backward compatibility.

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

Border radius

Chart branding

Plotly (Python)

import plotly.graph_objects as go

# Import from tokens.json or hardcode
TEAL = "#319795"
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

Recharts (React standalone tools)

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

<BarChart data={data}>
  <XAxis dataKey="name" style={{ fontFamily: "Inter" }} />
  <YAxis style={{ fontFamily: "Inter" }} />
  <Tooltip />
  <Bar dataKey="value" fill="#319795" />
</BarChart>

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: Inter, 14px
• Tick labels: Inter, 12px
• Legend: Inter, horizontal, above chart

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

Streamlit apps

# .streamlit/config.toml
[theme]
base = "light"
primaryColor = "#319795"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#E6FFFA"
textColor = "#000000"

[client]
toolbarMode = "minimal"

Using tokens by project type

Accessibility

• Teal #319795 on white passes WCAG AA for large text (3.8:1)
• text.primary (#000000) on white passes AAA (21:1)
• text.secondary (#5A5A5A) on white passes AA (7.4: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)