A design system for software that decides things about people's lives. It is built on the conviction that in public-benefits tools, clarity is a safety feature and a citation carries weight.
In the lineage of the U.S. Web Design System, refined past what a government site would ship.
Four convictions decide every token and component below. They come before the rules, because the rules are downstream of them.
A misread notice can cost someone their benefits. Here legibility is harm reduction.
Every figure shows where it came from: a document, a rule, or an unverified claim. Sourcing is a first-class visual element.
One accent, real whitespace, no decoration that performs rigor it does not carry. If a metric does not vary, it does not earn pixels.
AA contrast, visible focus, and never color alone. Inherited from the canon, kept non-negotiable.
The U.S. Web Design System is the most battle-tested civic design language there is: accessible, plain, and trusted. Civil keeps what makes it trustworthy and refines what makes it feel like a form from 2015. Every change stays within the idiom. A government team could adopt Civil without leaving the hymnal.
| Decision | USWDS | Civil | Why |
|---|---|---|---|
| Display type | Merriweather, rarely used well | Source Serif 4 for display | A serif used with intent signals editorial care; the Source super-family stays cohesive with the body sans. |
| Primary color | Saturated federal blue | Evergreen #1F6F5C | Calmer and more humane than institutional blue, still unmistakably civic. |
| Canvas | White / cool gray | Warm paper #FBFAF8 | Softer, less clinical; easier for long case review. |
| Type scale | Broad, utilitarian | Tighter ~1.2 scale | More refined hierarchy; less shouting. |
| Density | Form-first | Content-first | Optimized for reading a determination, where a form layout would waste the space. |
Source Sans 3 for everything you operate, Source Serif 4 for the things you read, Roboto Mono for the things you cite. The serif is the elevation: government interfaces almost never trust a serif, and used only for display it reads as care.
Tokens are roles rather than paint: primary, ink, base, the warm accents, and the state colors. Color always carries meaning (success, caution, error) and never decorates. Every pairing clears AA contrast.
Civil keeps the four components that carry civic interfaces, each with a clear job and a clear edge.
The headline outcome of a page, set apart. Use it for the one thing a reader must take away, here the recommendation and its reason.
A state that needs attention, in four meanings. The left bar and icon carry the meaning so it never rests on color alone.
A small label for provenance, citations, and categories. Mono tags read as artifacts you can trust and trace.
Progress through a defined process, with the meaningful step emphasized. Here it makes the agent pipeline (and its deterministic boundary) visible.
One filled primary for the main action, an outline default for the rest. At most one primary per view.
The system is a set of CSS custom properties (the tokens) plus component classes. Build with the tokens, never raw hex, so a palette or scale change is one edit. Reference the role rather than the value:
.recommendation { color: var(--ink); background: var(--surface); border-left: 3px solid var(--primary); padding: var(--s-2); border-radius: var(--radius-md); }
Civil is implemented end-to-end in this caseworker app (web/static/styles.css) and documented in DESIGN_SYSTEM.md. The portfolio's other tools carry the same type and palette for family resemblance; the full component system lives here, where a hand-built front-end can express it.