familienarchiv/design_handoff_familienarchiv_redesign/README.md

# Handoff: Familienarchiv — Visual Redesign ("Mappe" direction)

## Overview

This package hands off a **complete visual redesign of the Familienarchiv web app** to a
developer using Claude Code. Familienarchiv is a private digital family archive
(German-first SvelteKit app) for digitising, transcribing, tagging and searching
historical correspondence.

The redesign unifies every page under one system — internally called **"Mappe"** (German
for *folder/portfolio*): a warm, archival, institutional look built on the De Gruyter Brill
corporate identity. It also **adds three new sections** that did not exist in the old app
(**Geschichten**, **Zeitstrahl**, **Aktivitäten**) alongside redesigns of the existing ones.

The work is broken into an **epic with foundation-first stories**. Read the three docs in
this order:

1. **`README.md`** (this file) — what's here, fidelity, how to use it.
2. **`DESIGN_RULES.md`** — the binding visual law (tokens, type, the shared patterns).
   *Read this before writing any code.*
3. **`EPIC.md`** — the epic + ordered stories + acceptance criteria. *Implement in order.*

## About the design files

The files in `prototypes/` are **design references created in HTML** — high-fidelity
prototypes that show the intended look and behaviour exactly. **They are not the production
codebase and must not be shipped as-is.** They are authored as "Design Components"
(`.dc.html`) for a prototyping runtime (`support.js`); that runtime is **not** part of the
target app.

Your task is to **recreate these designs inside the existing Familienarchiv codebase**
(SvelteKit 2 + Svelte 5 + Tailwind 4 + Paraglide i18n) using its established patterns —
real Svelte components, real routes, real i18n message keys. Where the prototype uses a
made-up runtime construct (`<dc-import>`, `<sc-for>`, `renderVals()`), map it to the
codebase's idiom (a Svelte component import, an `{#each}` block, component props/state).

### Why HTML prototypes are the source of truth

Every colour, size, weight, spacing and radius is written **inline** in the prototype
markup, and the files **render**. When the written spec and a prototype disagree, **the
prototype wins** — open it in a browser and measure. Treat `DESIGN_RULES.md` and `EPIC.md`
as the *intent and ordering*, and the prototypes as the *pixel ground truth*.

To view a prototype: open any `prototypes/*.dc.html` in a browser (they are self-contained;
`colors_and_type.css`, `support.js` and `assets/icons/` sit alongside them). Use the
**Hell / Dunkel** toggle in the header to verify dark mode.

## Fidelity

**High-fidelity (hifi).** Final colours, typography, spacing, radii, shadows, copy and
interaction intent are all decided. Recreate pixel-perfectly using the codebase's existing
libraries. Do not re-interpret the visual language — apply it.

## What's in this bundle

```
design_handoff_familienarchiv_redesign/
├── README.md            ← you are here
├── DESIGN_RULES.md      ← binding tokens + shared patterns (the "rules")
├── EPIC.md              ← epic, stories, acceptance criteria (implement in order)
├── _AUTHORING_KIT.md    ← the contract every prototype was authored against (copy-verbatim snippets)
└── prototypes/          ← runnable hifi references (source of truth)
    │   ── original section screens ──
    ├── ArchiveHeader.dc.html      shared header + nav + theme toggle
    ├── Dokumente.dc.html          dashboard
    ├── Personen.dc.html           person directory
    ├── Geschichten.dc.html        curated story collections (list)
    ├── Geschichte.dc.html         single story detail (2 variants)
    ├── Zeitstrahl.dc.html         chronological timeline
    ├── Aktivitaeten.dc.html       activity feed
    ├── Regeln.dc.html             the design-rules spec page (internal reference)
    │   ── added screens (the previously un-prototyped pages) ──
    ├── Dokumente-Liste.dc.html    document search / grouped results
    ├── Dokument-Detail.dc.html    document viewer + transcription workbench
    ├── Dokument-Bearbeiten.dc.html edit / new / bulk-edit (variant prop)
    ├── PersonDetail.dc.html       person detail (read)
    ├── PersonForm.dc.html         person new / edit (variant prop)
    ├── PersonReview.dc.html       provisional-person triage workflow
    ├── Geschichte-Editor.dc.html  story authoring: new / story / journey (variant prop)
    ├── Ereignis-Editor.dc.html    timeline event new / edit (variant prop)
    ├── Stammbaum.dc.html          family tree
    ├── Themen.dc.html             topics / tag directory
    ├── Anreicherung.dc.html       enrich workflow: list / step / done (variant prop)
    ├── Profil.dc.html             account settings + public profile (variant prop)
    ├── Anmeldung.dc.html          auth: login / register / forgot / reset (variant prop, no app header)
    ├── Hilfe-Transkription.dc.html transcription help / guidelines
    │   ── shared assets ──
    ├── colors_and_type.css        design tokens (port into the app)
    ├── support.js                 prototype runtime — DO NOT ship
    └── assets/icons/              De Gruyter "Simple" icons used by the screens
```

> **Status note (2026-06-16).** Two facts updated this bundle since the original handoff:
> 1. **This is now an alignment effort, not a greenfield reskin.** The token system
>    (`DESIGN_RULES §1–2`), dark mode, the app header, and the three "new" sections
>    (Geschichten, Zeitstrahl, Aktivitäten) **already exist in the codebase**. Foundation
>    Stories 1–4 are *close-out + extraction* of the missing shared primitives (`PageHeader`,
>    `Avatar`/`avatarFor`, `SegmentedControl`, `Card`, `MetaLine`, `EmptyState`, `StatusDot`),
>    not from-scratch builds. See the Gitea milestone **"Mappe Visual Redesign"** for the
>    issue-level breakdown (shared components, then pages).
> 2. **Briefwechsel was dropped** — that feature was removed from the product, so its
>    prototype and nav entry are gone. Admin + OCR pages are deferred to a phase-2 milestone.

## Assets

- **Icons** — De Gruyter "Simple" Medium-24px SVGs in `prototypes/assets/icons/`. In the
  real app these live at `static/degruyter-icons/Simple/…` and are rendered as `<img>`
  tags. Reuse the existing app copies; this bundle ships only the subset the redesign
  touches so you can see which are needed.
- **Fonts** — Montserrat + Tinos via Google Fonts (substitutes for Gotham + Times). The
  `@import` is at the top of `colors_and_type.css`. If the team has the licensed Gotham/Times
  faces, swap them in and keep the variable names.
- **Logo** — none. The brand is the wordmark `FAMILIENARCHIV` (Montserrat Bold, uppercase,
  `letter-spacing:.16em`) on the navy header.

## Target codebase notes

- **i18n**: all copy in the prototypes is German. The app is German-first with `en`/`es`
  translations (Paraglide). Every visible string must become a message key, German written
  first. Existing keys live in `frontend/messages/{de,en,es}.json`.
- **Icons as `<img>`**: keep the app convention — never inline SVG, never icon fonts. Dark
  mode inverts them globally via `img[src*='degruyter-icons'] { filter: invert(1); }`.
- **Tailwind 4**: the prototypes use inline styles for clarity. Port them to the codebase's
  Tailwind utilities / `@theme` tokens — but the *values* must match the tokens in
  `DESIGN_RULES.md` exactly.