# UX Design Overview

# Purpose

This directory contains the UX design artifacts for GreenGrass — a platform for managing grassroots political elections in the global south. The UX design phase follows the completion of 12 product specifications and a system architecture document.

The core UX challenge: 10 distinct personas across radically different contexts share one application. A volunteer knocking doors on a low-end Android phone in rural India needs a completely different interface than an Org Admin configuring compliance settings on a desktop in Puerto Rico. The UX must serve both without compromise.

# Reading Order

# Phase 1: Information Architecture

Start here. The IA documents define the global structure everything else hangs off of.

1. Navigation Model — How the platform organizes its features into a navigable structure. Defines the desktop shell (hybrid top bar + sidebar), mobile layout (bottom tabs), and field mode (full-screen takeover). The most critical IA document.

2. Screen Inventory — Comprehensive catalog of every screen in the platform (~240 screens across 22 feature areas). Each entry identifies personas, offline capability, and mobile optimization. The master reference for wireframing and implementation scoping.

3. Persona Views — How the platform renders differently for each of the 10 personas. Defines home screens, sidebar sections, mobile tabs, and what each persona doesn't see. The "role-adaptive UX" specification.

4. URL Structure — Maps the screen inventory to SvelteKit routes. Defines six layout groups (public, auth, app, field-mode, portal, wizard), routing patterns, auth guards, and offline-capable routes.

# Phase 2: Global Patterns

Recurring UI patterns that apply across the entire platform.

5. Pattern Catalog — 20 recurring UI patterns: list views, detail views, builders, forms, wizards, dashboards, maps, check-in tools, field mode, and more. Cross-cutting concerns: empty states, loading, error states, accessibility.

6. Offline & Sync Patterns — Five connectivity states, data freshness indicators, pending changes queue, conflict resolution, pre-loading strategy, battery and data usage awareness, shift sync lifecycle.

7. Notification Patterns — Notification center, four priority levels, delivery channels (in-app, push, email, SMS), per-persona defaults, email digests, election day notification behavior, Do Not Disturb.

8. Search Patterns — Global search with type-ahead, contextual search per feature area, filter patterns, saved searches, encryption constraints on search (BYOK tenants).

9. Settings & Help Patterns — Three-tier settings hierarchy (org/feature/personal), contextual help panels, knowledge base, AI concierge, language switching, onboarding flows, keyboard shortcuts.

10. Security UX Patterns — Duress mode sanitization rules per feature area, BYOK key generation ceremony, panic button behavior, passkey auth flows, session management, trusted contact recovery, device authorization.

# Phase 3: Design System Foundations

The visual and component foundations.

11. Foundations — 8px spacing scale, semantic color token system, Inter type scale, 4/8/12-column grid, elevation layers, border radius, Lucide iconography, motion tokens, z-index scale, density modes.

12. Theming Strategy — Per-tenant branding (color + logo), automatic derivative color generation, CSS custom property cascade, RTL via CSS logical properties, dark mode token mapping, high contrast mode, large text mode, reduced motion, theme composition layers.

13. Component Inventory — ~125 components across 13 categories: primitives, typography, buttons, forms, layout, navigation, data display, feedback, overlays, messaging, field mode, dashboard, specialized. Naming conventions, state definitions, composition patterns.

14. Responsive Strategy — Five breakpoints (640/768/1024/1280/1536px), mobile-first CSS, component adaptation tables, Capacitor native API usage, safe areas, performance budgets (150KB JS, 2s FCP on 3G), code splitting strategy, testing matrix.

# Phase 4: Wireframes

Detailed screen specifications with ASCII wireframes for key screens and flows. Implementation-ready.

15. Navigation Shell — Desktop shell (sidebar expanded/collapsed, detail panel, notification drawer, RTL), mobile shell (per-persona tab bars, hamburger menu, "More" bottom sheet), field mode shell (walk list, door card, map, shift lifecycle), wizard shell, supporter portal shell. Responsive breakpoint transitions, interaction specs, accessibility notes.

