Worker portal redesign — composability runtime + design-system extraction

Orchard design system tokens (light/dark/system theme via --orchard-* CSS custom properties)

8 pages (dashboard, case search, case detail with 6 tabs, application process, renewal queue, applications list, notices list, appeals list, 404)

30 caseworker action handlers across SNAP/TANF/Medicaid/CAPS/WIC (per #392, #393, #394 / MRs already shipped)

Program-specific action handlers with cross-program views and per-program upstream endpoints (ADR-019 service-class JWT)

JWS-signed determinations rendered via canopy_signing::SignableDetermination (ADR-002)

FTI auditor role + advisory naming (per the most-recent FTI work)

✅ Palette revision (orchard tokens) — !295

✅ --orchard-info CSS token

✅ Light / dark / system theme support

✅ Per-jurisdiction theme configuration (src/theme.rs + rulesets/{jurisdiction}/theme.toml)

Design system extraction into reusable Askama partials + CSS utility classes (Stage 1) + four-state primitive upgrade (Stage 1.5)

Composability runtime: TOML composition loader, 5-layer merge (RFC 7396 baseline + RFC 6902 DB layers per ADR-022), plugin manifest validation per ADR-021

Storage layering: forward-only migration for composition_documents + composition_documents_archive; live override APIs (read/write/archive)

Generic IDP loader + IDP-aware sign-in

Worker / supervisor / analyst dashboards (composition-driven)

Case detail (3 shell strategies + 13 section types)

Customize-my-dashboard (per-worker deltas)

Jurisdiction Studio (onboarding wizard + live-mode composer + Plugin Studio)

⌘K command palette

Audit log unified surface (system + case scopes)

First-impression states (splash, maintenance, expired, 404)

Plugin Marketplace federation — defer to v2 (in-process Askama partials in v1 per ADR-021 require canopy-core PRs to install plugins; federation arrives when WasmPluginSource is added)

Studio promote modal / promote-live-to-baseline endpoint — descoped from v1 pending #507 (unified canopy config-backend ADR). Admins promote live overrides to baseline via their jurisdiction’s existing workflow (PR / Salt / manual edit) external to canopy until #507 lands.

Applicant portal (ADR-008, Dioxus) — separate project

Mobile / tablet — not in scope for v1

Print views — ADR-010 Typst territory, separate surface

Worker-journey microspec — needs design iteration before build; file separate design-spec issues per journey (intake / IEVS resolution / sign-and-authorize / notice compose)

Determination sign-and-authorize ceremony — needs design before build; tracked as separate spec issue

Notice compose/preview UX — needs design before build; tracked as separate spec issue

Income tab interaction depth (IEVS resolution, add/edit/remove income, employer lookup) — section shape is designed; interaction depth is TBD

PluginSource trait abstracts plugin discovery. v1 ships only CompileTimePluginSource. v2 federation (WasmPluginSource etc) is additive.

Plugins are in-process Askama partials registered via #[canopy_plugin] macro + linkme distributed slice. Compile-time Plugin.toml ↔ Rust handler validation prevents manifest-handler drift.

Composition loader signature: load_composition(jurisdiction, role, user_id, surface) → Result<ComposedSurface, CompositionLoadError>.

Cache: invalidate-on-write, single-replica v1. Studio writes invalidate the in-process cache; multi-replica RabbitMQ fanout invalidation deferred post-UAT.

Role filtering applies after override merge — items the role can’t use are silently dropped, no aria-disabled clutter.

Closed-set errors: UnknownPlugin, SpanOutOfRange, RowOverflow, RoleNotFound.

Three DB-backed layers (user delta, role override, jurisdiction live) share one composition_documents table keyed by (jurisdiction_id, layer, scope_key, surface). scope_key is polymorphic: user UUID for user, role slug for role, 'jurisdiction' sentinel for jurisdiction_live.

Override body is an RFC 6902 JSON Patch op list. Studio "add one panel" maps to one {"op":"add","path":"/items/-",…} op (not a full-document rewrite). test ops support optimistic concurrency.

Composition loader fetches all DB layers in one indexed SQL query (WHERE jurisdiction_id AND surface AND (layer IN …)) and replays the patch lists against the jurisdiction TOML baseline in jurisdiction_live → role → user order.

Override lifecycle: live override stays after promote-merge as a no-op; Studio surfaces a "live matches baseline" hint with an explicit Archive button. No canopy-core-repo watcher in v1.

Uniform 1-year audit retention for override-layer events; every write emits a JWS-signed AuditEvent per ADR-014 (chain integrity extends across composition mutations).

Dashboard composition — which panels appear, in what rows, at what spans

Case-detail composition — which sections appear, in what order, with which shell strategy (scroll / card-grid / tabs)

Identity composition — which IDP(s), in what order, with what label/color

Desktop-first product — workers don’t review cases on phones

Runtime cost of two shells live: double templates, double htmx swap targets, ambiguous focus management when the viewport crosses a breakpoint mid-action

Escape hatch already exists: a jurisdiction that needs viewport flexibility picks tabs (the most viewport-tolerant shell)

Email-first discovery routes user to matching IDP by domain or claim mapping

idp.toml declares N IDPs with slug + label + provider type (Keycloak / SAML / OIDC) + host + chip styling

Local accounts as a toggle (localAccounts.enabled = false → section vanishes)

Zero-IDP graceful state pointing at Studio → Identity

System audit — admin-facing, jurisdiction-wide, filterable, exportable to CSV / signed PDF / compliance report

Case history — same data, filtered to one household, exportable as "Cite for hearing" → signed PDF

#485 Extract 8 Askama primitives (PanelFrame, Overline, GoldRule, BigNumber, HeroStrip, LeafGlyph, StatusPill, MoneyCell) into services/canopy-web/templates/_primitives/*.html

Reuses existing .skeleton + @keyframes pulse + .u-empty-state and adds one new .u-error-block utility (the four Stage-1.5 macros wrap these classes; no renames)

Outcome: existing canopy-web templates rewritable to use primitives without composability runtime

#505 Upgrade the 4 panel-state utility classes to first-class Askama-macro primitives (EmptyState, Skeleton, SkeletonRow, ErrorBlock)

Rule: every panel renders all four states

Non-blocking — runs in parallel with Stage 2 / Stage 3

#486 ADR-021: Composability runtime + plugin model — ratified 2026-05-20

#487 ADR-022: Storage layering for composition overrides — ratified 2026-05-20

#488 ADR-023: Promote-PR mechanism — deferred 2026-05-20 to #507

#489 Forward-only migration (per ADR-016) landing the unified composition_documents table + composition_documents_archive per ADR-022 (one table for all three DB-backed layers, polymorphic scope_key)

#490 Composition loader: 5-layer merge (system defaults compiled into binary → jurisdiction baseline TOML via RFC 7396 → DB-backed layers via RFC 6902 in jurisdiction_live → role → user precedence) + role filter applied post-merge; integrated with the invalidate-on-write cache from ADR-021

#491 Live override APIs (read/write/archive endpoints accepting application/json-patch+json; If-Match ETag for full-list replace; JWS-signed AuditEvent per ADR-014 on every mutation)

Deferred: Promote-live-to-baseline (#492 closed-deferred to #507). Studio’s v1 "promote" affordance is admin-driven: admin uses jurisdiction’s existing baseline-edit workflow (PR / Salt / manual edit) external to canopy.

#493 Generic IDP loader from rulesets/{juris}/idp.toml (email-discovery routing; OIDC provider types keycloak + oidc-generic in v1; local-accounts toggle; zero-IDP graceful state). SAML federation stays upstream of the OIDC IdP per CRAIG-aligned design; full multi-shape claims (authentik / zitadel / kanidm) deferred to #515.

#494 IDP-aware sign-in template — email-first discovery + multiple IDP chips with per-IDP chip_color + chip_icon; CSP-clean (Alpine.js + htmx only); axe-core WCAG 2.1 AA

Plan: worker-portal-redesign-stage4-idp-loader-and-sign-in.adoc

Follow-ups filed: #512 (SAML spike), #513 (local accounts), #514 (introspection mode), #515 (multi-shape claims), #516 (multi-juris sign-in), #517 (identity verify xtask), #518 (env-var retirement)

Worker dashboard (12-panel kit, composition-driven)

Supervisor dashboard (jurisdiction-aware overrides)

Analyst dashboard (panel subset)

Case detail with 3 shell strategies + 13 section types

Customize-my-dashboard (per-worker deltas)

#499 Studio onboarding wizard — MR1a + MR1b + MR1c shipped 2026-05-25 (!367 / !368 / forthcoming). MR1a promoted rulesets/georgia/ to rulesets/default/ (reference ruleset). MR1b made canopy-core jurisdiction-agnostic: FilesystemJurisdictionRegistry + active_jurisdiction(state) + WorkerRole::StudioAdmin + role coverage across 40 Plugin.tomls. MR1c shipped the 5-step wizard at /studio/onboarding/step/{1..5} emitting a downloadable scaffold bundle (deep-copy of default/ + 3 overridden TOMLs + README documenting integrator’s required next steps). 3 FUs deferred: #568 multi-IdP, #569 custom theme palette, #570 IdP discovery probe.

#500 Studio live-mode composer (promote modal descoped from v1 pending #507; admin promotes via jurisdiction’s external workflow until then)

#501 Studio plugin developer view (Plugin Studio — authoring scope is one of the 3 open design questions on #486)

⌘K command palette

Audit log unified surface (system + case scopes)

First-impression states (splash, maintenance, expired, 404)

NEW: services/canopy-web/templates/_primitives/orchard.html (single file housing all 8 macros)

NEW: services/canopy-web/templates/_primitives/_smoke.html (smoke fixture for unit tests)

NEW: services/canopy-web/tests/primitives_test.rs (per-macro variant assertions)

MODIFIED: services/canopy-web/static/css/canopy-web.css — adds ~220 lines for the 8 primitives' classes + .u-error-block; reuses existing .skeleton, @keyframes pulse, and .u-empty-state; no inline style= per CSP. Status-pill kind backgrounds hardcoded for cross-jurisdiction consistency (matches existing .u-status-* convention)

Stage-1 implementation plan lives at worker-portal-redesign-stage1-design-system.adoc

NEW: macros for empty_state / skeleton / skeleton_row / error_block appended to _primitives/orchard.html

NEW: services/canopy-web/templates/cases/_results_error.html (htmx error fragment for the validating surface)

NEW: tests/e2e/specs/panel-states.spec.ts (Playwright spec exercising each of the four states)

MODIFIED: services/canopy-web/static/css/canopy-web.css — no changes (macros wrap existing .u-empty-state / .skeleton / .u-error-block)

MODIFIED: ≥ 1 in-tree panel template validating the four-state rule (Stage-1.5 plan picks cases/search.html to avoid the dashboard.spec.ts coupling Stage 1 deferred)

NEW: services/canopy-web/migrations/<timestamp>_composition_documents.sql per ADR-022 schema

NEW: crates/canopy-plugin-macros/ (proc-macro crate; #[canopy_plugin] derive + compile-time Plugin.toml validation)

NEW: crates/canopy-composition/ (or canopy-web internal module — TBD by Stage 3 implementation plan): PluginSource trait + CompileTimePluginSource + load_composition + 5-layer merge

NEW: HTTP handlers in canopy-web for GET/PATCH/DELETE /v1/composition/{surface}/{layer}/…​ per ADR-022 write API contract

MODIFIED: services/canopy-web/src/api/…​ to wire the composition loader into existing case-detail + dashboard request paths

cargo xtask validate clean (fmt + clippy + nextest + check-docs)

cargo xtask docs plan-lint clean (this plan’s Status column stays canonical)

Pre-push validate + Playwright E2E (≥ 136 currently green)

cargo xtask coverage at or above the current DEFAULT_THRESHOLD floor (xtask/src/cmd/coverage.rs; unit-lane scoped since #1382)

Stage 1: every primitive exercised by the smoke-fixture template (_primitives/_smoke.html) + a per-variant assertion in tests/primitives_test.rs. Consumer-template migration happens per Stage 5-7 issues.

Stage 1.5: ≥ 1 in-tree panel template renders all four states (empty, loading, error, populated) using the four empty_state / skeleton / skeleton_row / error_block macros; all 20 .u-empty-state template consumers migrated to o::empty_state; underlying .u-empty-state / .skeleton / .u-error-block CSS classes retained (macros wrap them per Stage 1 Decision 4)

Stage 2: ADR-021 + ADR-022 merged + cross-referenced from this plan’s Design section (Stage 2 done at 2 of 3; ADR-023 deferred to #507)

Stage 3: forward-only migration applied cleanly; composition loader unit-tested with fixture TOML + fixture patch op lists covering all 5 layers; PatchFailed error surfaces test-op failures + missing paths with layer + op-index context

Stage 4: IDP loader unit-tested per provider type (keycloak + oidc-generic); sign-in template axe-core WCAG 2.1 AA clean; zero-IDP graceful state renders. SAML federation dropped from app layer (handled upstream of OIDC IdP); full multi-shape claims (authentik / zitadel / kanidm) deferred to #515.

Stage 5-7: per-surface acceptance defined in the surface’s own MR