Campaign_Tracker/_bmad-output/planning-artifacts/ux-design-specification.md

---

stepsCompleted:

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14 lastStep: 14 inputDocuments:
• _bmad-output/planning-artifacts/prd.md
• _bmad-output/planning-artifacts/validation-report-2026-04-03.md
• _bmad-output/planning-artifacts/client-database-plan-extract.txt

---

UX Design Specification Campaign_Tracker App

Author: Daniel Date: 2026-04-03

---

Executive Summary

Project Vision

Create a browser-based municipal election-services operations platform that modernizes an existing Access production workflow without changing legacy tables. The UX must reduce operational friction across client services, production, transportation, and support while preserving trusted workflow continuity.

Target Users

• Client Services Coordinators: configure municipality accounts and election-cycle services.
• Production Leads: monitor milestones, dependencies, and exception recovery.
• Transportation Coordinators: plan daily and upcoming pickup/delivery operations.
• Operations Administrators: manage governance, defaults, permissions, and compatibility controls.
• Support Analysts: investigate data/reporting issues and maintain audit-aligned corrections.

Key Design Challenges

• Support complex, date-critical election workflows without overwhelming users.
• Keep permanent municipality data and election-cycle operational data clearly separated but visibly connected.
• Provide dense operational tables/reports that remain readable, fast, and keyboard-accessible.
• Preserve legacy trust by making extension-layer behavior transparent and auditable.

Design Opportunities

• Build role-specific task views so each team sees only the highest-value next actions.
• Use timeline-first UX patterns to surface schedule risk early and reduce missed milestones.
• Provide clear traceability UI (source links, status history, reason codes) to improve confidence in reporting.
• Turn high-friction reporting into one-click operational exports with predictable filters and presets.

Core User Experience

Defining Experience

The core experience is election-cycle operations planning and execution in one continuous workspace: set up municipality cycle details, track milestones, resolve blockers, and produce operational outputs without context switching. The primary interaction to optimize is “commit a status update with confidence” so teams can act quickly without creating downstream risk.

Platform Strategy

• Primary and only platform (MVP+current scope): authenticated web app for PC/desktop operations environments.
• Input model: keyboard + mouse first, with dense grid/timeline interaction and rapid filtering.
• Tablet/mobile interfaces are out of scope.
• Offline: not required for MVP; UI must show explicit reconnect/sync state and safe retry behavior.
• Architecture-facing UX rule: compliance and dependency checks appear pre-commit, in flow.

Effortless Interactions

• Single-workspace election setup with prior-cycle defaults and progressive required-field checks.
• “Next Best Action” prompts per record to reduce decision latency.
• Inline blocker diagnostics: why blocked, impact, and one-click jump to corrective field/action.
• Fast row-level status updates, plus guarded bulk actions for repetitive operational work.
• Saved report presets (transport/sort) with deterministic filters and export parity.
• In-flow trust cues: actor, timestamp, reason code, policy-state chips (clearance/residency relevance).

Critical Success Moments

• Setup success: coordinator completes a valid election-cycle plan without external checklist lookup.
• Prevention success: production lead resolves a dependency before cutoff after risk is surfaced early.
• Dispatch success: transport coordinator generates an accurate date-sorted run in one pass.
• Trust success: support traces disputed output to source history in under 2 minutes.
• Governance success: admin executes privileged updates with visible policy checks and no workflow detour.
• Recovery success: blocked/late milestone resolved from the same screen where risk appears.

Experience Principles

• Design for operational clarity first; aesthetics support comprehension, not the reverse.
• Keep timeline truth visible, actionable, and prioritized by urgency/risk.
• Reduce interaction cost for repetitive work (fewer clicks, fewer mode switches, fewer surprises).
• Make traceability and policy-state visible at decision points, not after the fact.
• Preserve legacy mental models while delivering materially faster, safer execution.
• Every critical action should answer: what changed, why, by whom, and what is next.

Desired Emotional Response

Primary Emotional Goals

• Primary: users feel in control under pressure.
• Secondary: users feel confident that data, status, and outputs are trustworthy.
• Supporting: users feel efficient and focused, not burdened by process overhead.
• Protective: users feel psychologically safe to correct mistakes without fear of hidden consequences.

