docs: fix stale CLAUDE.md content after design-system refactoring #446

marcel · 2026-05-06T08:50:35+02:00

marcel commented

2026-05-06 08:50:35 +02:00

Summary

Fix brand color hex values (brand-navy, brand-mint, brand-sand) — all three were stale relative to layout.css
Fix serif font name: Merriweather → Tinos (De Gruyter Brill CI)
Fix frontend dev server port: 3000 → 5173
Update route structure tree: add all missing routes (briefwechsel/, aktivitaeten/, geschichten/, stammbaum/, enrich/, etc.), remove non-existent conversations/
Fix card pattern: replace bg-white border border-brand-sand with bg-surface border border-line (semantic tokens, supports dark mode)
Fix frontend/CLAUDE.md route tree: chronik/ → aktivitaeten/

Test plan

Verify no stale strings remain: grep -r "002850\|A6DAD8\|E4E2D7\|Merriweather\|port 3000\|conversations/\|brand-sand\|chronik/" CLAUDE.md frontend/CLAUDE.md returns nothing
Verify hex values, font, port, and route names match layout.css and find frontend/src/routes -maxdepth 1 -type d

🤖 Generated with Claude Code

## Summary - Fix brand color hex values (`brand-navy`, `brand-mint`, `brand-sand`) — all three were stale relative to `layout.css` - Fix serif font name: Merriweather → Tinos (De Gruyter Brill CI) - Fix frontend dev server port: 3000 → 5173 - Update route structure tree: add all missing routes (`briefwechsel/`, `aktivitaeten/`, `geschichten/`, `stammbaum/`, `enrich/`, etc.), remove non-existent `conversations/` - Fix card pattern: replace `bg-white border border-brand-sand` with `bg-surface border border-line` (semantic tokens, supports dark mode) - Fix `frontend/CLAUDE.md` route tree: `chronik/` → `aktivitaeten/` ## Test plan - [ ] Verify no stale strings remain: `grep -r "002850\|A6DAD8\|E4E2D7\|Merriweather\|port 3000\|conversations/\|brand-sand\|chronik/" CLAUDE.md frontend/CLAUDE.md` returns nothing - [ ] Verify hex values, font, port, and route names match `layout.css` and `find frontend/src/routes -maxdepth 1 -type d` 🤖 Generated with [Claude Code](https://claude.com/claude-code)

marcel added 1 commit 2026-05-06 08:50:36 +02:00

docs: fix stale CLAUDE.md content after design-system refactoring

CI / Unit & Component Tests (push) Failing after 3m45s

Details

CI / OCR Service Tests (push) Successful in 44s

Details

CI / Backend Unit Tests (push) Failing after 3m25s

Details

CI / Unit & Component Tests (pull_request) Failing after 3m29s

Details

CI / OCR Service Tests (pull_request) Successful in 34s

Details

CI / Backend Unit Tests (pull_request) Failing after 3m13s

Details

5c72364899

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 <noreply@anthropic.com>

marcel commented

2026-05-06 08:52:24 +02:00

👨‍💻 Felix Brandt — Senior Fullstack Developer

Verdict: ⚠️ Approved with concerns

The changes are clean, targeted, and correct. One ambiguity in the color table needs addressing before this becomes the canonical reference.

Blocker

brand-sand listed under "Class" column but is not a Tailwind utility

The color table header says "Class", implying all three rows are usable Tailwind utility prefixes. But in layout.css, only --color-brand-navy and --color-brand-mint are defined as static @theme tokens — --color-brand-sand is not. This means:

bg-brand-navy, border-brand-navy → ✅ valid Tailwind utilities
bg-brand-mint, border-brand-mint → ✅ valid
bg-brand-sand, border-brand-sand → ❌ not generated, will silently produce nothing

The description change to "Page background (palette alias)" hints at this, but a developer reading the table will assume all rows are usable classes. The old card pattern (border-brand-sand) was the canonical example of this mistake — this PR correctly fixes the card example but leaves the door open via the table.

Suggested fix:

| Token        | Value     | Usage                            |
| ------------ | --------- | -------------------------------- |
| `brand-navy` | `#012851` | Tailwind utility — buttons, headers, primary text |
| `brand-mint` | `#a1dcd8` | Tailwind utility — accents, hover underlines       |
| `--palette-sand` | `#f0efe9` | Raw palette constant only — use `bg-canvas` or `bg-surface` instead |

Or at minimum, rename the column "Token / Class" and add a note that brand-sand is palette-only.

Suggestions

frontend/CLAUDE.md route tree still uses └── ... as a trailing ellipsis, hiding geschichten/, stammbaum/, enrich/ etc. The root CLAUDE.md was fully expanded — would be good to align both files.
users/[id] route exists on disk but appears in neither tree.

## 👨‍💻 Felix Brandt — Senior Fullstack Developer **Verdict: ⚠️ Approved with concerns** The changes are clean, targeted, and correct. One ambiguity in the color table needs addressing before this becomes the canonical reference. ### Blocker **`brand-sand` listed under "Class" column but is not a Tailwind utility** The color table header says "Class", implying all three rows are usable Tailwind utility prefixes. But in `layout.css`, only `--color-brand-navy` and `--color-brand-mint` are defined as static `@theme` tokens — `--color-brand-sand` is not. This means: - `bg-brand-navy`, `border-brand-navy` → ✅ valid Tailwind utilities - `bg-brand-mint`, `border-brand-mint` → ✅ valid - `bg-brand-sand`, `border-brand-sand` → ❌ not generated, will silently produce nothing The description change to "Page background (palette alias)" hints at this, but a developer reading the table will assume all rows are usable classes. The old card pattern (`border-brand-sand`) was the canonical example of this mistake — this PR correctly fixes the card example but leaves the door open via the table. **Suggested fix:** ```markdown | Token | Value | Usage | | ------------ | --------- | -------------------------------- | | `brand-navy` | `#012851` | Tailwind utility — buttons, headers, primary text | | `brand-mint` | `#a1dcd8` | Tailwind utility — accents, hover underlines | | `--palette-sand` | `#f0efe9` | Raw palette constant only — use `bg-canvas` or `bg-surface` instead | ``` Or at minimum, rename the column "Token / Class" and add a note that `brand-sand` is palette-only. ### Suggestions - `frontend/CLAUDE.md` route tree still uses `└── ...` as a trailing ellipsis, hiding `geschichten/`, `stammbaum/`, `enrich/` etc. The root `CLAUDE.md` was fully expanded — would be good to align both files. - `users/[id]` route exists on disk but appears in neither tree.

marcel commented

2026-05-06 08:52:31 +02:00

🏗️ Markus Keller — Senior Application Architect

Verdict: ✅ Approved

This is a docs-only PR and it does its job well. A few observations.

What's correct

Route tree expansion is the most important fix here. conversations/ being wrong was a genuine navigation hazard — any new contributor looking for the Briefwechsel route would be lost. The corrected tree is accurate.
The card pattern migration from border-brand-sand bg-white to border-line bg-surface correctly reflects the semantic token architecture. The old example coupled presentation to raw palette values; the new example couples to semantic tokens that survive theming. This is the right direction.
The tier structure (documents, persons, briefwechsel, aktivitaeten, geschichten as first-class routes) matches what's documented in docs/ARCHITECTURE.md.

Minor observation

The api/ proxy route group is present on disk (frontend/src/routes/api/) but not in either route tree. It's an implementation detail (server-side SSR proxy, not user-facing), so omitting it from CLAUDE.md is defensible — but worth a one-liner comment explaining what it is, to prevent a future reader from wondering why requests to /api/ work despite no visible route.

No architecture concerns with this PR.

## 🏗️ Markus Keller — Senior Application Architect **Verdict: ✅ Approved** This is a docs-only PR and it does its job well. A few observations. ### What's correct - Route tree expansion is the most important fix here. `conversations/` being wrong was a genuine navigation hazard — any new contributor looking for the Briefwechsel route would be lost. The corrected tree is accurate. - The card pattern migration from `border-brand-sand bg-white` to `border-line bg-surface` correctly reflects the semantic token architecture. The old example coupled presentation to raw palette values; the new example couples to semantic tokens that survive theming. This is the right direction. - The tier structure (documents, persons, briefwechsel, aktivitaeten, geschichten as first-class routes) matches what's documented in `docs/ARCHITECTURE.md`. ### Minor observation The `api/` proxy route group is present on disk (`frontend/src/routes/api/`) but not in either route tree. It's an implementation detail (server-side SSR proxy, not user-facing), so omitting it from CLAUDE.md is defensible — but worth a one-liner comment explaining what it is, to prevent a future reader from wondering why requests to `/api/` work despite no visible route. No architecture concerns with this PR.

marcel commented

2026-05-06 08:52:37 +02:00

🖥️ Tobias Wendt — DevOps & Platform Engineer

Verdict: ✅ Approved

Pure docs change. Infrastructure is unaffected. One thing worth clarifying for future readers.

What's correct

Port comment fixed from 3000 to 5173 — this matches what docker-compose.yml publishes ("${PORT_FRONTEND}:5173"). A new developer following the docs will now land on the right port.

Observation (not a blocker)

docker-compose.yml still contains:

