Plan: Worker Portal Design Mockups (Issue #420)

On this page

Status

Step Description Status

1

Mockup adoc. New docs/modules/ROOT/pages/design/worker-portal-mockups.adoc with one section per worker-portal surface: dashboard, case search, case detail, application process, renewal queue, applications list, notices list, appeals list, login. Case detail is documented as the SNAP-rendering subset (8 tabs: household, income, determination, notices, appeals, activity, abawd, guidance) with a callout noting which additional tabs render under TANF (work-req, time-limits), Medicaid (categories), CAPS (authorization), and WIC (nutrition). The 16 tab partials in services/canopy-web/templates/cases/tab_*.html are the source of truth; the section maps program → tab subset rather than listing all 16 partials inline. Each section includes: Mermaid layout diagram (boxes representing UI regions), the Orchard color tokens used (referencing rulesets/georgia/notices/components/orchard.typ:1-32), and the htmx targets / form actions on the page.

Done (2026-05-11)

2

Kroki PNG generation. The Antora docs build already wires Kroki for Mermaid rendering. Confirm docs/antora.yml (or equivalent) has Kroki enabled; if not, add the configuration. Each Mermaid block in the new adoc renders to a PNG inline.

Done (2026-05-11)

3

Docs nav. Add the new mockups page to docs/modules/ROOT/nav.adoc under a "Design" or "Reference" section. Update docs/modules/ROOT/pages/services/canopy-web.adoc with a cross-link to the mockups page.

Done (2026-05-11)

Issue: #420
Branch: docs/worker-portal-design-mockups
Labels: type::documentation, priority::low, service::web, workflow::ready

As-built note (2026-05-11): deviation-free landing. Case Detail’s 16 tab partials were documented via the program → tab-subset table rather than per-tab inline screenshots; pixel-perfect mockups stay out-of-scope. The Antora playbook at antora-playbook.yml:14-15 already has asciidoctor-kroki wired, so Step 2 was confirm-only with no new configuration.

Context

The 8 worker-portal pages (dashboard, case search, case detail, application process, renewal queue, applications list, notices list, appeals list) plus the login surface were built without explicit design mockups; design choices live only in the templates and accumulated CSS. Case detail in turn renders a program-dependent subset of 16 tab partials (services/canopy-web/templates/cases/tab_*.html): SNAP shows 8 (household, income, determination, notices, appeals, activity, abawd, guidance); TANF adds work-req + time-limits; Medicaid adds categories; CAPS adds authorization; WIC adds nutrition. New contributors lack visual reference for any of this. UAT prep needs printable mockups so caseworkers can comment on layout before clicking through.

This plan documents what’s already in production rather than propose a redesign. Real design refresh (post-UAT, possibly under the Dioxus rewrite) is a separate concern.

Code references

  • services/canopy-web/templates/ — Askama templates as the source of truth for current layout.

  • services/canopy-web/static/css/ — Orchard CSS rules.

  • rulesets/georgia/notices/components/orchard.typ:1-32 — design tokens (color palette).

  • docs/modules/ROOT/pages/services/canopy-web.adoc — existing service-reference page.

Scope

In scope:

  • One mockup adoc covering 8 page types + login.

  • Case detail documented as the SNAP-rendering 8-tab subset with a program → extra-tab map for TANF / Medicaid / CAPS / WIC.

  • Mermaid layout diagrams.

  • Orchard color-token annotations.

  • Antora nav integration.

Out of scope:

  • Design refresh / new mockups for proposed future UI. This documents existing surfaces.

  • Detailed pixel-perfect specifications. Mermaid box diagrams are sufficient for layout reference; pixel-level fidelity belongs in a real design tool, not Antora.

  • Mobile / responsive layouts. Worker portal is desktop-first; if responsive becomes a goal, that’s a separate plan.

  • Constituent-portal mockups (canopy-portal). Different surface, different audience.

  • Accessibility audit annotation in the mockup. axe-core results live elsewhere.

Dependencies

  • No prerequisite plans on disk.

Design

Adoc structure (sketch):

= Worker Portal Mockups
:toc:

== Dashboard

[mermaid]
....
flowchart TD
  H[Header: Logo, User Menu]
  S[Sidebar: Navigation]
  M[Main: Stats Cards]
  C[Content: Recent Activity Table]
  H --> M
  S --> M
  M --> C
....

*Orchard tokens:*

* Primary: `--color-orchard-primary` (used in stats cards)
* Secondary: `--color-orchard-secondary` (used in table headers)
* Background: `--color-orchard-bg`

== Case Search

…

Each section captures the same shape: layout diagram, color tokens, htmx interactions, primary actions.

Files Touched

File Change

docs/modules/ROOT/pages/design/worker-portal-mockups.adoc

New file

docs/modules/ROOT/nav.adoc

Add Design section + mockups page link

docs/modules/ROOT/pages/services/canopy-web.adoc

Cross-link to mockups page

docs/antora.yml (if needed)

Confirm Kroki/Mermaid wiring

CHANGELOG.adoc

=== Added entry (documentation)

Verification

  1. cargo xtask check-docs — Tier 1 docs unchanged; new file passes structure check.

  2. Local Antora preview: npx antora docs/antora-playbook.yml (or equivalent) — mockup pages render with Kroki PNGs inline.

  3. Manual visual check: every section’s Mermaid diagram resolves to a readable layout box.

  4. Open the built Antora site (not just the source .adoc) and confirm each mockup PNG actually renders in the browser — Kroki config claiming rendering is not sufficient; the rendered output must be visible.

Documentation Updates

  • docs/modules/ROOT/pages/design/worker-portal-mockups.adoc — new

  • docs/modules/ROOT/nav.adoc — Design nav section

  • docs/modules/ROOT/pages/services/canopy-web.adoc — cross-link

  • CHANGELOG.adoc — entry under == Unreleased / === Added

  • Plan archive: move to plans/archive/ post-merge

Edit this page · default