Emotional Journey Mapping

• First-use: “I understand what matters right now” (clarity over overwhelm).
• In-flow execution: “I can act quickly and safely” (speed with confidence).
• Completion: “I did this correctly” (verification and closure).
• Error/block state: “I know exactly what to fix next” (guided recovery, low anxiety).
• Policy/dependency failure: “I understand why this is blocked and what unlocks it” (explainable constraints).
• Cutoff-day pressure moment: “I can prioritize the highest-risk item immediately” (calm urgency, not panic).
• Return use: “This is predictable and dependable” (habit-forming trust).

Micro-Emotions

• Prioritize: confidence, relief, momentum, trust, accomplishment.
• Minimize: ambiguity, hesitation, anxiety, blame, rework frustration.
• Add subtle positive cues: readiness confirmations, completion states, transparent status provenance, and safe-undo confidence for reversible actions.
• Tone by severity:
  • Info = calm and concise
  • Warning = action-oriented and specific
  • Critical = urgent but non-alarmist, with immediate next step

Design Implications

• Confidence -> show source, actor, timestamp, and reason code at decision points.
• Control -> keep next-best-action guidance visible in dense operational views.
• Trust -> provide pre-commit policy/dependency checks with clear pass/fail feedback.
• Relief -> make blocked-state recovery one-click from the same working context.
• Momentum -> optimize repetitive tasks (fast row updates, presets, keyboard-first interaction).
• Psychological safety -> provide reversible actions where possible and explicit impact preview for irreversible actions.
• Cognitive load management -> progressive detail (summary first, drill-down on demand) to support both novice and expert operators.
• High-pressure support -> fixed “priority queue” panel highlighting what must be resolved before cutoff.

Emotional Design Principles

• Reduce uncertainty before reducing clicks.
• Every critical action should leave users more confident than before they clicked.
• Error states must guide, not punish.
• Trust is built through visible provenance and predictable outcomes.
• Calm, high-signal interfaces beat visually busy dashboards for deadline work.
• Explain constraints in plain language at the moment they matter.
• Support fast experts without sacrificing clarity for occasional users.
• Urgency messaging must accelerate action without escalating stress.

UX Pattern Analysis & Inspiration

Inspiring Products Analysis

Excel

• Strength: fast sorting, filtering, and organization of dense tabular data.
• UX value for this product: operations users can prioritize quickly across many municipalities/jobs without losing context.
• Pattern to borrow: grid-first workflows with explicit column controls, deterministic sorting, and repeatable views.

Word

• Strength: direct display-and-edit flow where users can immediately update content in context.
• UX value for this product: users should update election/job fields inline without disruptive screen changes.
• Pattern to borrow: clear edit states, obvious commit behavior, and immediate confirmation of applied changes.

Why these are inspiration, not templates

• Election operations are deadline- and policy-constrained, so interactions must preserve traceability, policy checks, and provenance in ways generic office tools do not require.

Transferable UX Patterns

• Grid-first operational workspace for high-volume records.
• Inline editing with explicit editable/read-only affordances.
• Fast sort/filter/preset workflows for recurring report and dispatch use.
• Row selection + guarded bulk actions for repetitive updates.
• Persistent hierarchy: always-visible keys (municipality, cycle, milestone status, risk level).
• Deterministic state cues: visible “last refreshed” and data-freshness indicators for decision confidence.

Anti-Patterns to Avoid

• Hidden edit modes that obscure whether a change is pending or committed.
• Decorative dashboards that reduce scan speed of dense operational data.
• Multi-step navigation for simple status/date updates that should be inline.
• Ambiguous save behavior (silent auto-save for high-risk changes).
• Generic “office app cloning” that ignores policy checks, reason codes, and audit provenance.
• Non-deterministic sorting/filtering that can produce different operational views for different users.

Design Inspiration Strategy

Adopt

• Excel-style organization controls for dense data operations.
• Word-style direct editing with explicit commit confirmations.

Adapt

• Require pre-commit dependency/policy validation before sensitive status changes.
• Add role-aware defaults and progressive disclosure (summary first, drill-down when needed).
• Preserve provenance visibility (actor, timestamp, reason code) near every critical action.
• Keep interaction consistency: same edit, save, and status-confirm patterns across all operational views.

Avoid

• Minimalist patterns that hide operational truth.
• Any flow that separates action from consequence visibility.
• Any interaction that weakens trust under cutoff pressure.

Decision Rules for Pattern Use

• If a pattern improves speed but reduces certainty, do not adopt as-is.
• If a pattern increases clicks but prevents high-impact errors, prefer safety by default.
• If users cannot explain “what changed and why” from the UI, redesign the interaction.
• If two users can reach different filtered/sorted conclusions from the same data context, tighten the interaction model.

Design System Foundation

1.1 Design System Choice

Ant Design (React + Ant Design v5 token system) for a PC-first municipal operations web application.

Rationale for Selection

Ant Design is the best fit using first-principles criteria for this product:

• Operational clarity under pressure: strong support for dense tables, forms, and status-driven workflows.
• Execution speed with low risk: mature, documented components reduce build time and UX inconsistency.
• Trust and governance visibility: supports explicit validation, status tags, and auditable interaction patterns.
• Adoption fit: familiar enterprise interaction model for office-based users.

Why this over alternatives:

• Not custom-first: custom systems increase delivery risk and maintenance burden without clear value for this operations-heavy tool.
• Not utility-only foundation: utility-only approaches can drift in consistency across complex admin workflows.

Implementation Approach

• Use Ant Design as the base for core UI primitives: Layout, Table, Form, DatePicker, Steps, Timeline, Tag, Modal, Drawer, Alert, Result.
• Build domain-specific extension components on top of Ant Design for election operations:
  • Municipality/Cycle Workspace Grid
  • Cutoff Risk Queue Panel
  • Blocker Resolution Drawer
  • Dispatch Run Builder
  • Audit Provenance Side Panel
• Apply architecture guardrails in UX and data interactions:
  • Legacy Access tables remain immutable.
  • All new capabilities write to extension tables only.
  • Data composition uses join queries/views via ID relationships.
  • Permanent municipality entities remain clearly separated from election-cycle entities in navigation, forms, and reports.

Implementation exit criteria:

• Users can complete core cycle setup and status workflows without leaving primary workspace context.
• All high-risk commits show pre-commit validation and clear recovery guidance.
• Role-critical views preserve dense data readability and keyboard efficiency on desktop.

Customization Strategy

• Use Ant Design token theming to create an operations-focused visual profile:
  • High-contrast semantic status colors (on-track, at-risk, blocked, overdue)
  • Compact density profile for high-volume grid work
  • Consistent spacing and typography for long-form operational scanning
• Establish reusable pattern standards:
  • Inline edit + explicit commit behavior
  • Deterministic filtering/sorting state indicators
  • Provenance visibility (actor, timestamp, reason code) at decision points
• Restrict customization to tokens and wrapper components first; avoid deep component forks unless required by compliance or workflow-critical needs.

2. Core User Experience

2.1 Defining Experience

The defining experience is operationally safe, high-speed status progression for election-cycle work: users update dates/statuses inline, pass visible dependency/policy checks, and commit changes with immediate confidence in downstream accuracy.

This experience is built around one promise: “Any coordinator can move critical work forward quickly without breaking compliance, traceability, or production readiness.”

2.2 User Mental Model

Users think in task queues and deadlines, not abstract records. They expect to:

• Find the right municipality/cycle quickly
• Sort/filter work by urgency and due date
• Edit directly where they are looking
• See instantly whether the change is valid
• Understand why something is blocked and how to unblock it

Current mental model carryover:

• Excel-like control over tabular organization (sort, filter, scan, batch)
• Word-like in-context editing with clear commit confirmation
• “One source of truth” expectation during high-pressure cutoff windows

Likely confusion points to design against:

• Mixing permanent municipality data with election-cycle data
• Unclear save/commit state
• Hidden dependency failures discovered too late

2.3 Success Criteria

Users should consistently report: “This just works when it matters.”

Core success indicators:

• Status/date updates are completed in-line without navigation detours
• Pre-commit checks prevent invalid transitions before save
• Blocked-state reasons are explicit and actionable from the same screen
• Users can verify who changed what and why in seconds
• High-priority items are clearly surfaced before cutoff risk escalates

2.4 Novel UX Patterns

Pattern strategy: familiar-first, innovation-in-guardrails.

Established patterns to leverage:

• Dense data grids with deterministic sort/filter behavior
• Inline field editing with explicit commit actions
• Role-oriented task queues and saved operational views

Novel combination for this product:

• “Safe Commit Rail”: dependency/policy validation integrated directly into inline updates
• “Cutoff Risk Queue”: persistent urgency panel tied to timeline and blocker state
• “Provenance-at-point-of-action”: actor/timestamp/reason code visible where decisions are made

This avoids forcing users to learn a new interaction language while still delivering a materially better operations workflow.

2.5 Experience Mechanics

1. Initiation

• User lands in role-specific operations workspace (Client Services, Production, Transportation, Support).
• Default view loads prioritized election-cycle records with saved filters and risk ordering.
• User selects row/field or bulk selection set for intended update.

1. Interaction

• User edits status/date/service fields inline in the grid or side drawer.
• System evaluates transition rules in real time (dependencies, policy checks, required reason codes).
• If valid, commit action is enabled; if invalid, blocker details and direct fix actions are shown.

1. Feedback

• On valid commit, user sees immediate confirmation with changed fields highlighted.
• Provenance metadata appears with actor, timestamp, and reason code.
• Related risk indicators and queue ordering refresh deterministically so users trust what changed.

1. Completion

• Record returns to normal state with updated lifecycle status.
• If follow-up action is needed, “Next Best Action” is presented immediately.
• User can continue in current context (no forced navigation), preserving momentum during deadline work.

Visual Design Foundation

Color System

Visual direction: calm operational clarity with high-signal status semantics.

Core palette:

• Primary: #1F4E79 (municipal navy; trust and structure)
• Secondary: #0F766E (teal support/action)
• Accent: #2563EB (interactive focus/action emphasis)

Semantic status palette:

• Success / On Track: #2E7D32
• Warning / At Risk: #B45309
• Error / Blocked: #B91C1C
• Info / Neutral Progress: #2563EB
• Overdue / Critical Flag: #7F1D1D

Neutral foundation:

• Background: #F7F9FC
• Surface: #FFFFFF
• Border: #D0D7E2
• Primary Text: #111827
• Secondary Text: #4B5563

Ant Design token strategy:

• Configure global tokens first (colorPrimary, colorSuccess, colorWarning, colorError, colorInfo, colorBgBase, colorText, borderRadius, density-related sizing).
• Keep status meaning consistent across tables, tags, timelines, and alerts.

Typography System

Tone: professional, clear, non-decorative, optimized for dense operational reading.

Type stack:

• Primary UI text: Public Sans, Segoe UI, Arial, sans-serif
• Data-heavy/labels fallback: IBM Plex Sans, Segoe UI, sans-serif
• Monospace for IDs/reference codes: IBM Plex Mono, Consolas, monospace

Type hierarchy (desktop-first):

• H1: 28px / 36px / 600
• H2: 22px / 30px / 600
• H3: 18px / 26px / 600
• Body default: 14px / 22px / 400
• Dense table/body compact: 13px / 20px / 400
• Caption/meta: 12px / 18px / 400

Typography principles:

• Prioritize legibility over brand flourish.
• Keep numeric/date fields highly scannable.
• Use consistent casing and label patterns for form-heavy workflows.

Spacing & Layout Foundation

Layout direction: compact, structured, desktop-optimized operational workspace.

Spacing system:

• Base unit: 8px
• Micro spacing for dense table controls: 4px
• Section spacing rhythm: 16px / 24px / 32px

Grid and containers:

• Desktop-first 12-column grid
• Content max-width bands for readability in wide monitors
• Persistent side regions for risk queue/filter panels when useful

Component density rules:

• Default to compact controls for grid and forms
• Keep touch-target inflation out of scope (PC-only product)
• Reserve larger spacing only for high-risk confirmations/modals

Visual rhythm:

• Clear row grouping and section boundaries
• Strong alignment around key operational identifiers (municipality, cycle, status, due date)

Accessibility Considerations

• WCAG 2.2 AA minimum contrast targets:
  • 4.5:1 for normal text
  • 3:1 for large text and UI components
