# FIOA Agent — Design System

A Material Design 3–based design system for public-records request management, redaction, and release. Civic-navy, institutional, plain-language. Built for the full cast of govtech users — from anonymous citizen requesters to records officers, legal review, and CISOs.

> **Status:** Foundations + core component library. Product UI kits (queue, redaction workspace, requester portal, release review) come next, layered on top of these tokens.

---

## 1. How to use

Link the single entry stylesheet. It pulls in every token file.

```html
<link rel="stylesheet" href="styles.css">
```

Then build with the semantic CSS custom properties — **never hard-code hex, px, or shadows**. Everything cascades from `tokens/`.

```html
<button style="
  height: var(--control-height);
  padding: 0 20px;
  border-radius: var(--radius-control);
  background: var(--accent);
  color: var(--text-on-accent);
  font: var(--weight-semibold) var(--label-large-size)/var(--label-large-line) var(--font-sans);
">Mark as released</button>
```

### File map
```
styles.css                ← link this
tokens/
  fonts.css               webfont @imports
  colors.css              MD3 roles + semantic + status lifecycle
  typography.css          serif/sans/mono scale
  spacing.css             4px grid + control sizing
  shape.css               corner radii
  elevation.css           navy-tinted shadow levels
  motion.css              easing + duration
assets/
  logo-mark.svg           brand mark
guidelines/               specimen + component cards (browsable)
index.html                visual reference — open this first
```

---

## 2. Brand

**Name:** FIOA Agent · **Tagline:** Records · Redact · Release

**Personality:** Modern govtech — clean, confident, "Stripe-for-government." Calm institutional authority without stodginess. We reduce anxiety around a legal process; we never sound bureaucratic.

**The mark** is a shield built from camera-shutter blades: the shield is security, compliance, and the protection of sensitive records; the half-open shutter is discovery, finding records, and transparency. It ships as two SVGs — civic navy (`logo-mark.svg`) for light surfaces and white (`logo-mark-white.svg`) for dark — so it always contrasts with its background. Pair it with the **Source Serif 4 Semibold** wordmark. Minimum size 24px. Don't recolor, stretch, rotate, or place it on a busy background.

### Voice
- **Plain language over legalese.** "You'll hear back by July 11," not "pending adjudication."
- **Name the exemption in human terms,** with the statute in mono as a secondary reference.
- **Status is always honest** — overdue is overdue. Never soften a missed statutory deadline.
- Address every requester type with equal respect; never gatekeep access in copy.

---

## 3. Color

Navy-anchored Material 3 tonal scheme. **Primary** (`#1B53A6`) drives actions; **brand navy** (`#0F2E5E`) is reserved for serif headlines, the masthead, and the redaction toolbar. **Tertiary teal** signals verified/released. **Seal gold** is for certifications and seals only — never as a UI accent.

Reach for the **semantic aliases** (`--accent`, `--surface-card`, `--text-secondary`, `--border`) rather than raw MD3 roles in product code.

### Status lifecycle
Eight workflow states, each a `--status-{name}-fg` / `-bg` pair: `received · triage · routed · redaction · review · released · overdue · onhold`. Always pair fg+bg; never invent ad-hoc status colors.

### Accessibility
Targets WCAG 2.1 AA / Section 508. Body text on surface meets 4.5:1; status pill fg-on-bg pairs are tuned for ≥4.5:1. Never signal status by color alone — pills carry a dot + label, the stepper carries icons.

---

## 4. Typography

Three families, strict roles:
- **Source Serif 4** — display & headline only. Institutional gravitas; never below 24px.
- **Public Sans** (USWDS face) — all titles, body, and UI labels. The workhorse.
- **IBM Plex Mono** — request IDs, statutory exemption codes, audit hashes, timestamps. Never prose.

Full MD3 scale lives in `typography.css` as `--{role}-{size|line|weight|tracking}`. Minimum body size 14px; minimum interactive label 11px.

> Fonts currently load from the Google Fonts CDN as a substitution. Self-host licensed binaries before production and swap the `@import` in `tokens/fonts.css`.

---

## 5. Spacing, shape, elevation, motion

- **Spacing** — 4px grid (`--space-1`…`--space-11`). Balanced density: 40px default controls, 48px rows, 44px minimum touch target.
- **Shape** — restrained corners. Controls 8px, cards 12px, sheets 16px, pills full. Nothing rounder than it needs to be.
- **Elevation** — six navy-tinted levels. Cards level-1, menus level-3, dialogs level-5. Tint comes from `#001B3E`, keeping shadows cool, not muddy.
- **Motion** — MD3 easing. 150ms for control states, 300ms emphasized for surfaces. No bounce, no overshoot — composed, not playful.

---

## 6. Components

Core library in `guidelines/comp-*`: Buttons (filled/tonal/outlined/text/destructive), Text fields, Selection controls (checkbox/radio/switch), Chips & segmented, Request card, Banners, Avatars & requester-type badges, Status stepper, Redaction tools, Queue table.

These are HTML/CSS reference specimens that establish the visual contract. As product UI kits are built, they should be promoted to reusable components reading the same tokens.

---

## 7. Conventions

- Token-first: no magic numbers in product code.
- Semantic aliases over raw MD3 roles.
- Status = dot/icon + label + color, never color alone.
- Mono only for machine-precise strings.
- Serif only for display/headline.
- Respect every requester type in copy and UI; never imply gatekeeping of lawful access.