docs/DESIGN_V2.md

71 lines · markdown

# Docket -  Design V2 (ground-up, elder-first) -  LOCKED 2026-06-27
 
The dark "forensic terminal" look is RETIRED as the design. New direction (Zion's pick): **"Large-print public service"** + **brass accent**. Built for an 80-year-old first; a high-schooler citing it second. Precise spec below -  implement EXACTLY; do not reintroduce monospace, dense tables, dark default, or a 10-item nav.
 
## Non-negotiables (the failures to fix)
- **NO monospace anywhere in the UI** (it reads techy/intimidating). Data figures use tabular-lining numerals in the UI sans, not a mono font.
- **NO dense data tables** as the primary display. Lists are big, simple, one-record-per-row cards with large text.
- **Default theme = light large-print** (this spec). Dark + Plain remain optional toggles only.
- **Nav consolidated** from ~10 items to a few plain ones (below).
- Plain language everywhere (≤8th-grade), plain dates ("June 26, 2026"), acronyms expanded.
 
## SOURCE THE AESTHETIC FROM ZION'S OWN SITES -  never a generated/AI design pack
The look must come from Zion's real, de-fingerprinted sites (zionboggan.com + treetrace.dev), NOT the ui-ux-pro-max pack, NOT Atkinson Hyperlegible / Public Sans / generic cards (that IS the fingerprint he's rejecting). Extracted from his live CSS:
- **His type trio (use it):** **Archivo** (bold display + headings + uppercase labels) · **Fraunces** (serif -  leads, long reading, optional headlines) · **JetBrains Mono** (DATA ONLY -  tallies, bill numbers, dates; never prose/nav).
- zionboggan.com = light, white/near-black + Tango palette (#204A87 #4E9A06 #8F5902 #A40000). treetrace.dev = dark ink #0B0C0E/#121316 + paper #F2EFE9 + cobalt #2E5BFF.
 
## Color -  Docket default (light, his palette, neutral, AAA target)
```
--bg:            #FFFFFF   /* white page (max contrast / familiar) */
--surface:       #F7F4ED   /* his warm paper tone for cards/sections */
--text:          #0B0C0E   /* his ink near-black, ~18:1 on white */
--text-soft:     #44423D   /* secondary, >=7:1 */
--border:        #D8D2C4   /* warm visible border */
--accent:        #8F5902   /* HIS amber/ochre (Tango) -  links + small text, ~6:1 on white; neutral, brass-adjacent */
--accent-strong: #CE5C00   /* his deeper ochre for large fills (dark text on it) */
--accent-wash:   #FBF3DF   /* faint amber for active/selected */
--focus:         #0B0C0E   /* 3px focus ring */
--yea:           #4E7A06   /* his Tango green, slightly muted -  PASS, always with a text label */
--nay:           #A40000   /* his Tango red, used SMALL for FAIL only -  never as a dominant/party color */
```
Dark mode = his treetrace treatment (ink #0B0C0E/#121316 + cobalt #2E5BFF + paper text). Plain = max-contrast. Both stay as toggles; light is DEFAULT.
 
## Type -  his trio (mono is DATA-ONLY, not banned, just constrained)
- **Headings / display / labels:** **Archivo** (700-900, can be uppercase for kicker labels).
- **Leads / long-form reading:** **Fraunces** (serif) -  gives the credible "research publication" feel.
- **Data tokens only:** **JetBrains Mono** for vote tallies, bill numbers, dollar amounts, dates (tabular). NOT for nav, body prose, or buttons.
- **Sizes (elder-first scale):** body/lead **20px** (line-height 1.55-1.65); min text anywhere **16px**; H1 **34-42px**; H2 26-28px; H3 20-22px.
- The elder-friendliness comes from SCALE + SIMPLICITY + WHITESPACE applied to HIS aesthetic -  not from swapping his fonts for a generic legibility font.
 
## Layout
- **Single column**, max reading width ~720px (text) / ~860px (lists); generous whitespace (section spacing 32-48px).
- **Big tappable elements:** primary buttons/cards **>=56px** tall; all targets **>=44px**; clear 2px borders; obvious hover + 3px focus ring; links underlined.
- **Breadcrumbs** on every sub-page (Home / Bills / H.R. 22) + a large **"← Back"** affordance.
- One clear **primary action** per screen.
- Reserve space for async content (no layout shift); skeletons for any server fetch (perceived speed).
 
## Navigation / IA (the "mapping" fix)
- **Top bar (every page):** large **Docket** wordmark (links Home) · a prominent **Search** (big, labeled, always reachable) · a **Menu**.
- **Primary nav -  6 plain items, big labels, active item clearly highlighted:**
  `Home` · `Bills` · `Votes` · `Representatives` · `Spending` · `States`
  (Rename: Members → **Representatives**. The Register feed = "What's happening", surfaced on Home. Calendar / Schedule / Executive / Federal Register move under Home cards or a clearly-labeled "More", NOT the primary bar.)
- **Mobile:** a clearly-LABELED "Menu" button (text + icon, >=44px) opening a big, simple full-screen menu with large rows -  not a tiny ambiguous hamburger.
- **Mode toggle:** small, out of the way (e.g. in the menu/footer): Standard (this large-print, default) / Dark / Plain.
 
## Per-page pattern (apply to ALL)
1. Breadcrumb + big Back.
2. Big H1 page title + one plain-language sentence under it.
3. (List pages) prominent Search + a few simple Sort/Filter controls (big, labeled).
4. Content as **big simple cards** -  each record shows its key facts in large text, the one most-important fact first (e.g. a vote: "H.R. 22 -  [title]" big, then "Passed, 414-12" then date + Source). NO multi-column dense tables.
5. Source link (rule #1) + **Cite this** on records.
- Home = welcoming hub: big headline, plain "what this is", a prominent Search, and 6-8 big cards to the sections + a "How to cite" note.
 
## Keep (don't lose)
All data, neutrality gate (no adjectives, source on every fact, no comments, muted/never-saturated party colors), the Cite-this feature, search+sort, the perf/latency work (KEEP `revalidate`/ISR caching -  do NOT reintroduce `force-dynamic`), responsive (no overflow at 390px).
 
## Build order (controlled -  verify the LOOK before propagating)
1. Design system: tokens above + Public Sans/Atkinson fonts + set light large-print as DEFAULT (Dark/Plain stay toggles). New simplified header/nav + mobile menu. Breadcrumb + Back components. Big-card + big-button + big-search components.
2. Rebuild HOME + ONE list page (Bills) + ONE detail page (a bill) as the TEMPLATE in this language.
3. **STOP -  screenshot home + the two template pages; overseer shows Zion for approval.**
4. After approval: propagate the pattern to every remaining page (Votes, Members→Representatives, Spending, States, Calendar, Executive, Search, etc.).
5. QA crawl CLEAN (no overflow/#418) + all 3 modes work + AAA contrast on default.

1	# Docket - Design V2 (ground-up, elder-first) - LOCKED 2026-06-27
2
3	The dark "forensic terminal" look is RETIRED as the design. New direction (Zion's pick): "Large-print public service" + brass accent. Built for an 80-year-old first; a high-schooler citing it second. Precise spec below - implement EXACTLY; do not reintroduce monospace, dense tables, dark default, or a 10-item nav.
4
5	## Non-negotiables (the failures to fix)
6	- NO monospace anywhere in the UI (it reads techy/intimidating). Data figures use tabular-lining numerals in the UI sans, not a mono font.
7	- NO dense data tables as the primary display. Lists are big, simple, one-record-per-row cards with large text.
8	- Default theme = light large-print (this spec). Dark + Plain remain optional toggles only.
9	- Nav consolidated from ~10 items to a few plain ones (below).
10	- Plain language everywhere (≤8th-grade), plain dates ("June 26, 2026"), acronyms expanded.
11
12	## SOURCE THE AESTHETIC FROM ZION'S OWN SITES - never a generated/AI design pack
13	The look must come from Zion's real, de-fingerprinted sites (zionboggan.com + treetrace.dev), NOT the ui-ux-pro-max pack, NOT Atkinson Hyperlegible / Public Sans / generic cards (that IS the fingerprint he's rejecting). Extracted from his live CSS:
14	- His type trio (use it): Archivo (bold display + headings + uppercase labels) · Fraunces (serif - leads, long reading, optional headlines) · JetBrains Mono (DATA ONLY - tallies, bill numbers, dates; never prose/nav).
15	- zionboggan.com = light, white/near-black + Tango palette (#204A87 #4E9A06 #8F5902 #A40000). treetrace.dev = dark ink #0B0C0E/#121316 + paper #F2EFE9 + cobalt #2E5BFF.
16
17	## Color - Docket default (light, his palette, neutral, AAA target)
18	```
19	--bg: #FFFFFF /* white page (max contrast / familiar) */
20	--surface: #F7F4ED /* his warm paper tone for cards/sections */
21	--text: #0B0C0E /* his ink near-black, ~18:1 on white */
22	--text-soft: #44423D /* secondary, >=7:1 */
23	--border: #D8D2C4 /* warm visible border */
24	--accent: #8F5902 /* HIS amber/ochre (Tango) - links + small text, ~6:1 on white; neutral, brass-adjacent */
25	--accent-strong: #CE5C00 /* his deeper ochre for large fills (dark text on it) */
26	--accent-wash: #FBF3DF /* faint amber for active/selected */
27	--focus: #0B0C0E /* 3px focus ring */
28	--yea: #4E7A06 /* his Tango green, slightly muted - PASS, always with a text label */
29	--nay: #A40000 /* his Tango red, used SMALL for FAIL only - never as a dominant/party color */
30	```
31	Dark mode = his treetrace treatment (ink #0B0C0E/#121316 + cobalt #2E5BFF + paper text). Plain = max-contrast. Both stay as toggles; light is DEFAULT.
32
33	## Type - his trio (mono is DATA-ONLY, not banned, just constrained)
34	- Headings / display / labels: Archivo (700-900, can be uppercase for kicker labels).
35	- Leads / long-form reading: Fraunces (serif) - gives the credible "research publication" feel.
36	- Data tokens only: JetBrains Mono for vote tallies, bill numbers, dollar amounts, dates (tabular). NOT for nav, body prose, or buttons.
37	- Sizes (elder-first scale): body/lead 20px (line-height 1.55-1.65); min text anywhere 16px; H1 34-42px; H2 26-28px; H3 20-22px.
38	- The elder-friendliness comes from SCALE + SIMPLICITY + WHITESPACE applied to HIS aesthetic - not from swapping his fonts for a generic legibility font.
39
40	## Layout
41	- Single column, max reading width ~720px (text) / ~860px (lists); generous whitespace (section spacing 32-48px).
42	- Big tappable elements: primary buttons/cards >=56px tall; all targets >=44px; clear 2px borders; obvious hover + 3px focus ring; links underlined.
43	- Breadcrumbs on every sub-page (Home / Bills / H.R. 22) + a large "← Back" affordance.
44	- One clear primary action per screen.
45	- Reserve space for async content (no layout shift); skeletons for any server fetch (perceived speed).
46
47	## Navigation / IA (the "mapping" fix)
48	- Top bar (every page): large Docket wordmark (links Home) · a prominent Search (big, labeled, always reachable) · a Menu.
49	- Primary nav - 6 plain items, big labels, active item clearly highlighted:
50	`Home` · `Bills` · `Votes` · `Representatives` · `Spending` · `States`
51	(Rename: Members → Representatives. The Register feed = "What's happening", surfaced on Home. Calendar / Schedule / Executive / Federal Register move under Home cards or a clearly-labeled "More", NOT the primary bar.)
52	- Mobile: a clearly-LABELED "Menu" button (text + icon, >=44px) opening a big, simple full-screen menu with large rows - not a tiny ambiguous hamburger.
53	- Mode toggle: small, out of the way (e.g. in the menu/footer): Standard (this large-print, default) / Dark / Plain.
54
55	## Per-page pattern (apply to ALL)
56	1. Breadcrumb + big Back.
57	2. Big H1 page title + one plain-language sentence under it.
58	3. (List pages) prominent Search + a few simple Sort/Filter controls (big, labeled).
59	4. Content as big simple cards - each record shows its key facts in large text, the one most-important fact first (e.g. a vote: "H.R. 22 - [title]" big, then "Passed, 414-12" then date + Source). NO multi-column dense tables.
60	5. Source link (rule #1) + Cite this on records.
61	- Home = welcoming hub: big headline, plain "what this is", a prominent Search, and 6-8 big cards to the sections + a "How to cite" note.
62
63	## Keep (don't lose)
64	All data, neutrality gate (no adjectives, source on every fact, no comments, muted/never-saturated party colors), the Cite-this feature, search+sort, the perf/latency work (KEEP `revalidate`/ISR caching - do NOT reintroduce `force-dynamic`), responsive (no overflow at 390px).
65
66	## Build order (controlled - verify the LOOK before propagating)
67	1. Design system: tokens above + Public Sans/Atkinson fonts + set light large-print as DEFAULT (Dark/Plain stay toggles). New simplified header/nav + mobile menu. Breadcrumb + Back components. Big-card + big-button + big-search components.
68	2. Rebuild HOME + ONE list page (Bills) + ONE detail page (a bill) as the TEMPLATE in this language.
69	3. STOP - screenshot home + the two template pages; overseer shows Zion for approval.
70	4. After approval: propagate the pattern to every remaining page (Votes, Members→Representatives, Spending, States, Calendar, Executive, Search, etc.).
71	5. QA crawl CLEAN (no overflow/#418) + all 3 modes work + AAA contrast on default.