• Keyboard-first operation:
  • Visible 2px focus indicators on interactive elements
  • Logical tab order in grids, forms, drawers, and modals
• Do not rely on color alone:
  • Pair status colors with labels/icons/patterns
• Motion and feedback:
  • Subtle motion only for orientation, not decoration
  • Respect reduced-motion preferences
• Dense-data readability:
  • Preserve minimum font sizes and row heights that remain readable during long operational sessions

Design Direction Decision

Design Directions Explored

Six design directions were explored in the HTML showcase:

• Direction 1: Operations Command Desk (tri-pane situational control)
• Direction 2: Queue + Inspector (fast update throughput)
• Direction 3: Spreadsheet Plus (Excel-like grid-first operations)
• Direction 4: Timeline Operations (deadline-first sequencing)
• Direction 5: Workbench + Modal Deep Work (single-task focus)
• Direction 6: Executive Snapshot + Drilldown (overview-to-action model)

Chosen Direction

Hybrid direction:

• Base layout and information hierarchy from Direction 1
• Grid interaction and column/preset behavior from Direction 3
• Inspector-side quick edit/validation behavior from Direction 2

Design Rationale

• Preserves trusted legacy mental model while improving speed.
• Keeps risk visibility and blocker recovery in constant view.
• Supports dense, keyboard-first PC workflows without navigation overhead.
• Provides clear commit confidence through in-flow validation and provenance visibility.

Implementation Approach

• Primary screen architecture: tri-pane workspace
  • Left: context/navigation (municipality, cycle, saved views)
  • Center: dense editable operations grid
  • Right: risk queue + quick inspector/provenance
• Interaction model:
  • Inline edits in grid
  • Safe Commit checks before sensitive transitions
  • Immediate row-level confirmation with actor/timestamp/reason code
• Build order:
  • 1. Workspace shell and layout
  • 1. Grid + filters + presets
  • 1. Inspector and validation rail
  • 1. Risk queue and provenance panel

User Journey Flows

Client Services Coordinator - Election Setup and Publish

Goal: create a complete election-cycle plan without touching immutable legacy tables and publish a production-ready job.

flowchart TD
    A[Open Municipality Workspace] --> B[Select Municipality]
    B --> C[Load Permanent Data via Legacy Join]
    C --> D[Create Election-Cycle Extension Record]
    D --> E[Apply Prior-Cycle Defaults]
    E --> F[Configure Services: Addressing, Envelopes, Sorting, Office Copies, Transport]
    F --> G[Enter Key Dates and Owners]
    G --> H{Required Fields Complete?}
    H -- No --> I[Show Missing Fields + Jump Links]
    I --> F
    H -- Yes --> J[Run Pre-Commit Validation]
    J --> K{Dependency/Policy Pass?}
    K -- No --> L[Show Blockers + Reason + Corrective Action]
    L --> F
    K -- Yes --> M[Publish to Production Readiness]
    M --> N[Show Confirmation + Provenance + Next Best Action]

Production Lead - Dependency Exception Recovery

Goal: resolve blockers before cutoff and preserve auditable exception history.

flowchart TD
    A[Open Risk Queue] --> B[Select At-Risk Job]
    B --> C[View Timeline + Dependency Panel]
    C --> D{Blocking Dependency Found?}
    D -- No --> E[Confirm On-Track Status]
    E --> F[Return to Queue]
    D -- Yes --> G[Create Exception Record]
    G --> H[Assign Owner + Due-By Timestamp]
    H --> I[Request Required Field Updates]
    I --> J{Updates Completed Before Cutoff?}
    J -- No --> K[Escalate + Replan Downstream Milestones]
    K --> L[Record Escalation Trail]
    J -- Yes --> M[Re-run Validation]
    M --> N[Clear Blocker and Update Status]
    N --> O[Write Audit Trail: actor/time/reason]
    O --> F

Transportation Coordinator - Daily Dispatch Planning

Goal: produce accurate date-sorted runs tied directly to election milestones.