16. Dashboards — All 11 dashboards: Campaign Overview (Org Admin), Field Operations (Field Director), Fundraising (Finance Director), Communications (Comms Director), Volunteer (Volunteer Coordinator), Data Quality (Data Manager), Compliance (Finance Director), GOTV War Room (election day, auto-refresh, dark mode), Team Lead, Candidate (curated/simplified), Alliance (cross-ref). Empty states, loading skeletons.

17. Field Mode — Complete shift lifecycle: pre-shift check, walk list (list + map views), door card with script and response capture, follow-up questions, "Not Home" quick result. Phone banking variant, voter registration variant, GOTV door card, ride request flow. End shift confirmation, sync screen, debrief. Crash recovery. Touch target specifications.

18. Onboarding — Org Setup wizard (5 steps: auth, org profile, team invites, configuration, review & launch), Volunteer Onboarding (4 steps: account, tour, training, ready), BYOK Key Generation wizard (5 steps with Shamir's Secret Sharing). Post-wizard "Getting Started" checklist.

19. Messaging — Desktop split view (conversation list + thread), mobile full-screen flows, compose, candidate briefings (structured/formatted), approval requests (approve/reject/comment inline), War Room channel (election day, system alerts, issue reports), offline messaging, encryption indicators.

20. Supporter Portal — Public donation page (pre-auth, tenant-branded), donation confirmation, portal home, donation history with recurring management, events with RSVP, communication preferences, public event page. Magic link + full account authentication tiers.

21. Alliance — Alliance Dashboard (aggregate metrics + per-org breakdowns, desktop + mobile), Member List with detail panel, Affiliation Request Form and Queue, Sharing Configuration (by category and by org views), Joint Campaign Setup wizard (4 steps, 4 campaign types, 3 governance models), Shared Analytics (cross-org charts and tables), GOTV Alliance Coordination (election day cross-org war room). Empty states for no-alliance, pending affiliation, and new alliance.

22. CRM / People — Contact List (filterable, persona-adaptive columns, desktop + mobile), Contact Detail (unified record with persona-specific tabs, activity timeline, offline partial), Contact Create/Edit (progressive disclosure, dupe detection on save), Segment Builder (visual query builder with live preview), Segment List, Dedup Review Queue (confidence-grouped), Dedup Side-by-Side Comparison (field-by-field merge with preview), Data Import Wizard (4-step: upload, column mapping, dedup preview, confirm), Import History, Data Export (field selection, format choice, audit logged), Data Quality Report (score breakdown, completeness by field, validity issues, staleness), Tag Management. Empty states.

23. Field Operations (Admin) — Canvassing: Campaign List/Create-Edit, Script Builder (split-pane with live preview, branching logic, score mapping), Turf Management Map (draw/select/assign turfs, completion color coding), Turf Auto-Generation (constraint-based with preview), Walk List Management (assign/reassign volunteers), Results Review (per-turf breakdown, support distribution, flagged interactions), Progress Map (full-width geographic view with active volunteer positions). Phone Banking: Campaign List/Create-Edit (BYOP/integrated dialer, segment-based call lists with exclusions), Script Builder (shared with canvassing + phone-specific steps), Progress Dashboard (real-time caller activity, call outcomes, support scores). Voter Registration: Drive List/Create-Edit (jurisdiction-driven), Jurisdiction Template Selector (country-specific registration forms with eligibility rules), Results Review (registration progress, follow-up pipeline, data issues). Empty states.

24. Fundraising (Admin) — Donation List/Detail (filterable, multi-currency, flagged donation variant), Donation Form Builder (split-pane with live preview, amount configuration, donor fields, appearance, payment methods), Form Preview, Embed Config (inline/modal/button types, domain allowlist), Fundraising Campaign List/Create-Edit (goal tracking, linked forms and communications), Recurring Donation Management (MRR metrics, status lifecycle, charge history, admin pause/cancel), Pledge Management (pledge lifecycle, reminder scheduling, fulfillment linking), Refund Processing (full/partial, alliance split reversal, cash manual handling), Cash Donation Recording (mobile-first, offline-capable, receipt photo), Cash Reconciliation (two-column matching, discrepancy tracking), Compliance Flag Review (severity-ordered, fraud indicators, approve/refund/block actions), A/B Test Setup/Results (variant configuration, statistical significance tracking), Alliance Split Configuration (percentage/fixed/threshold types, unanimous approval), Alliance Fundraising Report (per-org breakdown, disbursement history), Payment Processor Configuration (guided connect flow, test transactions, credential security), Year-End Statement Generator (bulk generation, email delivery, PDF download). Empty states.

25. Communications — Email Campaign List (status lifecycle, inline metrics), Email Campaign Builder (setup/audience/content/delivery sections, template selection, personalization tokens, pre-send checklist, subject A/B testing, automated campaign variant), Email Template Builder (block-based drag-and-drop, inline editing, compliance footer), Email Template Library (card grid with thumbnails, categories), SMS/WhatsApp Composer (channel toggle, character counter with segment tracking, WhatsApp quick reply buttons, time-of-day enforcement, frequency cap checks), Communication Analytics (cross-channel overview, email performance table, trend charts, audience health), Consent Management (channel × purpose matrix, consent expiry tracking, renewal requests, default rules per contact source), Communication Preferences (frequency caps, quiet hours with GOTV override, compliance disclaimers, sender identities), Unsubscribe Management (reason tracking, manual re-subscribe with audit), Email Sending Domain Config (DNS record generation, SPF/DKIM/DMARC verification). Empty states.

26. Social Media — Social Media Dashboard (connected accounts with follower counts, this week's performance metrics, upcoming scheduled posts, recent posts with cross-platform engagement), Post Composer (multi-platform with per-platform overrides, character counters, media with crop notes, compliance disclaimers, scheduling, approval routing), Post Calendar (month/week/list views, drag-to-reschedule, day detail panel), Post Analytics (per-post detail with per-platform breakdown and 48-hour performance chart, aggregate analytics with platform comparison and best posting times), Social Account Connection (OAuth flow, token status, permissions display), Platform-Specific Preview (side-by-side previews with per-platform warnings). Empty states.

27. Events — Event List (persona-adaptive admin vs volunteer/supporter views, event type icons, capacity indicators), Event Create/Edit (in-person/virtual/hybrid toggle, RSVP settings with open/invite-only/approval-required modes, capacity with waitlist, reminders, promotion links, staff assignment, fundraising integration, media), Event Detail (admin view with RSVP summary/staff/discussion thread, volunteer view with RSVP action/calendar/directions, post-event outcome variant), RSVP Management (full list with approval queue variant, bulk actions, guest tracking), Check-in Tool (mobile-first offline-capable with progress counter, alphabetical list with tap-to-check-in, QR scan mode with camera, walk-in registration, 56px touch targets, haptic feedback, 10-second undo), Event Metrics (RSVP/attendance/walk-in/show-rate metrics, RSVP source breakdown, check-in timeline chart, fundraising data, CRM impact, comparison to similar events, post-event action buttons), Virtual Event Setup (platform selection, unique link generation for attendance tracking, recording sharing), Post-Event Survey Builder (6 question types, drag-to-reorder, results visualization with response distribution, volunteer-interest CRM linking). Empty states.

28. Press & Media — Media Contact List/Detail (press-specific CRM fields, relationship dots, interaction history with pitch/response/coverage timeline, pitch success rate), Media List Management (dynamic criteria-based + static curated lists), Press Release Builder (split-pane with structured template: headline/dateline/body/quotes/boilerplate/contact, embargo support, versioning, compliance disclaimer, approval workflow), Press Release Preview (full distribution format), Press Release Distribution (media list + individual selection, personalization, attachments, embargo tracking), Media Advisory Builder (WHO/WHAT/WHEN/WHERE structured template with event auto-fill), Statement Builder (streamlined rapid-response, urgent flag with push notification, emergency bypass for OA/CD), Media Kit Management (asset cards with public/gated access levels, gated access creates CRM contacts, download tracking), Coverage Log (manual entry with headline/outlet/journalist/sentiment/format/topics, linked to pitch/release), Coverage Analytics (sentiment distribution, format breakdown, topic analysis, pitch-to-coverage rate, journalist responsiveness, coverage over time), Endorsement Pipeline (Kanban: identified→approached→considering→committed→public, drag-and-drop, "Public" triggers announcement workflow with press release + social post), Endorsement Detail (stage progress, endorser profile, quote, photo, timeline, assignment), Talking Points Library (topic-organized accordion, versioned with diff, team distribution via messaging, candidate briefing integration), Interview Schedule (upcoming/past/requests tabs, auto-assembled prep with talking points + journalist history + recent outlet coverage, accept/decline/reply for requests, post-interview outcome logging), Spokesperson Configuration (designated spokespeople with topic areas, contact routing rules, press contact info for releases). Empty states.

29. Activism — Activism Campaign List (letter/email, petition, public comment types with type-specific metrics), Letter/Email Action Setup (target info, talking points with priority ordering for AI, template message, public page configuration), Petition Setup (petition statement, signature goal with goal-reached behavior, signer information fields with visibility controls), Public Comment Campaign Setup (regulatory body, docket number, deadline with auto-close, submission method: platform-direct/manual-download/both), Action Page — Public (mobile-first two-step flow: supporter info → AI message generation, action counter social proof, tenant-branded compliance disclaimer), Petition Page — Public (mobile-first signing with progress bar, truncated petition text with expand, recent signatures with privacy-preserving display), AI Message Generation Preview (unique AI-written message from talking points + personal connection, explicit approval checkbox, edit/regenerate/fallback-to-template, 3 regeneration limit, transparency disclosure), Activism Campaign Analytics (type-specific metrics, actions-over-time chart, geographic distribution map + table, per-supporter action feed with CRM links, message viewing), Delivery Event Documentation (delivery method/location/recipient, photo evidence with camera capture, attached documents, target response tracking, staff present, related press coverage linking, partial offline support). Empty states.

30. GOTV Admin — GOTV Universe Builder (criteria-based segment builder with include/exclude rules, support score and voting history filters, geographic breakdown, tier segmentation for priority ordering, finalize-and-lock workflow), Early Voting Data Upload (CSV/Excel upload with column mapping, voter ID primary match key with name+DOB fallback, match preview showing universe impact, cumulative uploads with history and undo), Volunteer Staging Setup (map with location pins + detail panel, capacity tracking with visual bar, contact person and hours, customizable supplies checklist, volunteer roster per location), GOTV Turf Cutting (interactive map with draw/select/split tools, supporter density heatmap overlay, auto-generate with configurable parameters: contacts per turf, max completion time, optimization priority, multi-pass scheduling for morning/afternoon/evening, volunteer assignment, dynamic re-cutting on election day), Election Day Comms Plan (visual timeline of communication waves, per-wave configuration: time, auto/manual trigger, channel SMS/WhatsApp/Email, audience targeting with dynamic "who haven't voted" filter, personalization tokens, WhatsApp quick reply buttons, GOTV quiet hours override, election day live send controls), Poll Watcher Registry (list with status badges ○◐●, assigned/backup polling locations, jurisdiction requirements and deadline warnings, export roster for filing), Poll Watcher Credential Tracking (credential number/dates/document upload, verification status, printable summary), Ride Coordination Dispatcher (map + split panel with pending requests and available drivers, priority ordering with urgent flags for wait time and accessibility, smart driver matching by proximity/vehicle/workload, multi-passenger optimization, status tracking: Pending→Assigned→En Route→Transporting→Completed, auto-refresh, multiple ride sources), Poll Watcher Issue Queue (severity-ordered: Critical/High/Medium with color + icon badges, category filter: Voter Access/Equipment/Campaign Violation/Wait Times/Accessibility/Intimidation, issue detail with photo/video evidence, escalation routing to legal/election protection/electoral commission, internal timestamped notes, resolution audit trail, auto-refresh with sound notification for Critical), Turnout Dashboard Map View (full-width choropleth map color-coded by turnout rate red→green relative to target, overlay toggles for turf boundaries/canvassers/staging/polling locations, click-turf detail panel with per-tier voted counts and data source confidence, auto-refresh 60s), Turnout Dashboard Segment View (table with turnout by support tier/geography/demographics/custom, target vs actual with gap column and ⚠ flags, turnout-over-time chart with target pace dotted line, drill-down to individual contacts), Reallocation Suggestions (platform-generated prioritized suggestions: canvasser shifts, phone bank surges, targeted SMS, each with rationale citing specific data, approve/modify/reject controls, previously actioned audit trail, regenerate from latest data), Election Night Results Entry (mobile-first numeric entry per race per location, pre-filled candidates from staff config, partial vs final status, validation against registered voter counts, timestamp auto-recorded), Election Night Results Dashboard (candidate bar chart with vote counts and percentages, reporting progress tracker, results timeline chart showing trend as results come in, per-location table with status, internal comparison against support score predictions, map view toggle, multi-race tabs, 30-second auto-refresh), Post-Election Analysis (tabbed: Turnout with segment/region tables and target comparison, Operations with door knock/phone/ride metrics and contact rates by region, Volunteers with per-volunteer performance, Model Validation comparing support scores vs actual turnout with accuracy assessment, Resources with staging utilization and operational efficiency, PDF export), Staging Location Check-in (mobile-first for Team Lead, progress counter with visual bar, not-checked-in list prioritized with phone numbers and turf assignments, tap-to-check-in with haptic confirmation and 10-second undo, QR scan option, 56px touch targets, report issue and contact Field Director). Empty states. Cross-references: DASH-008 War Room Dashboard, GOTV field mode screens (Door Card, Walk List, Chase Call), ALLY-008 Alliance GOTV Coordination.

31. Settings & Admin — Org Profile & Branding (organization name/short name, logo upload with size preview, primary/accent color picker with live preview, default/additional languages, timezone), Role Template Editor (system + custom templates, permission matrix with feature areas as rows and View/Create/Edit/Delete/Export/Admin as columns, collapsible feature sections, clone and reset to default, member count per role), Permission Override Panel (per-user additive-only overrides with required reason for audit trail, added-by tracking), Staff Management List (filterable by role/status, Active/Invited/Deactivated badges, row actions: edit role, resend invite, reset passkey, deactivate, view overrides, view activity), Staff Invite Flow (email + name, role selection with plain-language can/cannot summary, optional geographic scope restriction to specific regions), Geographic Scope Configuration (map with shaded regions + region list with contact counts, jurisdiction level selector: Country/State/District/County/Precinct/Custom), Campaign Period Configuration (campaign name, start/end/election dates, status with day count, previous periods archive), Compliance Configuration (jurisdiction + framework selection, enforced rules checklist with jurisdiction-required rules locked, enforcement behavior: block/warn/flag), Contribution Limits Configuration (per-donor-type per-cycle limits table: Individual/Corporation/PAC/Self-Funding, aggregation method, over-limit behavior: block/flag/partial-accept), Disclaimer Text Configuration (primary disclaimer with per-channel application checkboxes, additional disclaimers, per-language translations), Data Retention Policy (per-data-type retention rules with retain period and expiry action: auto-delete/archive/manual, post-campaign cleanup behavior, minimum retention for compliance), Integration Settings Hub (card grid by category: Communications/Social/Payments/Maps/Video, status/provider/sync time per card), WhatsApp Business Setup (phone number, API token, test connection, message template management with approval status), SMS Provider Configuration (provider selection, credentials, phone numbers, test delivery), Email Domain Configuration (cross-ref COMM-010, DNS records, SPF/DKIM/DMARC verification), Social Media Account Connections (cross-ref SOCIAL-005, per-platform OAuth), Billing & Subscription (current plan with usage metrics, payment method, billing history with invoice downloads, billing contact), Audit Trail Viewer (searchable filterable log of all user actions: logins, exports, permission changes, settings changes, expandable row detail with IP/user agent, non-deletable tamper-proof, CSV/JSON export), Security Settings (three-tier Standard/Enhanced/Maximum, passkey/MFA requirements, session timeout, IP allowlist with field mode exemption, incident response email alerts for suspicious logins/exports/permission changes, duress mode and trusted contact recovery collapsed sections), Encryption Key Management (BYOK for Maximum tier, current key with algorithm/status/Shamir share holders, key rotation ceremony requiring 3-of-5, encrypted key backup export, key history with rotation audit), API Key Management (named keys with scoped permissions per feature area + read/write, IP restrictions, expiration, usage tracking, key shown once on generation), Webhook Configuration (named webhooks with URL/secret/event selection, retry policy, test webhook, delivery log with response codes and timing, success rate tracking). Empty states.

32. Authentication — Login with Passkey (single CTA centered card, <3 second biometric login, tenant-branded with org logo + name, "What's a passkey?" expandable), Login Fallback (magic link with 15-minute expiry and 60-second resend cooldown + SMS OTP with 6-digit auto-submit and 10-minute expiry, rate limiting 3 per 15 minutes), Account Recovery via Trusted Contacts (2-of-3 approval default, 24-hour cooling-off period with countdown, old passkeys invalidated on recovery, "No, This Isn't Them" cancels immediately, no admin-initiated recovery), Passkey Registration (guided enrollment with platform-specific instructions for iOS Face ID/Touch ID/Android biometric/security key, "What's a passkey?" plain-language explanation, duress passkey option for Maximum security tier), Trusted Contact Setup (2-5 contacts from same org, contacts notified when added, removal requires re-auth), Device Authorization (QR code with 5-minute expiry + manual alphanumeric code, approval from existing device with device details, new device appears in device list), Session Expired (data preserved in local storage, one-tap re-authenticate, sensitive action re-auth variant showing action description and timeout context). Edge case states (no passkey found, rate limited, no trusted contacts, incompatible device, expired QR).

33. User Profile — Personal Profile (name, avatar upload/remove, phone with verification, email read-only/admin-managed, language and timezone, role and organization display, last login), Notification Preferences (channel × type matrix: In-App/Push/Email/SMS columns × Messages/Approvals/Assignments/Reminders/Campaign Updates/Security Alerts rows, quiet hours with start/end time and GOTV override toggle, email digest frequency: real-time/daily/weekly), Security Settings — Personal (registered devices list with platform/browser/last used and remove requiring re-auth, trusted contacts management with add/remove, security summary checklist with ✓/○ indicators for passkey/trusted contacts/recovery/devices, duress passkey setup for Maximum tier), Language Preference (instant-apply radio buttons, RTL auto-flip, bilingual header showing current and new language, tenant-controlled language list), Tenant Switcher (org cards with logo/role/last active time, full context switch clearing local state, [+ Join Another Org] with invite code entry). Empty states.

34. Support & Help — Knowledge Base Browser (full-text search with instant results, role-filtered articles prioritized by user's persona, category cards matching sidebar structure, popular/recently updated articles, desktop grid / mobile list), Knowledge Base Article (formatted content with table of contents sidebar, related articles, thumbs up/down feedback, partial offline with cached text/images, deep links to platform screens, breadcrumb navigation), AI Concierge Chat (context-aware knowing current screen and user role, responses with article links + direct action links, chat history persisted, desktop side panel / mobile full screen, escalation to human support for premium tenants, quick suggestion chips), Training Module List (volunteer view with Required/Recommended sections and progress bars, admin view with per-module completion rates and per-volunteer matrix), Training Module Content (sequential lessons with progress indicator, text/images/video content types, offline caching for text and images, bookmark and resume, estimated time), Training Quiz (one question at a time with progress dots, configurable pass threshold, retake option, offline-capable with sync on reconnect, results review with correct answers and explanations), Certification Status (volunteer view with module cards showing ✓ completed/◐ in progress/○ not started, admin cross-tab matrix with volunteer rows × module columns, expiration tracking with renewal prompts), Training Content Editor (module settings with title/description/requirements, lesson list with drag-to-reorder, quiz question editor with 4 question types, assignment targeting all/specific roles/specific people, versioning with draft/published states, save draft and publish actions). Empty states.

35. Public Pages — Candidate Profile Page (/p/[slug] short URL, candidate photo/name/title/tagline, bio with expandable full text, dynamic endorsements from pipeline, upcoming public events from events module, donate and volunteer CTAs, social media links, SEO meta tags and Open Graph, tenant compliance disclaimer), Organization Profile Page (/o/[slug] short URL, org logo/name/mission, hero image, get involved CTAs for donate/volunteer/events, dynamic upcoming events from events module, recent press coverage from coverage log, compliance disclaimer), Volunteer Signup Page (minimal required fields: name and email only, optional phone, interest checkboxes for role matching: canvassing/phone banking/events/data entry/other, availability grid, CRM integration creating or matching contact tagged "Prospective Volunteer", consent opt-in not pre-checked, confirmation screen with donation upsell and social share buttons), Media Kit Page (press contact info with name/title/email/phone, downloadable assets organized by category: logos PNG/SVG, photos hi-res, documents PDF, optional gated access requiring email which creates CRM contact tagged "Media," download tracking per asset, recent press coverage). Cross-references: PUB-003 Supporter Portal (supporter-portal.md + fundraising.md), PUB-004 Public Event Page (events.md EVT-003), PUB-005 Action Page (activism.md ACT-005), PUB-006 Petition Page (activism.md ACT-006). Empty states.

36. Content Operations — The content pipeline, added after the audit: Content Dashboard (today's schedule with pipeline state, what waits on you, topics from talking points), Content Review (round history, comparison between rounds, required revision comments, escalation), Approval Queue (sorted by scheduled time, batch approval) and Approval (current and previous round side by side; mobile). Redrawn from the review screens of a prototype built for managing content creators, which GreenGrass does not do.

# Wireframe Audit

37. Wireframe Audit Report — Structural audit of all 21 wireframe documents. Executive summary with coverage stats (236 screens inventoried, 15 formerly missing now added, 9 docs normalized to standard structure). Per-document gap analysis, design system token assessment, offline coverage grading, terminology audit. Appendix A: 89 consolidated open questions across all docs, categorized and deduplicated. Appendix B: consolidated design decisions from all docs with contradiction analysis.

38. Screen Index — Cross-reference of all 240 screen IDs to their wireframe location with status (Complete / Covered / Cross-ref / Missing).

# UX Principles

These principles guide all design decisions for GreenGrass.

# 1. The volunteer in the field comes first

Every design decision is pressure-tested against the hardest user: a volunteer on a low-end Android phone with intermittent connectivity, walking door-to-door in a rural area. If a pattern doesn't work for them, it doesn't ship. Desktop admin interfaces are important but must never compromise the field experience.

# 2. Invisible complexity

10 personas share one application, but no user should feel the weight of the others. Features outside a user's access are absent — not greyed out, not hidden behind permission dialogs, but truly invisible. The Volunteer sees a simple, focused app. The Org Admin sees a full-featured platform. Neither knows the other's view exists.

# 3. Offline is not an error state

Offline mode is a first-class operating condition, not a degraded fallback. The UI should communicate connectivity status clearly but never make the user feel that they're using a broken version of the app. Field operations work fully offline. Data syncs when it can.

# 4. Stability over dynamism in navigation

The navigation structure stays stable regardless of connectivity, context, or time of day. Items don't appear and disappear as conditions change. Offline-unavailable features are greyed out with a badge, not removed. Users build muscle memory for where things are — that memory must be reliable.

# 5. Security is invisible until it matters

The security architecture (5-tier model, BYOK encryption, passkey auth, duress mode) is substantial, but users shouldn't feel its weight during normal operation. Login should be one tap (passkey). Encryption should be automatic. Security surfaces (audit trail, key management, duress mode) are available but not prominent. The exception: when security needs attention (compromised passkey, key rotation, active threat), the UI must be unambiguous and direct.

# 6. Respect the device

Mobile is not a shrunken desktop. Mobile screens are designed for mobile — large touch targets, vertical scrolling, one-handed operation. Desktop screens use the space — data tables, side-by-side panels, drag-and-drop. The same feature may have significantly different interfaces on each platform, and that's correct.

# 7. RTL is structural, not decorative

Right-to-left support is built into every layout decision from day one, not retrofitted. Sidebar position, tab bar order, icon direction, text alignment, breadcrumb direction — all defined in terms of logical properties (inline-start/inline-end), not physical ones (left/right).

# 8. Election day is a different app

When GOTV operations activate, the platform transforms. Dashboards change, notification priorities shift, new screens appear, field mode switches to GOTV-specific flows. This transformation is designed, not improvised — it's part of the navigation model and persona views.

# Glossary

# Cross-References to Specs

# Design Decisions

UX-specific decisions are recorded in decisions/ux-decisions.md. This document covers wireframe structural conventions, design token integration approach, offline behavior specification, terminology conventions, and screen ID assignment.

Key decisions already made during Phase 1 IA work: