From 5c72364899d547fec6366daf96d434c3bd26d3dd Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 08:49:47 +0200 Subject: [PATCH 1/3] docs: fix stale CLAUDE.md content after design-system refactoring Brand colors, font name, dev port, route tree, and card pattern were all outdated relative to layout.css and the current route structure. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 45 ++++++++++++++++++++++++++------------------- frontend/CLAUDE.md | 16 ++++++++-------- 2 files changed, 34 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 41bc39a4..f7c85503 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -54,7 +54,7 @@ cd backend cd frontend npm install -npm run dev # Dev server (port 3000) +npm run dev # Dev server (port 5173) npm run build # Production build npm run preview # Preview production build @@ -181,21 +181,28 @@ Input DTOs live flat in the domain package. Response types are the model entitie ``` frontend/src/routes/ -├── +layout.svelte Global header (sticky), nav links, logout -├── +layout.server.ts Loads current user, injects auth cookie -├── +page.svelte Home / document search -├── +page.server.ts Load: search documents; no actions +├── +layout.svelte / +layout.server.ts Global layout, auth cookie +├── +page.svelte / +page.server.ts Home / document search dashboard ├── documents/ -│ ├── [id]/+page.svelte Document detail (view + file preview) -│ └── [id]/edit/ Edit form (all metadata + file upload) -│ └── new/ Create form (same fields, empty) +│ ├── [id]/ Document detail (view + file preview) +│ ├── [id]/edit/ Edit form (all metadata + file upload) +│ ├── new/ Upload form +│ └── bulk-edit/ Multi-document edit ├── persons/ -│ ├── +page.svelte Person list with search -│ ├── [id]/+page.svelte Person detail (inline edit + merge) +│ ├── [id]/ Person detail +│ ├── [id]/edit/ Person edit form │ └── new/ Create person form -├── conversations/ Bilateral conversation timeline -├── admin/ User + group + tag management -└── login/ logout/ Auth pages +├── briefwechsel/ Bilateral conversation timeline (Briefwechsel) +├── aktivitaeten/ Unified activity feed (Chronik) +├── geschichten/ Stories — list, [id], [id]/edit, new +├── stammbaum/ Family tree (Stammbaum) +├── enrich/ Enrichment workflow — [id], done +├── admin/ User, group, tag, OCR, system management +├── hilfe/transkription/ Transcription help page +├── profile/ User profile settings +├── login/ logout/ register/ +├── forgot-password/ reset-password/ +└── demo/ Dev-only demos ``` ### API Client Pattern @@ -235,20 +242,20 @@ Brand color utilities (defined in `layout.css`): | Class | Value | Usage | | ------------ | --------- | -------------------------------- | -| `brand-navy` | `#002850` | Primary text, buttons, headers | -| `brand-mint` | `#A6DAD8` | Accents, hover underlines, icons | -| `brand-sand` | `#E4E2D7` | Page background, card borders | +| `brand-navy` | `#012851` | Primary text, buttons, headers | +| `brand-mint` | `#a1dcd8` | Accents, hover underlines, icons | +| `brand-sand` | `#f0efe9` | Page background (palette alias) | Typography: -- `font-serif` (Merriweather) — body text, document titles, names +- `font-serif` (Tinos) — body text, document titles, names - `font-sans` (Montserrat) — labels, metadata, UI chrome Card pattern for content sections: ```svelte -
-

Section Title

+
+

Section Title

``` diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md index 0061686a..677e7caa 100644 --- a/frontend/CLAUDE.md +++ b/frontend/CLAUDE.md @@ -30,7 +30,7 @@ src/ │ ├── documents/ # Document CRUD, detail, edit, upload │ ├── persons/ # Person directory, detail, edit, merge │ ├── briefwechsel/ # Bilateral conversation timeline -│ ├── chronik/ # Unified activity feed +│ ├── aktivitaeten/ # Unified activity feed (Chronik) │ ├── admin/ # User, group, tag, OCR, system management │ ├── api/ # Internal API proxies (server-side only) │ ├── login/ logout/ # Auth pages @@ -106,20 +106,20 @@ Brand color utilities (defined in `layout.css`): | Class | Value | Usage | | ------------ | --------- | -------------------------------- | -| `brand-navy` | `#002850` | Primary text, buttons, headers | -| `brand-mint` | `#A6DAD8` | Accents, hover underlines, icons | -| `brand-sand` | `#E4E2D7` | Page background, card borders | +| `brand-navy` | `#012851` | Primary text, buttons, headers | +| `brand-mint` | `#a1dcd8` | Accents, hover underlines, icons | +| `brand-sand` | `#f0efe9` | Page background (palette alias) | Typography: -- `font-serif` (Merriweather) — body text, document titles, names +- `font-serif` (Tinos) — body text, document titles, names - `font-sans` (Montserrat) — labels, metadata, UI chrome Card pattern for content sections: ```svelte -
-