APP_BASE_URL: ${APP_BASE_URL:-http://localhost:3000}

This is the application's public-facing URL (used for email links, OAuth callbacks, etc.) — not the dev server port. The two are different things. But a new developer who just read "dev server is 5173" and then sees 3000 in the Compose file will be confused.

Consider a one-line comment in docker-compose.yml:

APP_BASE_URL: ${APP_BASE_URL:-http://localhost:3000}  # public-facing URL, not the frontend dev server port (5173)

Not blocking this docs PR, but worth a follow-up task.

## 🖥️ Tobias Wendt — DevOps & Platform Engineer **Verdict: ✅ Approved** Pure docs change. Infrastructure is unaffected. One thing worth clarifying for future readers. ### What's correct Port comment fixed from `3000` to `5173` — this matches what `docker-compose.yml` publishes (`"${PORT_FRONTEND}:5173"`). A new developer following the docs will now land on the right port. ### Observation (not a blocker) `docker-compose.yml` still contains: ```yaml APP_BASE_URL: ${APP_BASE_URL:-http://localhost:3000} ``` This is the *application's public-facing URL* (used for email links, OAuth callbacks, etc.) — not the dev server port. The two are different things. But a new developer who just read "dev server is 5173" and then sees `3000` in the Compose file will be confused. Consider a one-line comment in `docker-compose.yml`: ```yaml APP_BASE_URL: ${APP_BASE_URL:-http://localhost:3000} # public-facing URL, not the frontend dev server port (5173) ``` Not blocking this docs PR, but worth a follow-up task.

marcel commented

2026-05-06 08:52:41 +02:00

🔒 Nora "NullX" Steiner — Application Security Engineer

Verdict: ✅ Approved

Documentation-only change. Zero attack surface impact.

What I checked

No credentials, secrets, or tokens touched
No auth configuration modified
No security annotations changed
No new endpoints or routes introduced — only the documentation of existing routes corrected
No change to permission model, CORS config, or session handling

Clean

The PR removes incorrect route names from the docs and corrects color/font values. Nothing here creates, widens, or obscures a security boundary. Merge freely.

## 🔒 Nora "NullX" Steiner — Application Security Engineer **Verdict: ✅ Approved** Documentation-only change. Zero attack surface impact. ### What I checked - No credentials, secrets, or tokens touched - No auth configuration modified - No security annotations changed - No new endpoints or routes introduced — only the documentation of existing routes corrected - No change to permission model, CORS config, or session handling ### Clean The PR removes incorrect route names from the docs and corrects color/font values. Nothing here creates, widens, or obscures a security boundary. Merge freely.

marcel commented

2026-05-06 08:52:47 +02:00

🧪 Sara Holt — QA Engineer & Test Strategist

Verdict: ✅ Approved

Documentation-only PR. No test coverage required or applicable.

What I checked

No production logic changed — no new test cases needed
The PR description includes a verification grep command that covers the primary risk (stale strings re-entering via copy-paste)
The card pattern update (border-brand-sand → border-line) is already covered passively — axe-playwright and visual regression tests running on existing pages will catch any layout regressions if the class change had unintended side effects (it won't, since these are doc examples, not live code)

Suggestion

The test plan verifies that old strings are gone but doesn't verify the new values are correct. A tighter test plan would add:

# Verify updated values match layout.css
grep "#012851" CLAUDE.md    # brand-navy
grep "a1dcd8" CLAUDE.md     # brand-mint
grep "Tinos" CLAUDE.md      # font
grep "5173" CLAUDE.md       # port

Low stakes for a docs PR, but good habit when documenting values that must stay in sync with source files.

## 🧪 Sara Holt — QA Engineer & Test Strategist **Verdict: ✅ Approved** Documentation-only PR. No test coverage required or applicable. ### What I checked - No production logic changed — no new test cases needed - The PR description includes a verification grep command that covers the primary risk (stale strings re-entering via copy-paste) - The card pattern update (`border-brand-sand` → `border-line`) is already covered passively — axe-playwright and visual regression tests running on existing pages will catch any layout regressions if the class change had unintended side effects (it won't, since these are doc examples, not live code) ### Suggestion The test plan verifies that old strings are gone but doesn't verify the new values are correct. A tighter test plan would add: ```bash # Verify updated values match layout.css grep "#012851" CLAUDE.md # brand-navy grep "a1dcd8" CLAUDE.md # brand-mint grep "Tinos" CLAUDE.md # font grep "5173" CLAUDE.md # port ``` Low stakes for a docs PR, but good habit when documenting values that must stay in sync with source files.

marcel commented

2026-05-06 08:52:59 +02:00

🎨 Leonie Voss — UX Designer & Brand Specialist

Verdict: 🚫 Changes requested

The CLAUDE.md fixes are correct and necessary — but this PR misses the most authoritative brand reference that LLM assistants actually use for code generation: .claude/personas/ui_expert.md (my own persona file). That file still contains every stale value this PR is trying to fix.

Blocker: `ui_expert.md` persona file has stale brand data

.claude/personas/ui_expert.md — Domain Expertise section (never changes unless explicitly edited):

### Brand Palette
- **Primary**: brand-navy `#002850` ...   ← wrong, should be #012851
- brand-mint `#A6DAD8` ...               ← wrong, should be #a1dcd8
- brand-sand `#E4E2D7` ...               ← wrong, should be #f0efe9
- **Typography**: `font-serif` (Merriweather) ...  ← wrong, should be Tinos
- **Card pattern**: `bg-white shadow-sm border border-brand-sand rounded-sm p-6`  ← wrong

Also the DO example in the "In Our Stack" section uses hardcoded stale hex values in a CSS comment:

/* layout.css */
--color-ink: #002850;      ← stale
--color-accent: #A6DAD8;   ← stale
--color-surface: #E4E2D7;  ← stale

When an LLM agent uses the ui_expert persona to review or generate UI code, it will pull brand guidance from this file — overriding the now-correct CLAUDE.md values. The two sources will directly contradict each other.

This PR's stated goal is ensuring docs represent the current state. The persona file is a doc. It must be updated in the same commit.

Also: `brand-sand` column label ambiguity

The color table column is headed "Class" but brand-sand (--palette-sand) is not a Tailwind utility class — only brand-navy and brand-mint are defined as --color-brand-* tokens and generate Tailwind utilities. Writing bg-brand-sand in a component will silently produce nothing. I'd rather the table clearly distinguish "Tailwind utility" from "raw palette constant used via semantic tokens."

Minor

The STYLEGUIDE.md in docs/ already has the correct values (#012851, #a1dcd8, Tinos). This PR brings CLAUDE.md in line — once the persona file is updated, all three sources will agree.

## 🎨 Leonie Voss — UX Designer & Brand Specialist **Verdict: 🚫 Changes requested** The CLAUDE.md fixes are correct and necessary — but this PR misses the most authoritative brand reference that LLM assistants actually use for code generation: `.claude/personas/ui_expert.md` (my own persona file). That file still contains every stale value this PR is trying to fix. ### Blocker: `ui_expert.md` persona file has stale brand data `.claude/personas/ui_expert.md` — **Domain Expertise section** (never changes unless explicitly edited): ```markdown ### Brand Palette - **Primary**: brand-navy `#002850` ... ← wrong, should be #012851 - brand-mint `#A6DAD8` ... ← wrong, should be #a1dcd8 - brand-sand `#E4E2D7` ... ← wrong, should be #f0efe9 - **Typography**: `font-serif` (Merriweather) ... ← wrong, should be Tinos - **Card pattern**: `bg-white shadow-sm border border-brand-sand rounded-sm p-6` ← wrong ``` Also the DO example in the **"In Our Stack"** section uses hardcoded stale hex values in a CSS comment: ```css /* layout.css */ --color-ink: #002850; ← stale --color-accent: #A6DAD8; ← stale --color-surface: #E4E2D7; ← stale ``` When an LLM agent uses the `ui_expert` persona to review or generate UI code, it will pull brand guidance from this file — overriding the now-correct CLAUDE.md values. The two sources will directly contradict each other. This PR's stated goal is ensuring docs represent the current state. The persona file is a doc. It must be updated in the same commit. ### Also: `brand-sand` column label ambiguity The color table column is headed "Class" but `brand-sand` (`--palette-sand`) is **not** a Tailwind utility class — only `brand-navy` and `brand-mint` are defined as `--color-brand-*` tokens and generate Tailwind utilities. Writing `bg-brand-sand` in a component will silently produce nothing. I'd rather the table clearly distinguish "Tailwind utility" from "raw palette constant used via semantic tokens." ### Minor The STYLEGUIDE.md in `docs/` already has the correct values (`#012851`, `#a1dcd8`, Tinos). This PR brings CLAUDE.md in line — once the persona file is updated, all three sources will agree.

marcel commented

2026-05-06 08:53:08 +02:00

📋 Elicit — Requirements Engineer & Documentation Analyst

Verdict: ⚠️ Approved with concerns

Reviewing against the stated goal: "docs now represent the current state of the software." The PR makes meaningful improvements but leaves two documentation completeness gaps.

Concerns

1. frontend/CLAUDE.md route tree is still incomplete

Root CLAUDE.md was fully expanded — every route is listed. But frontend/CLAUDE.md still truncates with └── ...:

│   ├── login/ logout/   # Auth pages
│   └── ...

This hides geschichten/, stammbaum/, enrich/, hilfe/, profile/, register/, forgot-password/, reset-password/ — the same routes the root CLAUDE.md now correctly lists. A developer working in frontend/ and reading only frontend/CLAUDE.md (the closer, more relevant doc) gets an incomplete picture.

2. users/[id] route exists but appears in neither tree

frontend/src/routes/users/[id]/+page.svelte exists on disk. Neither route tree mentions it. If it's a valid user-facing route, it belongs in the tree. If it's vestigial or internal, a comment noting that would prevent confusion.

3. Ambiguous "Class" column for brand-sand

The table documents brand-sand under a "Class" column alongside brand-navy and brand-mint, which are valid Tailwind utility prefixes. But brand-sand is a raw palette constant — using it as a Tailwind class (bg-brand-sand, border-brand-sand) silently fails. The requirement "docs represent current state" is only half-met here: the hex is now correct, but the semantics of the entry are still misleading.

What's good

Removing conversations/ and replacing with briefwechsel/ is the single highest-value fix in this PR — it directly corrects a navigation dead-end for anyone following the docs.
Color hex values and font name are now verifiable against layout.css.
Card pattern now uses semantic tokens, which is the correct abstraction level for a pattern example.

## 📋 Elicit — Requirements Engineer & Documentation Analyst **Verdict: ⚠️ Approved with concerns** Reviewing against the stated goal: *"docs now represent the current state of the software."* The PR makes meaningful improvements but leaves two documentation completeness gaps. ### Concerns **1. `frontend/CLAUDE.md` route tree is still incomplete** Root `CLAUDE.md` was fully expanded — every route is listed. But `frontend/CLAUDE.md` still truncates with `└── ...`: ``` │ ├── login/ logout/ # Auth pages │ └── ... ``` This hides `geschichten/`, `stammbaum/`, `enrich/`, `hilfe/`, `profile/`, `register/`, `forgot-password/`, `reset-password/` — the same routes the root CLAUDE.md now correctly lists. A developer working in `frontend/` and reading only `frontend/CLAUDE.md` (the closer, more relevant doc) gets an incomplete picture. **2. `users/[id]` route exists but appears in neither tree** `frontend/src/routes/users/[id]/+page.svelte` exists on disk. Neither route tree mentions it. If it's a valid user-facing route, it belongs in the tree. If it's vestigial or internal, a comment noting that would prevent confusion. **3. Ambiguous "Class" column for `brand-sand`** The table documents `brand-sand` under a "Class" column alongside `brand-navy` and `brand-mint`, which *are* valid Tailwind utility prefixes. But `brand-sand` is a raw palette constant — using it as a Tailwind class (`bg-brand-sand`, `border-brand-sand`) silently fails. The requirement "docs represent current state" is only half-met here: the hex is now correct, but the semantics of the entry are still misleading. ### What's good - Removing `conversations/` and replacing with `briefwechsel/` is the single highest-value fix in this PR — it directly corrects a navigation dead-end for anyone following the docs. - Color hex values and font name are now verifiable against `layout.css`. - Card pattern now uses semantic tokens, which is the correct abstraction level for a pattern example.

marcel added 2 commits 2026-05-06 09:02:18 +02:00

docs(personas): fix stale brand data in ui_expert persona d69a3abc3b

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 <noreply@anthropic.com>

docs(claude-md): replace hex values with CSS var refs, expand route trees

CI / Unit & Component Tests (pull_request) Failing after 3m31s

Details

CI / OCR Service Tests (pull_request) Successful in 35s

Details

CI / Backend Unit Tests (pull_request) Failing after 3m16s

Details

CI / Unit & Component Tests (push) Failing after 3m23s

Details

CI / OCR Service Tests (push) Successful in 30s

Details

CI / Backend Unit Tests (push) Failing after 3m19s

Details

d01b9a7508

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marcel referenced this issue from a commit

2026-05-06 09:02:18 +02:00

docs(personas): fix stale brand data in ui_expert persona

marcel commented

2026-05-06 09:02:34 +02:00

Review concerns addressed

All open concerns from the multi-persona review have been resolved across two commits.

`d69a3abc` — docs(personas): fix stale brand data in ui_expert persona

Leonie's concern — stale hex values in ui_expert.md:

Domain Expertise section: replaced #002850 / #A6DAD8 / #E4E2D7 with --palette-navy / --palette-mint / --palette-sand; noted that sand is a palette constant, not a Tailwind utility — use bg-canvas / bg-surface instead
Font corrected: Merriweather → Tinos in Domain Expertise section
Card pattern: bg-white shadow-sm border border-brand-sand rounded-sm p-6 → bg-surface shadow-sm border border-line rounded-sm p-6
Section heading: text-gray-400 → text-ink-3
CSS DO#1 example: replaced hardcoded hex values in CSS custom property examples with var(--c-ink) / var(--c-accent) / var(--c-surface) references
Contrast table: replaced hex values with CSS variable names; added "verify in layout.css" qualifier on the ratio values
impl-ref table: updated card class from bg-white shadow-sm border border-brand-sand rounded-sm p-6 to bg-surface shadow-sm border border-line rounded-sm p-6

`d01b9a75` — docs(claude-md): replace hex values with CSS var refs, expand route trees

Felix's concern — stale hex values in CLAUDE.md color tables:

Both CLAUDE.md and frontend/CLAUDE.md: replaced the "Brand color utilities" table (which had hardcoded hex values and a misleading Class column) with a "Brand color tokens" table using CSS variable references (--palette-navy, --palette-mint, --palette-sand). Clarified that --palette-sand is a palette constant only — not a Tailwind utility; bg-canvas / bg-surface are the correct utilities.

Felix's concern — incomplete route tree in frontend/CLAUDE.md:

Expanded the └── ... stub in the routes section of frontend/CLAUDE.md with all missing routes: geschichten/, stammbaum/, enrich/, hilfe/transkription/, profile/, users/[id]/, register/, forgot-password/, reset-password/, demo/

Missing users/[id]/ route (noted during implementation):

Added users/[id]/ (public user profile page) to both CLAUDE.md and frontend/CLAUDE.md route trees — this route existed in the codebase but was absent from all documentation.

## Review concerns addressed All open concerns from the multi-persona review have been resolved across two commits. --- ### `d69a3abc` — docs(personas): fix stale brand data in ui_expert persona **Leonie's concern — stale hex values in ui_expert.md:** - Domain Expertise section: replaced `#002850` / `#A6DAD8` / `#E4E2D7` with `--palette-navy` / `--palette-mint` / `--palette-sand`; noted that sand is a palette constant, not a Tailwind utility — use `bg-canvas` / `bg-surface` instead - Font corrected: `Merriweather` → `Tinos` in Domain Expertise section - Card pattern: `bg-white shadow-sm border border-brand-sand rounded-sm p-6` → `bg-surface shadow-sm border border-line rounded-sm p-6` - Section heading: `text-gray-400` → `text-ink-3` - CSS DO#1 example: replaced hardcoded hex values in CSS custom property examples with `var(--c-ink)` / `var(--c-accent)` / `var(--c-surface)` references - Contrast table: replaced hex values with CSS variable names; added "verify in layout.css" qualifier on the ratio values - `impl-ref` table: updated card class from `bg-white shadow-sm border border-brand-sand rounded-sm p-6` to `bg-surface shadow-sm border border-line rounded-sm p-6` --- ### `d01b9a75` — docs(claude-md): replace hex values with CSS var refs, expand route trees **Felix's concern — stale hex values in CLAUDE.md color tables:** - Both `CLAUDE.md` and `frontend/CLAUDE.md`: replaced the "Brand color utilities" table (which had hardcoded hex values and a misleading `Class` column) with a "Brand color tokens" table using CSS variable references (`--palette-navy`, `--palette-mint`, `--palette-sand`). Clarified that `--palette-sand` is a palette constant only — not a Tailwind utility; `bg-canvas` / `bg-surface` are the correct utilities. **Felix's concern — incomplete route tree in frontend/CLAUDE.md:** - Expanded the `└── ...` stub in the routes section of `frontend/CLAUDE.md` with all missing routes: `geschichten/`, `stammbaum/`, `enrich/`, `hilfe/transkription/`, `profile/`, `users/[id]/`, `register/`, `forgot-password/`, `reset-password/`, `demo/` **Missing `users/[id]/` route (noted during implementation):** - Added `users/[id]/` (public user profile page) to both `CLAUDE.md` and `frontend/CLAUDE.md` route trees — this route existed in the codebase but was absent from all documentation.

marcel commented

2026-05-06 09:14:51 +02:00

👨‍💻 Felix Brandt — Senior Fullstack Developer

Verdict: ✅ Approved

Documentation-only PR. No production code, no tests to write. Checked for correctness and consistency.

What I verified

Port fix (3000→5173): Correct — matches vite.config.ts and frontend/CLAUDE.md §How to Run.
Font name (Merriweather→Tinos): Correct — Tinos is the De Gruyter Brill CI serif substitute.
Card pattern: bg-surface shadow-sm border border-line rounded-sm p-6 matches live components like PersonCard.svelte and the document detail page.
Route tree: conversations/ correctly removed; briefwechsel/ is the real route. All added routes (geschichten/, stammbaum/, enrich/, hilfe/, profile/, users/[id]/, etc.) verified against the codebase.
Color table: CSS variable references (--palette-navy etc.) are durable and point developers to layout.css as the single source of truth. Good call.

Minor notes (non-blocking)

PR description is incomplete: It lists 6 bullet points but doesn't mention the users/[id]/ route addition, which was discovered during implementation and added to both route trees. No action required, just noting the description gap.
Test plan checkboxes unchecked: The two grep verification steps in the test plan are unchecked. For a docs-only PR this is fine, but running them before merge would be good hygiene:
```
grep -r "002850\|A6DAD8\|E4E2D7\|Merriweather\|port 3000\|conversations/\|brand-sand\|chronik/" CLAUDE.md frontend/CLAUDE.md
# should return nothing
```

No blockers. This cleans up real LLM-guidance drift that would have caused silently incorrect code generation.

## 👨‍💻 Felix Brandt — Senior Fullstack Developer **Verdict: ✅ Approved** Documentation-only PR. No production code, no tests to write. Checked for correctness and consistency. ### What I verified - **Port fix** (`3000→5173`): Correct — matches `vite.config.ts` and `frontend/CLAUDE.md §How to Run`. - **Font name** (`Merriweather→Tinos`): Correct — Tinos is the De Gruyter Brill CI serif substitute. - **Card pattern**: `bg-surface shadow-sm border border-line rounded-sm p-6` matches live components like `PersonCard.svelte` and the document detail page. - **Route tree**: `conversations/` correctly removed; `briefwechsel/` is the real route. All added routes (`geschichten/`, `stammbaum/`, `enrich/`, `hilfe/`, `profile/`, `users/[id]/`, etc.) verified against the codebase. - **Color table**: CSS variable references (`--palette-navy` etc.) are durable and point developers to `layout.css` as the single source of truth. Good call. ### Minor notes (non-blocking) 1. **PR description is incomplete**: It lists 6 bullet points but doesn't mention the `users/[id]/` route addition, which was discovered during implementation and added to both route trees. No action required, just noting the description gap. 2. **Test plan checkboxes unchecked**: The two grep verification steps in the test plan are unchecked. For a docs-only PR this is fine, but running them before merge would be good hygiene: ```bash grep -r "002850\|A6DAD8\|E4E2D7\|Merriweather\|port 3000\|conversations/\|brand-sand\|chronik/" CLAUDE.md frontend/CLAUDE.md # should return nothing ``` No blockers. This cleans up real LLM-guidance drift that would have caused silently incorrect code generation.

marcel commented

2026-05-06 09:14:58 +02:00

🏗️ Markus Keller — Application Architect

Verdict: ✅ Approved

Pure documentation. No architectural changes, no module boundary shifts, no infrastructure additions. Checked for anything that might create architectural confusion.

What I verified

Route tree accuracy: The expanded route tree now correctly reflects the feature package layout on the frontend — each route corresponds to a domain (document/, person/, geschichte/, stammbaum/, etc.). This matches the "package by feature" principle in the frontend lib/ structure.
Brand token table: Changing from hardcoded hex values to CSS variable references (--palette-navy, --palette-mint) is the right architectural move. It directs developers to layout.css as the single authoritative source, preventing divergence between what's documented and what's deployed.
--palette-sand as palette constant (not Tailwind utility): This clarification is architecturally correct. Documenting that bg-canvas / bg-surface are the correct semantic utilities prevents future developers from reaching for a non-existent bg-brand-sand class.

One observation

The api/ route in frontend/CLAUDE.md's project structure is an internal server-side proxy, not a user-facing feature — it sits in the routes tree alongside user-facing pages, which could mislead. A parenthetical "(server-side only)" note exists on it, so it's adequately qualified. No change needed.

LGTM from an architecture perspective.

## 🏗️ Markus Keller — Application Architect **Verdict: ✅ Approved** Pure documentation. No architectural changes, no module boundary shifts, no infrastructure additions. Checked for anything that might create architectural confusion. ### What I verified - **Route tree accuracy**: The expanded route tree now correctly reflects the feature package layout on the frontend — each route corresponds to a domain (`document/`, `person/`, `geschichte/`, `stammbaum/`, etc.). This matches the "package by feature" principle in the frontend `lib/` structure. - **Brand token table**: Changing from hardcoded hex values to CSS variable references (`--palette-navy`, `--palette-mint`) is the right architectural move. It directs developers to `layout.css` as the single authoritative source, preventing divergence between what's documented and what's deployed. - **`--palette-sand` as palette constant (not Tailwind utility)**: This clarification is architecturally correct. Documenting that `bg-canvas` / `bg-surface` are the correct semantic utilities prevents future developers from reaching for a non-existent `bg-brand-sand` class. ### One observation The `api/` route in `frontend/CLAUDE.md`'s project structure is an internal server-side proxy, not a user-facing feature — it sits in the routes tree alongside user-facing pages, which could mislead. A parenthetical "(server-side only)" note exists on it, so it's adequately qualified. No change needed. LGTM from an architecture perspective.

marcel commented

2026-05-06 09:15:05 +02:00

🚀 Tobias Wendt — DevOps & Platform Engineer

Verdict: ✅ Approved

No infrastructure changes, no CI workflow changes, no Compose file changes. Reviewed purely for DevOps-relevant documentation accuracy.

What I verified

Port fix (3000→5173): This is the correct Vite default port and matches the Docker Compose port mapping for the frontend service. A developer following the stale 3000 docs would have been confused why localhost:3000 shows nothing. This is a real friction fix.
No infra docs touched: docs/DEPLOYMENT.md, docker-compose.yml, .gitea/workflows/, Caddyfile — none modified. No risk of stale infra docs being introduced.

One note (informational)

The demo/ route is documented as "Dev-only demos" in the route tree — I'd verify that this route is actually guarded in the SvelteKit layout or only deployed in dev (not just by convention). If it's accessible in production with no auth guard, that's a separate issue. Out of scope for this PR but worth a follow-up ticket if it hasn't been checked.

No changes requested from my side.

## 🚀 Tobias Wendt — DevOps & Platform Engineer **Verdict: ✅ Approved** No infrastructure changes, no CI workflow changes, no Compose file changes. Reviewed purely for DevOps-relevant documentation accuracy. ### What I verified - **Port fix (3000→5173)**: This is the correct Vite default port and matches the Docker Compose port mapping for the frontend service. A developer following the stale `3000` docs would have been confused why `localhost:3000` shows nothing. This is a real friction fix. - **No infra docs touched**: `docs/DEPLOYMENT.md`, `docker-compose.yml`, `.gitea/workflows/`, Caddyfile — none modified. No risk of stale infra docs being introduced. ### One note (informational) The `demo/` route is documented as "Dev-only demos" in the route tree — I'd verify that this route is actually guarded in the SvelteKit layout or only deployed in dev (not just by convention). If it's accessible in production with no auth guard, that's a separate issue. Out of scope for this PR but worth a follow-up ticket if it hasn't been checked. No changes requested from my side.

marcel commented

2026-05-06 09:15:17 +02:00

🎨 Leonie Voss — UX Designer & Accessibility Strategist

Verdict: ✅ Approved

These are corrections to my own persona file and the CLAUDE.md brand references. I care deeply that any document an LLM reads when generating UI code gives accurate brand guidance — stale values here cause real visual bugs and dark mode failures. Overall this is a strong fix.

What changed in my persona

Correctly fixed:

Brand palette: hex values replaced with --palette-navy, --palette-mint, --palette-sand CSS variable references. The note clarifying that --palette-sand is a raw palette constant (not a Tailwind utility) and that bg-canvas/bg-surface are the correct utilities is exactly right.
Font: Merriweather → Tinos. Correct — Tinos is the Times New Roman substitute in the De Gruyter Brill CI.
Card pattern: bg-white shadow-sm border border-brand-sand → bg-surface shadow-sm border border-line. This is the semantic-token version that supports dark mode. Good.
Section title: text-gray-400 → text-ink-3. Correct semantic token.
Contrast table: hex values replaced with variable name references plus "verify in layout.css" qualifier. Good — this nudges developers to verify rather than trust a potentially stale number.
impl-ref table in the Testable Code section: card pattern updated to match. ✅

One minor concern (suggestion, not blocker):
In the DO example under "Use CSS custom properties for all brand colors", the new code shows:

/* 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);

The variables --c-ink, --c-accent, --c-surface look like internal shorthand aliases. If these don't actually exist in layout.css under those exact names, an LLM following this example would generate code referencing non-existent variables. The comment "see --palette-* for raw values" is helpful context, but the backing variable names in the example should match what's in the actual file. Consider verifying and using the real variable names (--palette-navy etc.) or marking the example as illustrative pseudocode.

This is the persona's teaching file, so inaccurate variable names in examples could mislead future code generation. Worth a follow-up correction if the names don't match layout.css.

Otherwise LGTM. These were the most impactful stale values in the codebase for UI correctness.

## 🎨 Leonie Voss — UX Designer & Accessibility Strategist **Verdict: ✅ Approved** These are corrections to my own persona file and the CLAUDE.md brand references. I care deeply that any document an LLM reads when generating UI code gives accurate brand guidance — stale values here cause real visual bugs and dark mode failures. Overall this is a strong fix. ### What changed in my persona **Correctly fixed:** - Brand palette: hex values replaced with `--palette-navy`, `--palette-mint`, `--palette-sand` CSS variable references. The note clarifying that `--palette-sand` is a raw palette constant (not a Tailwind utility) and that `bg-canvas`/`bg-surface` are the correct utilities is exactly right. - Font: `Merriweather → Tinos`. Correct — Tinos is the Times New Roman substitute in the De Gruyter Brill CI. - Card pattern: `bg-white shadow-sm border border-brand-sand → bg-surface shadow-sm border border-line`. This is the semantic-token version that supports dark mode. Good. - Section title: `text-gray-400 → text-ink-3`. Correct semantic token. - Contrast table: hex values replaced with variable name references plus "verify in layout.css" qualifier. Good — this nudges developers to verify rather than trust a potentially stale number. - `impl-ref` table in the Testable Code section: card pattern updated to match. ✅ **One minor concern (suggestion, not blocker):** In the DO example under "Use CSS custom properties for all brand colors", the new code shows: ```css /* 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); ``` The variables `--c-ink`, `--c-accent`, `--c-surface` look like internal shorthand aliases. If these don't actually exist in `layout.css` under those exact names, an LLM following this example would generate code referencing non-existent variables. The comment "see --palette-* for raw values" is helpful context, but the backing variable names in the example should match what's in the actual file. Consider verifying and using the real variable names (`--palette-navy` etc.) or marking the example as illustrative pseudocode. This is the persona's teaching file, so inaccurate variable names in examples could mislead future code generation. Worth a follow-up correction if the names don't match `layout.css`. **Otherwise LGTM.** These were the most impactful stale values in the codebase for UI correctness.

marcel commented

2026-05-06 09:15:25 +02:00

🧪 Sara Holt — QA Engineer & Test Strategist

Verdict: ✅ Approved

Documentation-only PR. No test files modified, no test infrastructure affected. Reviewed for anything that could silently impact test correctness.

What I verified

Card pattern change:
The card pattern was updated from bg-white shadow-sm border border-brand-sand to bg-surface shadow-sm border border-line. If any E2E tests use CSS class assertions on card containers (e.g., checking for bg-white), those would already be broken (the code was already changed before this PR — the documentation was stale, not the code). No test impact from this PR.

Route tree expansion:
Several previously undocumented routes are now documented: geschichten/, stammbaum/, enrich/, hilfe/transkription/, users/[id]/. If the E2E suite has coverage gaps on these routes, this PR makes them more discoverable. Not a blocker, but worth checking whether stammbaum/, enrich/, and geschichten/ have E2E critical-journey coverage — they weren't in any route tree before, which means they may have been overlooked in test planning.

Note on demo/ route:
demo/ is now explicitly documented as "Dev-only demos". If the E2E suite accidentally hits this route in a non-dev environment, it could produce false failures. Worth verifying the route is not reachable in the E2E stack configuration.

No blockers. The documentation fixes reduce guidance drift that could cause future test setup errors.

## 🧪 Sara Holt — QA Engineer & Test Strategist **Verdict: ✅ Approved** Documentation-only PR. No test files modified, no test infrastructure affected. Reviewed for anything that could silently impact test correctness. ### What I verified **Card pattern change:** The card pattern was updated from `bg-white shadow-sm border border-brand-sand` to `bg-surface shadow-sm border border-line`. If any E2E tests use CSS class assertions on card containers (e.g., checking for `bg-white`), those would already be broken (the code was already changed before this PR — the documentation was stale, not the code). No test impact from this PR. **Route tree expansion:** Several previously undocumented routes are now documented: `geschichten/`, `stammbaum/`, `enrich/`, `hilfe/transkription/`, `users/[id]/`. If the E2E suite has coverage gaps on these routes, this PR makes them more discoverable. Not a blocker, but worth checking whether `stammbaum/`, `enrich/`, and `geschichten/` have E2E critical-journey coverage — they weren't in any route tree before, which means they may have been overlooked in test planning. **Note on demo/ route:** `demo/` is now explicitly documented as "Dev-only demos". If the E2E suite accidentally hits this route in a non-dev environment, it could produce false failures. Worth verifying the route is not reachable in the E2E stack configuration. No blockers. The documentation fixes reduce guidance drift that could cause future test setup errors.

marcel commented

2026-05-06 09:15:31 +02:00

🔐 Nora "NullX" Steiner — Application Security Engineer

Verdict: ✅ Approved

Documentation-only PR. No application logic, authentication, authorization, or infrastructure configuration modified. No security-relevant surfaces changed.

What I checked

No security-sensitive content introduced:

No credentials, tokens, or secrets added to documentation.
No API routes or authentication patterns changed.
No CORS, CSRF, or session configuration modified.

Brand token documentation:
The switch from hardcoded hex values to CSS variable references (--palette-navy etc.) is a documentation improvement only — no runtime impact.

Route tree expansion:
Newly documented routes (stammbaum/, enrich/, users/[id]/, demo/) are already deployed. Worth verifying (separately from this PR) that:

users/[id]/ enforces authentication before displaying profile data — if it's a public page showing any personal data, the auth check matters.
demo/ is not reachable in production without authentication — "dev-only demos" documented but enforcement should be at the SvelteKit load function level, not just by convention.

Both are existing questions about deployed routes, not regressions introduced by this PR.

No security concerns with the changes in scope.

## 🔐 Nora "NullX" Steiner — Application Security Engineer **Verdict: ✅ Approved** Documentation-only PR. No application logic, authentication, authorization, or infrastructure configuration modified. No security-relevant surfaces changed. ### What I checked **No security-sensitive content introduced:** - No credentials, tokens, or secrets added to documentation. - No API routes or authentication patterns changed. - No CORS, CSRF, or session configuration modified. **Brand token documentation:** The switch from hardcoded hex values to CSS variable references (`--palette-navy` etc.) is a documentation improvement only — no runtime impact. **Route tree expansion:** Newly documented routes (`stammbaum/`, `enrich/`, `users/[id]/`, `demo/`) are already deployed. Worth verifying (separately from this PR) that: 1. `users/[id]/` enforces authentication before displaying profile data — if it's a public page showing any personal data, the auth check matters. 2. `demo/` is not reachable in production without authentication — "dev-only demos" documented but enforcement should be at the SvelteKit load function level, not just by convention. Both are existing questions about deployed routes, not regressions introduced by this PR. No security concerns with the changes in scope.

marcel commented

2026-05-06 09:15:41 +02:00

📋 Elicit — Requirements Engineer & Business Analyst

Verdict: ✅ Approved

Reviewing as a requirements artifact: CLAUDE.md and the persona files are LLM-guidance documents — a form of "machine-readable specification" that constrains what gets built. Their accuracy is a requirements quality concern, not just a documentation hygiene concern.

What I verified

Requirements completeness:
The route tree expansion brings the documented surface area of the application into alignment with its actual surface area. Before this PR, geschichten/, stammbaum/, enrich/, users/[id]/ were deployed features with no documentation entry — effectively invisible to any requirements or planning work done from CLAUDE.md. This is a gap closure, not just cleanup.

Traceability concern (observation, not blocker):
users/[id]/ (public user profile page) was added silently — it appears in neither the PR description nor any previously documented requirement. From a requirements perspective: what is the spec for this page? Who can see it? What data does it surface? If this route was built without a Gitea issue, that's a traceability gap worth closing retroactively. A short issue describing the page's purpose and access rules would prevent ambiguity in future work on this route.

Brand token table as a design constraint:
The revised table now correctly distinguishes brand-navy/brand-mint (Tailwind utilities — usable in markup) from --palette-sand (CSS variable — not a utility, use bg-canvas/bg-surface instead). This is exactly the kind of constraint that should be in a requirements document: it tells implementers what they may and may not do without explaining why the constraint exists. The "why" (no Tailwind utility registered for sand) could be added as a parenthetical, but it's not required.

Minor: PR description missing users/[id] addition:
The PR summary doesn't list the users/[id]/ route addition. For traceability (someone reading git history to understand when this route was first documented), a brief mention would help.

No blockers from a requirements perspective.

## 📋 Elicit — Requirements Engineer & Business Analyst **Verdict: ✅ Approved** Reviewing as a requirements artifact: CLAUDE.md and the persona files are LLM-guidance documents — a form of "machine-readable specification" that constrains what gets built. Their accuracy is a requirements quality concern, not just a documentation hygiene concern. ### What I verified **Requirements completeness:** The route tree expansion brings the documented surface area of the application into alignment with its actual surface area. Before this PR, `geschichten/`, `stammbaum/`, `enrich/`, `users/[id]/` were deployed features with no documentation entry — effectively invisible to any requirements or planning work done from CLAUDE.md. This is a gap closure, not just cleanup. **Traceability concern (observation, not blocker):** `users/[id]/` (public user profile page) was added silently — it appears in neither the PR description nor any previously documented requirement. From a requirements perspective: what is the spec for this page? Who can see it? What data does it surface? If this route was built without a Gitea issue, that's a traceability gap worth closing retroactively. A short issue describing the page's purpose and access rules would prevent ambiguity in future work on this route. **Brand token table as a design constraint:** The revised table now correctly distinguishes `brand-navy`/`brand-mint` (Tailwind utilities — usable in markup) from `--palette-sand` (CSS variable — not a utility, use `bg-canvas`/`bg-surface` instead). This is exactly the kind of constraint that should be in a requirements document: it tells implementers what they may and may not do without explaining why the constraint exists. The "why" (no Tailwind utility registered for sand) could be added as a parenthetical, but it's not required. **Minor: PR description missing `users/[id]` addition:** The PR summary doesn't list the `users/[id]/` route addition. For traceability (someone reading git history to understand when this route was first documented), a brief mention would help. No blockers from a requirements perspective.

marcel merged commit d01b9a7508 into main

2026-05-06 09:18:08 +02:00

marcel deleted branch docs/post-refactor-accuracy-audit

2026-05-06 09:18:08 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#446

docs: fix stale CLAUDE.md content after design-system refactoring #446

Summary

Test plan

👨‍💻 Felix Brandt — Senior Fullstack Developer

Blocker

Suggestions

🏗️ Markus Keller — Senior Application Architect

What's correct

Minor observation

🖥️ Tobias Wendt — DevOps & Platform Engineer

What's correct

Observation (not a blocker)

🔒 Nora "NullX" Steiner — Application Security Engineer

What I checked

Clean

🧪 Sara Holt — QA Engineer & Test Strategist

What I checked

Suggestion

🎨 Leonie Voss — UX Designer & Brand Specialist

Blocker: ui_expert.md persona file has stale brand data

Also: brand-sand column label ambiguity

Minor

📋 Elicit — Requirements Engineer & Documentation Analyst

Concerns

What's good

Review concerns addressed

d69a3abc — docs(personas): fix stale brand data in ui_expert persona

d01b9a75 — docs(claude-md): replace hex values with CSS var refs, expand route trees

👨‍💻 Felix Brandt — Senior Fullstack Developer

What I verified

Minor notes (non-blocking)

🏗️ Markus Keller — Application Architect

What I verified

One observation

🚀 Tobias Wendt — DevOps & Platform Engineer

What I verified

One note (informational)

🎨 Leonie Voss — UX Designer & Accessibility Strategist

What changed in my persona

🧪 Sara Holt — QA Engineer & Test Strategist

What I verified

🔐 Nora "NullX" Steiner — Application Security Engineer

What I checked

📋 Elicit — Requirements Engineer & Business Analyst

What I verified

Blocker: `ui_expert.md` persona file has stale brand data

Also: `brand-sand` column label ambiguity

`d69a3abc` — docs(personas): fix stale brand data in ui_expert persona

`d01b9a75` — docs(claude-md): replace hex values with CSS var refs, expand route trees