flowchart TD
    A[Open Transportation Report Workspace] --> B[Set Date Range: Next Day / 7-Day Lookahead]
    B --> C[Apply Saved Filters: County, Municipality, Service Status]
    C --> D[Aggregate Pickup/Delivery Events from Extension + Legacy Joins]
    D --> E[Group by Date then County then Municipality]
    E --> F{Missing Critical Event Data?}
    F -- Yes --> G[Flag Record + Open Linked Job for Correction]
    G --> H[Refresh Report After Correction]
    H --> D
    F -- No --> I[Generate Dispatch Stop List]
    I --> J[Review Quantity and Notes]
    J --> K[Export CSV/XLSX-Compatible Output]
    K --> L[Mark Dispatch Plan Ready]

Journey Patterns

Navigation patterns:

• Role-based entry to a single operations workspace
• Queue-to-detail-to-queue loop without context loss
• Inline drill-in from report row to corrective action

Decision patterns:

• Required-field gate before publish
• Dependency/policy gate before commit
• Escalate-or-resolve branch based on cutoff timing

Feedback patterns:

• Immediate pass/fail validation states
• Explicit blocked reasons with one-click recovery path
• Provenance feedback after critical updates (actor/time/reason)

Flow Optimization Principles

• Keep users in one workspace during critical operations.
• Surface blockers before commit, not after.
• Make all high-risk actions explainable at point-of-action.
• Favor deterministic sorting/filtering for shared operational truth.
• Provide keyboard-first dense workflows for PC operators.
• Ensure every failure path ends with a clear next action.

Component Strategy

Design System Components

Use Ant Design foundation components as the default baseline:

• Layout and navigation: Layout, Menu, Breadcrumb, Tabs
• Data and tables: Table, Tag, Tooltip, Badge, Pagination
• Input and forms: Form, Input, Select, DatePicker, Checkbox, Radio
• Feedback and status: Alert, Result, Notification, Modal, Drawer, Spin
• Workflow cues: Steps, Timeline, Progress
• Utility patterns: Dropdown, Popconfirm, Empty

Coverage conclusion:

• Base CRUD, filtering, editing, modal/drawer interactions are fully supported.
• Domain-specific workflow intelligence requires custom composite components.

Custom Components

MunicipalityCycleWorkspaceGrid

Purpose: primary dense operations surface for municipality + election-cycle records.
Usage: default center pane in all role workspaces.
Anatomy: sticky header, column controls, inline editable cells, row status chips, provenance quick-view trigger.
States: default, sorted, filtered, inline-editing, validation-error, loading, empty.
Variants: compact (default), review mode (read-heavy).
Accessibility: keyboard row/cell navigation, sortable headers with ARIA sort state, error messaging tied to fields.
Interaction behavior: deterministic sort/filter, explicit commit for sensitive fields.

SafeCommitRail

Purpose: pre-commit dependency and policy gate for high-impact updates.
Usage: appears when status/date/service changes affect downstream operations.
Anatomy: validation summary, blocking reasons, corrective links, reason-code selector, commit action.
States: pass, warning, blocked, submitting, success.
Variants: inline rail (grid), drawer rail (detail mode).
Accessibility: focus lands on first blocker, screen-reader summary of pass/fail reasons.
Interaction behavior: commit disabled until required checks and reason codes are satisfied.

CutoffRiskQueuePanel

Purpose: persistent urgency queue for deadline-sensitive work.
Usage: right pane in tri-pane layout; always visible in operations views.
Anatomy: prioritized cards, countdown/due state, severity badges, owner, quick-open action.
States: normal, at-risk, blocked, overdue, resolved.
Variants: compact list, expanded analytical view.
Accessibility: severity announced with text labels (not color alone), keyboard selection and open action.
Interaction behavior: queue reorders deterministically after updates.

BlockerResolutionDrawer

Purpose: in-context recovery workspace for blocked records.
Usage: opened from blocked status, risk queue, or validation failures.
Anatomy: blocker details, dependency links, assignment, due-by edit, resolution note, save controls.
States: open/edit, invalid, saved, escalated.
Variants: standard blocker, escalation mode.
Accessibility: focus trap, labeled controls, error summaries.
Interaction behavior: save writes exception history and returns user to previous context.

DispatchRunBuilder