Section

+
+

Section

``` @@ -137,7 +137,7 @@ Card pattern for content sections: ```bash cd frontend npm install -npm run dev # Dev server on port 5173 (or 3000 if --port 3000) +npm run dev # Dev server on port 5173 ``` ### Build & Preview -- 2.49.1 From d69a3abc3b1f0c482d7f5f56049f802fb075f9b0 Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 08:58:39 +0200 Subject: [PATCH 2/3] docs(personas): fix stale brand data in ui_expert persona MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update hex values → CSS var references, fix font (Merriweather→Tinos), card pattern (border-brand-sand→border-line, bg-white→bg-surface), and contrast table to remove hardcoded hex in favour of --palette-* names. Addresses Leonie's review blocker on PR #446. Co-Authored-By: Claude Sonnet 4.6 --- .claude/personas/ui_expert.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/.claude/personas/ui_expert.md b/.claude/personas/ui_expert.md index f8839e4c..ea13a3cf 100644 --- a/.claude/personas/ui_expert.md +++ b/.claude/personas/ui_expert.md @@ -38,10 +38,10 @@ Screen readers and search engines rely on landmarks to navigate. Every page need 2. **Use CSS custom properties for all brand colors** ```css -/* layout.css */ ---color-ink: #002850; ---color-accent: #A6DAD8; ---color-surface: #E4E2D7; +/* layout.css — semantic tokens backed by CSS variables (see --palette-* for raw values) */ +--color-ink: var(--c-ink); +--color-accent: var(--c-accent); +--color-surface: var(--c-surface); ``` ```svelte
@@ -103,9 +103,9 @@ unsaved work without warning. 1. **Enforce WCAG AA contrast ratios** ``` -brand-navy (#002850) on white: 14.5:1 -- AAA pass -brand-mint (#A6DAD8) on navy: 7.2:1 -- AAA pass for large text -Gray-500 on white: check >= 4.5:1 -- AA minimum for body text +brand-navy (--palette-navy) on white: ~14.5:1 -- AAA pass (verify exact value in layout.css) +brand-mint (--palette-mint) on navy: ~7.2:1 -- AAA pass for large text +Gray-500 on white: check >= 4.5:1 -- AA minimum for body text ``` Always verify contrast with a tool. AA is the floor (4.5:1 normal text, 3:1 large text). Target AAA (7:1) for body copy. @@ -134,8 +134,8 @@ Color-blind users (8% of men) cannot distinguish status by color alone. Always p /* Silver #CACAC9 on white = 1.5:1 -- fails all WCAG levels */ .caption { color: #CACAC9; } -/* brand-mint on white = 2.8:1 -- fails AA for normal text */ -.label { color: #A6DAD8; } +/* brand-mint on white = ~2.8:1 -- fails AA for normal text */ +.label { color: var(--palette-mint); } ``` Test every text color against its background. Decorative palette colors are for borders and backgrounds, not text. @@ -338,7 +338,7 @@ Test at 320px (small phone), 768px (tablet), and 1440px (desktop). Review diffs - +
Section titletext-xs font-bold uppercase tracking-widest 12px / 700Most commonly undersized
Card containerbg-white shadow-sm border border-brand-sand rounded-sm p-6
Card containerbg-surface shadow-sm border border-line rounded-sm p-6 padding 24px—
@@ -376,10 +376,10 @@ await page.setViewportSize({ width: 1440, height: 900 }); ## Domain Expertise ### Brand Palette -- **Primary**: brand-navy `#002850` (text, buttons, headers), brand-mint `#A6DAD8` (accents, hover), brand-sand `#E4E2D7` (backgrounds, borders) -- **Typography**: `font-serif` (Merriweather) for body/titles, `font-sans` (Montserrat) for labels/UI chrome -- **Card pattern**: `bg-white shadow-sm border border-brand-sand rounded-sm p-6` -- **Section title**: `text-xs font-bold uppercase tracking-widest text-gray-400 mb-5` +- **Primary**: `brand-navy` (`--palette-navy`) — text, buttons, headers; `brand-mint` (`--palette-mint`) — accents, hover; sand (`--palette-sand`) — page background (use `bg-canvas` or `bg-surface` as Tailwind utilities, not `bg-brand-sand`) +- **Typography**: `font-serif` (Tinos) for body/titles, `font-sans` (Montserrat) for labels/UI chrome +- **Card pattern**: `bg-surface shadow-sm border border-line rounded-sm p-6` +- **Section title**: `text-xs font-bold uppercase tracking-widest text-ink-3 mb-5` ### Dual-Audience Design (25-42 AND 60+) - Seniors: 16px minimum body text (prefer 18px), 44px touch targets (prefer 48px), redundant cues, calm layouts, persistent navigation, no timed interactions -- 2.49.1 From d01b9a7508ac440b75414b7fa3e144efa6001529 Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 09:01:40 +0200 Subject: [PATCH 3/3] docs(claude-md): replace hex values with CSS var refs, expand route trees Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 13 +++++++------ frontend/CLAUDE.md | 23 +++++++++++++++-------- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f7c85503..3628e703 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -200,6 +200,7 @@ frontend/src/routes/ ├── admin/ User, group, tag, OCR, system management ├── hilfe/transkription/ Transcription help page ├── profile/ User profile settings +├── users/[id]/ Public user profile page ├── login/ logout/ register/ ├── forgot-password/ reset-password/ └── demo/ Dev-only demos @@ -238,13 +239,13 @@ export const actions = { ### Styling Conventions (Tailwind CSS 4) -Brand color utilities (defined in `layout.css`): +Brand color tokens (defined in `layout.css`): -| Class | Value | Usage | -| ------------ | --------- | -------------------------------- | -| `brand-navy` | `#012851` | Primary text, buttons, headers | -| `brand-mint` | `#a1dcd8` | Accents, hover underlines, icons | -| `brand-sand` | `#f0efe9` | Page background (palette alias) | +| Token / Utility | CSS variable | Usage | +| ---------------- | ---------------- | ------------------------------------------------------- | +| `brand-navy` | `--palette-navy` | Tailwind utility — buttons, headers, primary text | +| `brand-mint` | `--palette-mint` | Tailwind utility — accents, hover underlines, icons | +| `--palette-sand` | `--palette-sand` | Palette constant only — use `bg-canvas` or `bg-surface` | Typography: diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md index 677e7caa..8b912685 100644 --- a/frontend/CLAUDE.md +++ b/frontend/CLAUDE.md @@ -33,8 +33,15 @@ src/ │ ├── aktivitaeten/ # Unified activity feed (Chronik) │ ├── admin/ # User, group, tag, OCR, system management │ ├── api/ # Internal API proxies (server-side only) -│ ├── login/ logout/ # Auth pages -│ └── ... +│ ├── geschichten/ # Stories (list, [id], [id]/edit, new) +│ ├── stammbaum/ # Family tree +│ ├── enrich/ # Enrichment workflow ([id], done) +│ ├── hilfe/transkription/ # Transcription help page +│ ├── profile/ # User profile settings +│ ├── users/[id]/ # Public user profile page +│ ├── login/ logout/ register/ +│ ├── forgot-password/ reset-password/ +│ └── demo/ # Dev-only demos ├── lib/ # Domain-based package structure (mirrors backend) │ ├── document/ # Document domain: components, stores, services, utils │ │ ├── annotation/ # Annotation overlay components @@ -102,13 +109,13 @@ export const actions = { ## Styling Conventions (Tailwind CSS 4) -Brand color utilities (defined in `layout.css`): +Brand color tokens (defined in `layout.css`): -| Class | Value | Usage | -| ------------ | --------- | -------------------------------- | -| `brand-navy` | `#012851` | Primary text, buttons, headers | -| `brand-mint` | `#a1dcd8` | Accents, hover underlines, icons | -| `brand-sand` | `#f0efe9` | Page background (palette alias) | +| Token / Utility | CSS variable | Usage | +| ---------------- | ---------------- | ------------------------------------------------------- | +| `brand-navy` | `--palette-navy` | Tailwind utility — buttons, headers, primary text | +| `brand-mint` | `--palette-mint` | Tailwind utility — accents, hover underlines, icons | +| `--palette-sand` | `--palette-sand` | Palette constant only — use `bg-canvas` or `bg-surface` | Typography: -- 2.49.1