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.