Purpose: transform transportation events into date-sorted dispatch output.
Usage: transportation workspace for next-day and 7-day planning.
Anatomy: date range controls, filter set, grouped results, quantity notes, export actions.
States: unfiltered, filtered, data-gap warning, ready-to-export, exported.
Variants: next-day quick mode, week lookahead mode.
Accessibility: keyboard filter controls, grouped headings with clear labels.
Interaction behavior: can deep-link directly to corrective records when gaps are detected.

ProvenanceTimelinePanel

Purpose: show who changed what, when, and why at point-of-action.
Usage: side panel and row-level detail context.
Anatomy: timestamped events, actor, reason code, changed fields, source link.
States: populated, loading, empty, filtered.
Variants: compact inline preview, full audit view.
Accessibility: semantic timeline structure, clear event narration for screen readers.
Interaction behavior: supports rapid investigation without leaving current workflow.

Component Implementation Strategy

• Build all custom components as Ant Design wrappers/composites using shared tokens.
• Keep behavior contracts strict: deterministic sorting/filtering, explicit commit for sensitive transitions, visible provenance.
• Standardize state models across components: loading, empty, validation error, blocked, success.
• Enforce accessibility at component level: keyboard pathways, ARIA labels, non-color status cues.
• Align data boundaries in UI contracts:
  • Legacy entities are read-only source context.
  • Extension entities handle new writes and workflow state.
  • Join identifiers (ID, JCode/JurisCode, KitID) are explicit in component data contracts.

Implementation Roadmap

Phase 1 - Core workflow components:

• MunicipalityCycleWorkspaceGrid
• SafeCommitRail
• CutoffRiskQueuePanel

Phase 2 - Recovery and reporting components:

• BlockerResolutionDrawer
• DispatchRunBuilder

Phase 3 - Traceability and optimization:

• ProvenanceTimelinePanel
• Shared utilities for status chips, reason-code pickers, and validation summaries

UX Consistency Patterns

Button Hierarchy

Primary action rules:

• Use one primary button per context (for example: Publish, Commit Update, Export Dispatch).
• Primary buttons use colorPrimary and are placed at decision-completion points.
• Disable primary buttons when required checks are incomplete; always show why.

Secondary action rules:

• Secondary buttons for non-destructive alternatives (Cancel, Back, Review Later).
• Tertiary/text actions for low-risk utilities (View History, Open Details).

Destructive action rules:

• Destructive actions require explicit confirmation (Popconfirm or Modal) with impact summary.
• Require reason code for irreversible operational changes.

Accessibility:

• All buttons have clear labels (no icon-only for critical actions).
• Keyboard focus visible and consistent across all action tiers.

Feedback Patterns

Success:

• Immediate inline confirmation after save/commit.
• Show changed fields + provenance snippet (actor/time/reason).

Warning:

• At-risk states use warning chips with clear due-by context.
• Warning banners include direct corrective action links.

Error/Blocked:

• Blocked commits show a structured blocker list with jump-to-fix actions.
• Error copy is specific, actionable, and non-blaming.

Info:

• Neutral informational states for refresh/sync and report generation progress.
• Use concise, non-intrusive messaging for routine system updates.

Consistency rules:

• Never rely on color alone; pair status with icon and text.
• Use same severity mapping across grid, queue, drawers, timelines, and reports.

Form Patterns

Structure:

• Group fields by operational intent: municipality context, cycle data, services, milestones, ownership.
• Keep permanent municipality context visibly read-only when sourced from legacy tables.

Validation:

• Validate required fields progressively as users edit.
• Reserve hard-block validation for publish/commit checkpoints.
• Show inline field-level errors plus top-level summary for multi-error states.

Entry behavior:

• Use defaults from prior cycle when available, visibly marked as inherited values.
• Date and quantity fields use strict input formatting and keyboard-friendly controls.

Commit behavior:

• Sensitive transitions invoke SafeCommitRail with dependency/policy checks.
• Reason code required where audit policy requires it.

Navigation Patterns

Workspace model:

• Standard tri-pane structure:
  • Left: context and saved views
  • Center: operational grid/work area
  • Right: risk queue + inspector/provenance

Flow model:

• Queue -> detail -> corrective action -> queue return, with no context loss.
• Deep-linking allowed from reports to corrective records.

State persistence:

• Preserve filters, sorting, and column presets per user role/workspace.
• On refresh/re-entry, restore last valid operational view where safe.

