docs: establish CV UX scope entry and research traceability

2026-10-25 14:10:54 +01:00
parent 28f83df13a
commit 01e10996c5
12 changed files with 3226 additions and 0 deletions
@@ -0,0 +1,142 @@
+# Desktop and mobile wireframe specifications
+
+**Status: proposed, Not Tested.** These are implementable layout and interaction specifications, not screenshots of Jobjakt. They preserve the existing routes and current 900px editor breakpoint. Measurements below are starting constraints for review, not claims about current rendered geometry.
+
+## D-A: desktop CV editor, 1440 × 900
+
+```text
+┌────────── existing application navigation ────────────────────────────────┐
+│ Career / CVs  ›  Application CV                    Saved   PDF   More     │
+│ For: [role · company] / General CV    Uses current career profile          │
+├──────────────────────────────────────┬───────────────────────────────────┤
+│ Content Template Customize AI History│ Preview       2 pages · Fit 72%    │
+│                                      │                                   │
+│ SECTION OUTLINE                       │        ┌───────────────────┐      │
+│ Summary                  Visible     │        │                   │      │
+│ Experience · 3 entries   ↑ ↓  ⋮      │        │  Physical page 1    │      │
+│   Test engineer                      │        │                   │      │
+│   Edited for this CV   Reset         │        └───────────────────┘      │
+│ Skills                   ↑ ↓  ⋮      │                                   │
+│ + Add content                        │        ┌───────────────────┐      │
+│                                      │        │  Physical page 2    │      │
+└──────────────────────────────────────┴────────┴───────────────────┴──────┘
+```
+
+Keep the current application shell. Within remaining editor width, target an edit pane of 420–520px where space permits, a 16–24px gutter and a flexible preview pane. At 900–1100px prioritise a usable form over a large page image; do not force the 1440px dimensions. Each pane scrolls as the existing editor allows; title/status/actions and preview heading remain findable. Page scale is fit-to-available-width, never a change to actual page dimensions.
+
+The context line uses existing linked-job data. A general variant says “General CV”; no fabricated company. Clicking the source profile link uses the existing navigation guard. Status reserves a stable width for Saved, Saving, Unsaved and Save failed. Conflict/recovery expands a message below the header without replacing the draft. PDF remains named and reachable when tabs scroll.
+
+Content rows have 44px minimum practical touch target areas, visible focus and named move controls. Only the row handle starts drag. Visibility and delete remain separate actions. Remove/hide wording follows actual data ownership. Section detail shows source entry versus local override; reset explains what content it replaces.
+
+## D-B: template candidate view
+
+```text
+┌ Choose a design                                      Close ┐
+│ [ATS filter] [All available]  Selected: current design       │
+├─────────────────┬───────────────────────────────────────────┤
+│ Theme cards     │ Candidate name · category · availability   │
+│ [existing A]    │ ┌─────────────────────────────────────┐    │
+│ [existing B]    │ │ Actual rendered sample / candidate  │    │
+│ [existing C]    │ └─────────────────────────────────────┘    │
+│                 │ Sample content • visual overrides reset   │
+│                 │ Content edits are preserved                │
+├─────────────────┴───────────────────────────────┬───────────┤
+│ Cancel                                         │ Apply     │
+└────────────────────────────────────────────────┴───────────┘
+```
+
+Use an existing MUI Dialog with a labelled title, normal focus trap and return focus to the invoking card. Selection changes only candidate state. Loading uses a contained progress message; failure offers Retry and leaves Cancel reachable. Explicitly distinguish synthetic sample from the user's live content. Locked candidate exposes the existing plan explanation and cannot be applied. Apply is disabled during the single mutation. One successful application creates one undo step.
+
+## D-C: application cover letter
+
+```text
+┌ Application: role · company ────────────────────────────────────────────┐
+│ Attached CV: [CV name] [Open]        Cover letter v3 · Unsaved            │
+│ Write  Preview                   Save   Discard   PDF   History         │
+├─────────────────────────────────┬───────────────────────────────────────┤
+│ DOCUMENT DETAILS                │ Preview · Updating / Current          │
+│ [Copy contact details]          │        ┌────────────────────────┐     │
+│ Sender / recipient / date       │        │ Sender                 │     │
+│ Subject                         │        │ Date · Recipient       │     │
+│ [Match attached CV]             │        │ Subject                │     │
+│                                 │        │                        │     │
+│ LETTER                          │        │ Dear …                 │     │
+│ [Markdown toolbar]              │        │ Paragraphs …           │     │
+│ [labelled multiline field]      │        │ Sign-off               │     │
+│ AI: action/tone/language         │        └────────────────────────┘     │
+│ [Review suggestion]             │                                       │
+└─────────────────────────────────┴───────────────────────────────────────┘
+```
+
+This remains inside the current application workspace. Do not introduce another top-level navigation system. The exact document-details fields are introduced only with their versioned persistence contract. Before that phase, provide body-only preview, explicit Save and current history using existing data. “Match” is disabled with an explanation if no CV is attached; offer the current attach action.
+
+AI review occupies an existing comparison region and does not obscure Save state. Source and proposed text are labelled. Apply changes the local draft; no success message claims persistence before Save. History names source/time/version and previews before restoration. Restore creates a new version, preserving history.
+
+Copy-contact dialog lists selectable fields, default core contact scope and overwrite warning. Design dialog lists compatible settings and source CV. Both provide Cancel and an explicit final action; neither changes data on opening. After success, focus returns to the invoking button and a concise status announces the draft change.
+
+## M-A: mobile CV content, 390 × 844; must also work at 320px
+
+```text
+┌ Back   CV name                 More ┐
+│ Saved / Saving / Save failed        │
+│ Application context                │
+│ Content Template Customize AI …     │
+├────────────────────────────────────┤
+│ Summary                       Edit │
+│ Experience · 3                 Edit │
+│ [grip] Skills       ↑ ↓  Visible    │
+│ Education                          │
+│ + Add content                      │
+│                                    │
+├────────────────────────────────────┤
+│       Edit          Preview        │
+└────────────── safe area ────────────┘
+```
+
+Below 900px use the existing Edit/Preview mode rather than mounting an inaccessible duplicate editor behind a simulated modal. Preserve the selected tab, expanded section, scroll position and draft when switching modes. Expose the mode group with programmatic selection state. Inactive pane is hidden from focus and accessibility navigation. Announce current mode briefly, without reading the document on every change.
+
+Header title may truncate visually but has its full accessible name. The status line wraps rather than disappearing into overflow. Secondary actions move into a named More menu; history remains discoverable. Bottom controls include safe-area padding and do not cover the final form field. Browser text zoom to 200% can switch to a more compact arrangement without horizontal application overflow.
+
+## M-B: mobile entry form and preview
+
+Entry edit is a single column. Dates may share a row only while labels and month/year fields fit; stack at 320px or large text. Use distinct accessible labels “Start date” and “End date”, with format help described separately. Errors are adjacent, persistent and associated with the input. Focus the first invalid field only on attempted submit, not during ordinary typing.
+
+The keyboard must not cover active text or primary actions. Avoid relying solely on a fixed viewport height; test the existing scrolling layout with the real on-screen keyboard and safe areas. Reorder works with Move up/down on touch without dragging. A draft remains intact when entering preview and returning.
+
+Preview fills available width with scaled physical page surfaces, visible page count and render status. The standard Edit/Preview control returns to editing. PDF is available from a named action. Fit changes visual scale only. Preserve browser pinch/text-zoom functionality; do not claim custom gesture support. Long pages scroll vertically and last-good output remains available after a failed refresh.
+
+## M-C: mobile cover letter
+
+```text
+┌ Back  Letter · role/company   More ┐
+│ Unsaved changes                   │
+│ Write                  Preview    │
+│ CV: [attached CV]                  │
+├───────────────────────────────────┤
+│ Document details              ▾   │
+│ Letter text                       │
+│ [format toolbar, wraps]           │
+│ [multiline input]                 │
+│ AI suggestion / review            │
+├───────────────────────────────────┤
+│ Discard                   Save    │
+└───────────────────────────────────┘
+```
+
+Keep explicit Save/Discard until concurrency prerequisites are met. PDF and History may be in More when space is constrained, but are available in both modes. Save failure remains visible after scrolling; tapping Retry cannot generate concurrent submissions. Dirty navigation invokes the existing guard. A valid retry preserves text, formatting and document details.
+
+## State, accessibility and localisation specification
+
+| State | Visual response | Accessibility / focus | Persistence rule |
+|---|---|---|---|
+| Loading | Skeleton plus descriptive progress | Busy region; no repeated announcements | No blank draft writes |
+| Empty | Clear starter action, no fake content | Named CTA and heading | Starter inserts into local draft only |
+| Dirty | Unsaved status; letter Save enabled | Polite status once, not per keystroke | Draft retained until save/discard |
+| Saving | Progress with stable button layout | Busy/disabled duplicate submit | Serialize mutations |
+| Save failed | Inline explanation, Retry/recovery | Alert on transition; draft stays focused | No automatic destructive reload |
+| Conflict | Specific conflict and recovery actions | Focusable recovery; no forced loss | Stop auto writes, never blind retry |
+| Preview updating/failed | Last-good page labelled accordingly | Status associated with preview | Preview failure never marks save failed or saved |
+| Exporting | Named progress, prevent duplicate export | Keep current context | Export intended saved revision only |
+| Restoring | Preview/warning then new revision | Confirm dialog focus lifecycle | Existing historical records retained |
+
+Use existing English/Bokmål locale provider and translation keys. New labels, errors, ARIA names and date examples require both locales. Respect document language independently of interface language where the current model supports it. Test long Norwegian words, æ/ø/å, long URLs, large contact blocks and empty sections. Every proposed state above is **Not Tested** until validated against the implementation.