Skip to content

Design

UX/UI design specifications for racket-book V2 — owned by Mira (UX/UI Designer). Each page captures one screen or one cross-cutting design concern, in a form Juno (Frontend) can implement against without re-deriving intent.

How to read this section

Specs are Markdown-first, browser-renderable, and Tailwind-mappable. ASCII wireframes show layout intent at a glance; final visual fidelity comes from the component breakdown + design tokens. The point is to fix decisions cheaply, not to substitute for a Figma file.

Every screen spec follows the same skeleton:

  1. Source requirement — which Iris page + which V2 MoSCoW item this implements.
  2. Viewports — mobile-first 375 px baseline; 768 / 1280 adaptations.
  3. Wireframe — ASCII layout per viewport.
  4. Component breakdown — the elements on the screen, with state, copy, and behaviour notes.
  5. Interaction states — loading, empty, error, success.
  6. Accessibility — keyboard, focus, screen-reader labels, contrast, hit-target sizing.
  7. HTMX / progressive-enhancement seams — what is server-rendered, what swaps, what falls back without JS.
  8. i18n affordance — which strings are catalogue-driven ({% trans %}); which are data.
  9. Cross-references — Iris's source requirement, Theo's data-model fields, Pax's handler scope.

Round 1 (merged)

Two highest-leverage surfaces: the screen Stefan looks at first when he opens the app, and the screen he uses 50+ times a year.

Round 2 (merged)

The next-most-leverage surfaces — the customer-facing PDF artifact and the cross-stringer sharing UX:

  • Receipt PDF — visual design — A4, top-left-quadrant total, two redaction modes, EN + DE templates, WeasyPrint print CSS.
  • Share management — Rule #1 grant flow, list + revoke active grants, audit log surface, V3 client-side preview.
  • "Shared with me" inbox — the receiving stringer's standalone surface, with per-grant detail view + redaction notice, mobile-first.

Round 3 (this MR)

Onboarding + admin tooling — the surfaces beyond the stringer's daily workflow:

  • Stringer onboarding — magic-link landing → first-login profile fill (M3 + M21) → optional password setup. Mobile-first single-page form per stringer-lifecycle.
  • Admin — catalogue moderation queue — admin's view of CatalogueSubmission (M17 / UC-7); list (oldest first, filterable by kind), detail, Promote / Reject decision modals. Coordinates with Pax-A's catalogue schema.
  • Admin — person merge — admin tool for merging two duplicate Person rows per ADR-0004 § Person merge; search → side-by-side compare → typed-confirm merge with audit trail.
  • Admin — DSAR queue — V2 admin-mediated FADP rights surface (DSAR / erasure / portability) per fadp-posture; list + per-request render-export, two-step erasure with safety prompts, 30-day SLA chip, finalize-expired-soft-deletes sub-route.

Round 3+ (companion to M14 implementation)

  • Receipt email — body design — the email envelope + body that wraps the PDF receipt at the M14 send. Covers subject line (EN + DE), From / Reply-To rationale, plain-text body (HTML deferred), PDF attachment shape, locale resolution, no-email + failure UX. Companion to Pax-A's M14 backend work.

Round 5 (this MR — V2 launch core)

The two cutover surfaces tied to V2 launch — operator UI for the M15 ETL upload and the public-facing V1 deprecation:

  • Admin — V1 upload (M15 cutover flow) — wraps the M15 ETL pipeline (Vera) behind an admin browser UI: upload XLSX → dry-run reconciliation report → Approve / Cancel → commit + final summary. Typed-confirm gating on prod; idempotent retry. Companion to process — V1 upload spec.
  • V1-listing deprecation strategy — what happens to stringing.wagen.io post-V2-launch. Evaluates hard-redirect / soft-banner / sunset-page; recommends a forever sunset page that replaces the listing on cutover day. Implementation is a keystone Caddy + static-asset MR, sequenced after the M15 commit.

Round 6 (this MR — stringer-self-service surfaces)

The two surfaces that close V2's stringer-self-service gap — settings (the post-onboarding home for every optional field) and client management (XLSX-parity list + detail + edit):

  • Settings (V2) — single /settings page with seven sections (account, business identity, stringjob defaults, sign-in, notifications, your data, account closure). Comprehensive sweep of every stringer-scoped configuration in V2; explicit non-goals for client-specific overrides + V3 notification opt-outs. Closes #140.
  • Client management (V2) — /clients list (search + sort + recent-activity) + /clients/{id} detail (profile + edit + order history + reserved V3 hooks). Decision: M12 paid-date toggle lives on order-detail, NOT client-detail. Closes #141.

Round 10 (this MR — destructive-cleanup wrapper)

  • Admin — Finalize expired soft-deletes — admin's destructive-cleanup surface wrapping Pax's existing POST /admin/persons/finalize-expired endpoint behind a typed-confirm + dry-run preview UX. Stage 1 eligible list + Stage 2 per-Person typed-confirm + Stage 3 post-finalize audit summary. Inherits the canonical typed-confirm pattern from admin-person-merge and admin-dsar-queue. Closes #156.

Future rounds (queued)

  • Order detail / edit screen — the post-Strung surface where price edits, lifecycle-date changes, and re-emit triggers live (order-lifecycle hidden requirements 1–8). Hosts the M12 paid-date toggle per the client-management-v2 M12-decision.
  • Sign-in page — M21 password + magic-link sign-in surface, the post-onboarding return path.
  • Notifications inbox — full notifications surface (V2 covers the dashboard badge + mark-as-read; the dedicated inbox screen is queued).
  • Stringer-side "submit to catalogue" form — the producer side of the admin catalogue moderation queue.
  • Per-Person admin detail page — full timeline for one Person (orders + ClientProfiles + audit + shares + merges); cross-link target from the admin DSAR queue and admin person merge surfaces.
  • Generic admin audit-log search — across all share_audit event kinds (share grants, person merges, person erasures, etc.).
  • Stringer offboarding — self-deactivate + admin-finalize affordances per stringer-lifecycle § Offboarding.
  • V3 client portal screens — surfaces marked V3-deferred in Round 2 + Round 3 specs (share-management § Client-side surfaces, audit transparency for the client, "Download my data", "Delete my account", consent-ratification on magic-link claim) become first-class once the V3 portal lands.
  • DE copy pass — Mira drafts EN in every spec; Iris finalises DE after each round merges.

Working assumptions

  • Mobile-first. Stefan strings on a phone next to the racket, not at a desk. Every layout starts at 375 px and earns wider real estate by adding columns, never by pushing the phone case to a polyfill.
  • Server-rendered + HTMX. No SPA. Every state in the spec must be reachable by a full page load; HTMX swaps are the optimisation, not the contract.
  • Tailwind-mappable tokens. Design tokens maps 1:1 to Tailwind's defaults where possible; explicit overrides are flagged.
  • EN copy is normative; DE is Iris's later pass. Per the agent roster.
  • Saved-pref-wins for locale. Per i18n architecture. Specs reference the rule rather than re-stating it.