Additional Patterns

Search and filtering:

• Deterministic filtering/sorting with always-visible active filter chips.
• Saved filter presets for recurring dispatch and production scenarios.
• Clear reset behavior and predictable default sort (urgency then due date).

Modal and overlay:

• Use drawers for in-context edits and investigation.
• Use modals for high-risk confirmations and irreversible actions only.
• Focus management and escape/close behavior standardized.

Loading, empty, and no-result states:

• Loading: skeleton/compact spinner with context text.
• Empty: explain why list is empty and provide next action.
• No results: show active filter causes and one-click clear/adjust.

Desktop-first rule:

• UX patterns are optimized for PC keyboard + mouse workflows.
• Tablet-first and mobile-first interaction variants are out of scope for current product scope.

Responsive Design & Accessibility

Responsive Strategy

Primary strategy: desktop-first operational UX for office environments only.

• Supported interaction model: keyboard + mouse
• Core layouts optimized for 1280px+ operational screens
• Dense tri-pane workspace remains default for core workflows
• No tablet-specific or phone-specific UX targets in current scope
• If viewport is below supported width, show constrained fallback with guidance to use supported desktop resolution

Breakpoint Strategy

Desktop-only breakpoint model:

• Minimum supported operational width: 1280px
• Standard desktop: 1280px - 1599px
• Wide desktop: 1600px+

Adaptation behavior:

• 1280px - 1599px: compact tri-pane with collapsible secondary pane
• 1600px+: full tri-pane with persistent risk/provenance panel
• Below 1280px: reduced read mode and support notice for full editing workflows

Accessibility Strategy

Compliance target: WCAG 2.2 AA for all MVP and operationally critical flows.

Core requirements:

• Full keyboard operability for create/edit/commit/report/export workflows
• Visible focus indicators and logical tab order across grid, drawers, modals, and forms
• Semantic labels and ARIA attributes for custom composite components
• Color is never the sole indicator of status
• Clear, actionable error and blocker messaging
• Screen-reader-readable provenance and validation summaries

Testing Strategy

Responsive testing:

• Validate at 1280, 1366, 1440, and 1920 desktop widths
• Cross-browser desktop matrix: Chrome, Edge, Firefox (current major versions)

Accessibility testing:

• Automated scans (axe/Lighthouse or equivalent) in CI for critical pages
• Manual keyboard-only walkthroughs for core journeys
• Screen reader spot checks (NVDA + VoiceOver where available)
• Contrast validation for all semantic states (success/warn/error/info)

Acceptance checks:

• Core journeys complete without mouse-only dependencies
• No critical accessibility violations remain open at release gate
• Below-minimum viewport behavior is explicit and non-breaking

Implementation Guidelines

Responsive implementation:

• Use CSS grid/flex with desktop-first media queries
• Preserve deterministic column behavior in dense tables
• Keep right-side risk/provenance panels collapsible, not removed, at narrower desktop widths

Accessibility implementation:

• Use semantic HTML first, ARIA second
• Standardize focus management for modal/drawer open/close flows
• Provide reusable accessibility helpers in component layer:
  • status text + icon pairings
  • validation summary announcer
  • keyboard shortcut hints where appropriate

Operational guardrail:

• Do not invest in touch-target optimization or tablet/mobile navigation patterns in current release scope.

Approved Correct Course Addendum (2026-05-05)

ImportReviewWorkspace Flow

Add a dedicated flow for source ingestion and operator review:

• Import source file or approved export
• Preview column mapping and data typing
• Show deterministic validation issues by row and field
• Stage publish-ready rows separately from blocked rows
• Confirm publish with explicit provenance summary

Reconciliation Queue UX

Add a role-aware data quality queue:

• Mismatch list with severity, owner, status, and due date
• Deep-link from mismatches to affected report rows and traceability views
• Blocking-warning behavior on export when unresolved high-severity mismatches exist for selected scope

Contact and Proof Workflow Visibility

For proof/contact fields (Proof Sent, Proof Approved, contact assignment values):

• Show explicit role-based visibility and edit affordances
• Keep actor/timestamp provenance visible where policy allows
• Preserve deterministic filtering/sorting behavior in all related report and queue views