marcel/familienarchiv
1
0
Fork 0
Code Issues 107 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Merged
marcel merged 3 commits from docs/post-refactor-accuracy-audit into main 2026-05-06 09:18:08 +02:00
Conversation 15 Commits 3 Files Changed 3 +64 -49
3 changed files with 64 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.claude/personas/ui_expert.md
View File

@@ -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** 2. **Use CSS custom properties for all brand colors**
```css ```css
/* layout.css */ /* layout.css — semantic tokens backed by CSS variables (see --palette-* for raw values) */
--color-ink: #002850; --color-ink: var(--c-ink);
--color-accent: #A6DAD8; --color-accent: var(--c-accent);
--color-surface: #E4E2D7; --color-surface: var(--c-surface);
``` ```
```svelte ```svelte
<div class="text-ink bg-surface border-line"> <div class="text-ink bg-surface border-line">
@@ -103,9 +103,9 @@ unsaved work without warning.
1. **Enforce WCAG AA contrast ratios** 1. **Enforce WCAG AA contrast ratios**
``` ```
brand-navy (#002850) on white: 14.5:1 -- AAA pass brand-navy (--palette-navy) on white: ~14.5:1 -- AAA pass (verify exact value in layout.css)
brand-mint (#A6DAD8) on navy: 7.2:1 -- AAA pass for large text 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 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. 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 */ /* Silver #CACAC9 on white = 1.5:1 -- fails all WCAG levels */
.caption { color: #CACAC9; } .caption { color: #CACAC9; }
/* brand-mint on white = 2.8:1 -- fails AA for normal text */ /* brand-mint on white = ~2.8:1 -- fails AA for normal text */
.label { color: #A6DAD8; } .label { color: var(--palette-mint); }
``` ```
Test every text color against its background. Decorative palette colors are for borders and backgrounds, not text. 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
<table> <table>
<tr><td>Section title</td><td><code>text-xs font-bold uppercase tracking-widest</code></td> <tr><td>Section title</td><td><code>text-xs font-bold uppercase tracking-widest</code></td>
<td>12px / 700</td><td>Most commonly undersized</td></tr> <td>12px / 700</td><td>Most commonly undersized</td></tr>
<tr><td>Card container</td><td><code>bg-white shadow-sm border border-brand-sand rounded-sm p-6</code></td> <tr><td>Card container</td><td><code>bg-surface shadow-sm border border-line rounded-sm p-6</code></td>
<td>padding 24px</td><td>—</td></tr> <td>padding 24px</td><td>—</td></tr>
</table> </table>
</div> </div>
@@ -376,10 +376,10 @@ await page.setViewportSize({ width: 1440, height: 900 });
## Domain Expertise ## Domain Expertise
### Brand Palette ### Brand Palette
- **Primary**: brand-navy `#002850` (text, buttons, headers), brand-mint `#A6DAD8` (accents, hover), brand-sand `#E4E2D7` (backgrounds, borders) - **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` (Merriweather) for body/titles, `font-sans` (Montserrat) for labels/UI chrome - **Typography**: `font-serif` (Tinos) for body/titles, `font-sans` (Montserrat) for labels/UI chrome
- **Card pattern**: `bg-white shadow-sm border border-brand-sand rounded-sm p-6` - **Card pattern**: `bg-surface shadow-sm border border-line rounded-sm p-6`
- **Section title**: `text-xs font-bold uppercase tracking-widest text-gray-400 mb-5` - **Section title**: `text-xs font-bold uppercase tracking-widest text-ink-3 mb-5`
### Dual-Audience Design (25-42 AND 60+) ### 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 - Seniors: 16px minimum body text (prefer 18px), 44px touch targets (prefer 48px), redundant cues, calm layouts, persistent navigation, no timed interactions

52
CLAUDE.md
View File

@@ -54,7 +54,7 @@ cd backend
cd frontend cd frontend
npm install npm install
npm run dev # Dev server (port 3000) npm run dev # Dev server (port 5173)
npm run build # Production build npm run build # Production build
npm run preview # Preview production build npm run preview # Preview production build
@@ -181,21 +181,29 @@ Input DTOs live flat in the domain package. Response types are the model entitie
``` ```
frontend/src/routes/ frontend/src/routes/
├── +layout.svelte Global header (sticky), nav links, logout ├── +layout.svelte / +layout.server.ts Global layout, auth cookie
├── +layout.server.ts Loads current user, injects auth cookie ├── +page.svelte / +page.server.ts Home / document search dashboard
├── +page.svelte Home / document search
├── +page.server.ts Load: search documents; no actions
├── documents/ ├── documents/
│ ├── [id]/+page.svelte Document detail (view + file preview) │ ├── [id]/ Document detail (view + file preview)
│ └── [id]/edit/ Edit form (all metadata + file upload) │ ├── [id]/edit/ Edit form (all metadata + file upload)
│ └── new/ Create form (same fields, empty) │ ├── new/ Upload form
│ └── bulk-edit/ Multi-document edit
├── persons/ ├── persons/
│ ├── +page.svelte Person list with search │ ├── [id]/ Person detail
│ ├── [id]/+page.svelte Person detail (inline edit + merge) │ ├── [id]/edit/ Person edit form
│ └── new/ Create person form │ └── new/ Create person form
├── conversations/ Bilateral conversation timeline ├── briefwechsel/ Bilateral conversation timeline (Briefwechsel)
├── admin/ User + group + tag management ├── aktivitaeten/ Unified activity feed (Chronik)
└── login/ logout/ Auth pages ├── 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
├── users/[id]/ Public user profile page
├── login/ logout/ register/
├── forgot-password/ reset-password/
└── demo/ Dev-only demos
``` ```
### API Client Pattern ### API Client Pattern
@@ -231,24 +239,24 @@ export const actions = {
### Styling Conventions (Tailwind CSS 4) ### Styling Conventions (Tailwind CSS 4)
Brand color utilities (defined in `layout.css`): Brand color tokens (defined in `layout.css`):
| Class | Value | Usage | | Token / Utility | CSS variable | Usage |
| ------------ | --------- | -------------------------------- | | ---------------- | ---------------- | ------------------------------------------------------- |
| `brand-navy` | `#002850` | Primary text, buttons, headers | | `brand-navy` | `--palette-navy` | Tailwind utility — buttons, headers, primary text |
| `brand-mint` | `#A6DAD8` | Accents, hover underlines, icons | | `brand-mint` | `--palette-mint` | Tailwind utility — accents, hover underlines, icons |
| `brand-sand` | `#E4E2D7` | Page background, card borders | | `--palette-sand` | `--palette-sand` | Palette constant only — use `bg-canvas` or `bg-surface` |
Typography: Typography:
- `font-serif` (Merriweather) — body text, document titles, names - `font-serif` (Tinos) — body text, document titles, names
- `font-sans` (Montserrat) — labels, metadata, UI chrome - `font-sans` (Montserrat) — labels, metadata, UI chrome
Card pattern for content sections: Card pattern for content sections:
```svelte ```svelte
<div class="bg-white shadow-sm border border-brand-sand rounded-sm p-6"> <div class="rounded-sm border border-line bg-surface shadow-sm p-6">
<h2 class="text-xs font-bold uppercase tracking-widest text-gray-400 mb-5">Section Title</h2> <h2 class="text-xs font-bold uppercase tracking-widest text-ink-3 mb-5">Section Title</h2>
<!-- content --> <!-- content -->
</div> </div>
``` ```

33
frontend/CLAUDE.md
View File

@@ -30,11 +30,18 @@ src/
│ ├── documents/ # Document CRUD, detail, edit, upload │ ├── documents/ # Document CRUD, detail, edit, upload
│ ├── persons/ # Person directory, detail, edit, merge │ ├── persons/ # Person directory, detail, edit, merge
│ ├── briefwechsel/ # Bilateral conversation timeline │ ├── briefwechsel/ # Bilateral conversation timeline
│ ├── chronik/ # Unified activity feed │ ├── aktivitaeten/ # Unified activity feed (Chronik)
│ ├── admin/ # User, group, tag, OCR, system management │ ├── admin/ # User, group, tag, OCR, system management
│ ├── api/ # Internal API proxies (server-side only) │ ├── 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) ├── lib/ # Domain-based package structure (mirrors backend)
│ ├── document/ # Document domain: components, stores, services, utils │ ├── document/ # Document domain: components, stores, services, utils
│ │ ├── annotation/ # Annotation overlay components │ │ ├── annotation/ # Annotation overlay components
@@ -102,24 +109,24 @@ export const actions = {
## Styling Conventions (Tailwind CSS 4) ## Styling Conventions (Tailwind CSS 4)
Brand color utilities (defined in `layout.css`): Brand color tokens (defined in `layout.css`):
| Class | Value | Usage | | Token / Utility | CSS variable | Usage |
| ------------ | --------- | -------------------------------- | | ---------------- | ---------------- | ------------------------------------------------------- |
| `brand-navy` | `#002850` | Primary text, buttons, headers | | `brand-navy` | `--palette-navy` | Tailwind utility — buttons, headers, primary text |
| `brand-mint` | `#A6DAD8` | Accents, hover underlines, icons | | `brand-mint` | `--palette-mint` | Tailwind utility — accents, hover underlines, icons |
| `brand-sand` | `#E4E2D7` | Page background, card borders | | `--palette-sand` | `--palette-sand` | Palette constant only — use `bg-canvas` or `bg-surface` |
Typography: Typography:
- `font-serif` (Merriweather) — body text, document titles, names - `font-serif` (Tinos) — body text, document titles, names
- `font-sans` (Montserrat) — labels, metadata, UI chrome - `font-sans` (Montserrat) — labels, metadata, UI chrome
Card pattern for content sections: Card pattern for content sections:
```svelte ```svelte
<div class="bg-white shadow-sm border border-brand-sand rounded-sm p-6"> <div class="rounded-sm border border-line bg-surface shadow-sm p-6">
<h2 class="text-xs font-bold uppercase tracking-widest text-gray-400 mb-5">Section</h2> <h2 class="text-xs font-bold uppercase tracking-widest text-ink-3 mb-5">Section</h2>
<!-- content --> <!-- content -->
</div> </div>
``` ```
@@ -137,7 +144,7 @@ Card pattern for content sections:
```bash ```bash
cd frontend cd frontend
npm install 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 ### Build & Preview