subdocument-splitting-plan

plan/done/start-page-bea-wording-plan.md

@@ -0,0 +1,126 @@
+# Plan: Start page — make the beA context obvious
+
+**Status: Done**
+
+## Problem
+
+The start page (`src/routes/+page.svelte`) presents itself as a generic "PDF-Werkzeuge" site:
+
+- Hero headline: **"PDF-Werkzeuge"**
+- ZIP dropzone: label **"ZIP-Archiv bearbeiten"**, sublabel "ZIP-Datei hier ablegen oder zum
+  Auswählen klicken", aria label "ZIP-Archiv bearbeiten"
+- Drag overlay: **"ZIP-Archiv hier ablegen"**
+- `<title>`: `juri-merger — PDF-Werkzeuge`
+
+The ZIP the user is supposed to drop here is, in reality, an archive exported from the
+**besondere elektronische Anwaltspostfach (beA)** — that's what `/tools/bea` processes and what
+the whole product ("beA-Edit", see `agents.md`) exists for. Nothing on the start page says so.
+A user seeing any random ZIP has no hint which one belongs in this slot.
+
+Goal: keep the toolbox-hub structure (hero + beA entry point + tool tiles), but reframe the copy
+so that (a) the beA origin of the expected ZIP is unmistakable and (b) the overall positioning
+shifts from generic "PDF tools" to "workbench for beA exports (+ extra PDF tools)".
+
+## Target copy (proposal)
+
+### 1. Hero / page identity
+
+- `<title>`: from `juri-merger — PDF-Werkzeuge` to
+  `beA-Edit — Werkzeugkasten für das besondere elektronische Anwaltspostfach` (long form) or
+  `… für beA-Archive` (short form, see D1).
+- H1: from `PDF-Werkzeuge` to **`Werkzeugkasten für beA`**.
+- Subline: currently only the generic privacy line. Replace with a lead sentence explaining beA:
+  „Bereiten Sie ZIP-Archive aus dem besonderen elektronischen Anwaltspostfach (beA) auf — plus
+  praktische PDF-Werkzeuge.“ — then keep the existing privacy line as a second sentence.
+
+This keeps "PDF-Werkzeuge" discoverable for anyone who knew the old wording but leads with beA.
+
+### 2. ZIP entry point (the core fix)
+
+- Label: **„beA-ZIP öffnen"** instead of "ZIP-Archiv bearbeiten".
+- Sublabel: „ZIP aus dem besonderen elektronischen Anwaltspostfach (beA) hier ablegen oder zum
+  Auswählen klicken".
+- Add a small example/hint line inside or under the dropzone:
+  „Tipp: In beA exportierte Archive enden meist auf `.zip` und enthalten Anlagen als PDF."
+  (exact wording see D2 — including whether to show typical archive contents)
+- Icon inside the dropzone next to the "+" (e.g. Lucide `Mail`/`Postbox`-like or `Archive`)
+  to visually distinguish it from the plain-PDF tool tiles below.
+- Dropzone keeps `accept=".zip,…"`. No functional change to filtering — dropping any ZIP still
+  routes to `/tools/bea`.
+
+### 3. Full-window drag overlay
+
+- Text: **„beA-ZIP hier ablegen"** (currently "ZIP-Archiv hier ablegen"), optionally with the
+  subline „Archive aus dem besonderen elektronischen Anwaltspostfach".
+
+### 4. Tool grid section heading
+
+- Currently: „Werkzeuge". Change to **„Weitere PDF-Werkzeuge"** — this is where the words
+  "PDF-Werkzeuge" live on after the hero shift, clarifying these tiles are the _secondary_,
+  general-purpose part while beA sits above.
+
+## Code touchpoints
+
+All copy lives in exactly three files; no component API changes required:
+
+1. `src/routes/+page.svelte`
+
+- `<title>`, H1 + sublines in the Hero block
+- props passed to `FileDropzone`: `ariaLabel`, `label`, `sublabel` (add a hint element below
+  the dropzone if D2 decides for it)
+- drag overlay text
+- "Werkzeuge" → "Weitere PDF-Werkzeuge"
+
+1. `src/routes/+layout.svelte` — only if global header/footer copy mentions the product role
+   (check during implementation; likely unchanged).
+2. `tests/e2e/toolbox.spec.ts`
+   - Line ~88 asserts the heading name `'PDF-Werkzeuge'` → update to the new H1
+     (`'Werkzeugkasten für beA'`).
+   - Any other selectors keyed on the old labels must be swept (search tests for
+     "ZIP-Archiv" / "PDF-Werkzeuge").
+
+Accessibility notes:
+
+- The new sublabel contains the full term + abbreviation once per page; use `abbr`-free plain
+  text (screen readers handle "beA" fine as-is). Keep `aria-label` identical to the visible
+  label to avoid divergence.
+
+## Open decisions (defaults marked ✅)
+
+### D1 — How far to push the rebrand?
+
+- ✅ **A. Lead with beA, keep toolbox**: H1 "Werkzeugkasten für beA", tool grid becomes
+  "Weitere PDF-Werkzeuge". Minimal risk, preserves both audiences.
+- B. Full rename to "beA-Editor": hero only about beA, tools demoted into an opt-in section
+  further down. Stronger positioning, hides the newer tools behind scroll/click.
+
+### D2 — Where does the explainer text live?
+
+- ✅ **A. Short hint line inside/below the dropzone** (one sentence naming "besonderes
+  elektronisches Anwaltspostfach"). Cheap, always visible where it matters.
+- B. Info popover/question-mark icon expanding details (typical file names, how to export from
+  beA). More room, more moving parts.
+- C. Both A and B if users actually need export instructions (needs user feedback).
+
+### D3 — Also update other beA-named strings for consistency?
+
+- ✅ **A. Yes, sweep for consistency**: e.g. documents/README references and `ZipDropzone.svelte`
+  sublabels inside `/tools/bea` should also say "beA-ZIP" so terminology matches across pages.
+  Copy-only sweep, no behavior change.
+- B. Only the start page; leave inner pages untouched.
+
+## Implementation phases
+
+Single phase — this is copy + one test file.
+
+1. Apply copy changes in `src/routes/+page.svelte` (+ optional consistency sweep per D3).
+2. Update `tests/e2e/toolbox.spec.ts` expectations.
+3. Run `pnpm check`, `pnpm lint`, `pnpm build`, and the e2e suite.
+4. Manual browser pass: hero, dropzone, drag-overlay, keyboard focus order unchanged;
+   verify window-wide drag of a ZIP still lands on `/tools/bea`.
+5. Update `agents.md` / README wording if D3 = A touches those files.
+
+## Risks
+
+- Very low. Pure copy change; only test breakage possible (heading/label assertions), covered
+  by running the spec suite. SSR-safe: no new logic, all changes static markup.