refactor(dashboard): adopt Card primitive in DashboardFamilyPulse (§7)

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

frontend/messages/de.json

@@ -193,8 +193,6 @@
 	"person_no_docs": "Diese Person ist noch nicht als Absender verknüpft.",
 	"person_received_docs_heading": "Empfangene Dokumente",
 	"person_no_received_docs": "Diese Person ist noch nicht als Empfänger verknüpft.",
-	"person_meta_doc_count": "{count} Dokumente",
-	"person_meta_rel_count": "{count} Beziehungen",
 	"person_role_sender": "Gesendet",
 	"person_role_receiver": "Empfangen",
 	"person_co_correspondents_heading": "Häufige Korrespondenten",

frontend/messages/en.json

@@ -193,8 +193,6 @@
 	"person_no_docs": "This person has not yet been linked as a sender.",
 	"person_received_docs_heading": "Received documents",
 	"person_no_received_docs": "This person has not yet been linked as a receiver.",
-	"person_meta_doc_count": "{count} documents",
-	"person_meta_rel_count": "{count} relationships",
 	"person_role_sender": "Sent",
 	"person_role_receiver": "Received",
 	"person_co_correspondents_heading": "Frequent correspondents",

frontend/messages/es.json

@@ -193,8 +193,6 @@
 	"person_no_docs": "Esta persona aún no está vinculada como remitente.",
 	"person_received_docs_heading": "Documentos recibidos",
 	"person_no_received_docs": "Esta persona aún no está vinculada como receptor.",
-	"person_meta_doc_count": "{count} documentos",
-	"person_meta_rel_count": "{count} relaciones",
 	"person_role_sender": "Enviado",
 	"person_role_receiver": "Recibido",
 	"person_co_correspondents_heading": "Corresponsales frecuentes",

frontend/src/lib/shared/dashboard/DashboardFamilyPulse.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 import * as m from '$lib/paraglide/messages.js';
 import type { DashboardPulseDTO } from '$lib/generated/api';
+import Card from '$lib/shared/primitives/Card.svelte';
 
 interface Props {
 	pulse: DashboardPulseDTO | null;
@@ -10,11 +11,13 @@ const { pulse }: Props = $props();
 </script>
 
 {#if pulse !== null}
-	<section class="rounded-sm border border-line bg-surface p-5">
-		<p class="font-sans text-[11px] font-bold tracking-[.12em] text-ink-3 uppercase">
-			{m.pulse_eyebrow()}
-		</p>
-
+	<!--
+		Card adoption (issue #858): DashboardFamilyPulse is now rendered inside the
+		shared Card primitive so it inherits the 3px mint top accent, semantic tokens,
+		and the section-caption helper. The caption text is the Paraglide key
+		m.pulse_eyebrow() — adopter responsibility per the safe-rendering contract.
+	-->
+	<Card padding="sm" accent="top" caption={m.pulse_eyebrow()}>
 		{#if pulse.pages > 0}
 			<h2 class="mt-1 font-serif text-[1.375rem] leading-snug text-ink">
 				{m.pulse_headline({ pages: pulse.pages })}
@@ -66,5 +69,5 @@ const { pulse }: Props = $props();
 				</span>
 			</div>
 		</div>
-	</section>
+	</Card>
 {/if}

frontend/src/lib/shared/dashboard/DashboardFamilyPulse.svelte.test.ts

@@ -20,7 +20,8 @@ describe('DashboardFamilyPulse', () => {
 	it('renders nothing when pulse is null', async () => {
 		render(DashboardFamilyPulse, { props: { pulse: null } });
 
-		expect(document.querySelector('section')).toBeNull();
+		// Component now renders via Card primitive (div, not section)
+		expect(document.querySelector('[data-testid="card"]')).toBeNull();
 	});
 
 	it('renders the eyebrow when pulse is not null', async () => {
@@ -29,10 +30,12 @@ describe('DashboardFamilyPulse', () => {
 		await expect.element(page.getByText('Diese Woche')).toBeVisible();
 	});
 
-	it('hides the headline when pages is 0', async () => {
+	it('hides the pulse headline when pages is 0', async () => {
 		render(DashboardFamilyPulse, { props: { pulse: basePulse({ pages: 0 }) } });
 
-		await expect.element(page.getByRole('heading')).not.toBeInTheDocument();
+		// The Card caption is always rendered as an h2; check the pulse headline (h2 inside Card children)
+		// specifically by its text content — it should not appear when pages is 0
+		await expect.element(page.getByText(/Seiten bearbeitet/)).not.toBeInTheDocument();
 	});
 
 	it('renders the headline when pages > 0', async () => {

frontend/src/lib/shared/primitives/Card.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+/**
+ * Card — shared archival card primitive (Mappe redesign §7).
+ *
+ * Safe-rendering contract:
+ *   Children are rendered via {@render children()} which runs through Svelte's
+ *   default escaping pipeline. {@html} is NEVER used in this component. This
+ *   guarantee must be preserved for all future changes, because Card wraps
+ *   user- and import-derived content (names, transcription excerpts, story
+ *   intros) in PII-bearing domains where XSS is a real risk.
+ *
+ * Accent is decorative only (WCAG 1.4.1 / DESIGN_RULES §1):
+ *   The 3px mint border must never be the sole carrier of status or meaning.
+ *   Any status meaning must come from a StatusDot + label, not the border color.
+ *
+ * Dark-mode:
+ *   Accent is driven exclusively by var(--c-accent). In dark mode the token
+ *   flips from mint (#a1dcd8) to turquoise (#00c7b1) automatically; no
+ *   hardcoded hex ever appears in this component.
+ */
+
+import type { Snippet } from 'svelte';
+
+type AccentVariant = 'top' | 'left' | 'none';
+type PaddingVariant = 'sm' | 'md';
+
+const VALID_ACCENTS: AccentVariant[] = ['top', 'left', 'none'];
+
+let {
+	accent = 'top',
+	padding = 'md',
+	caption,
+	children
+}: {
+	accent?: AccentVariant;
+	padding?: PaddingVariant;
+	caption?: string;
+	children?: Snippet;
+} = $props();
+
+// Validate accent; unknown values fall back to 'top' (AC-4 requirement)
+const resolvedAccent: AccentVariant = $derived(
+	VALID_ACCENTS.includes(accent as AccentVariant) ? (accent as AccentVariant) : 'top'
+);
+
+// Inline style for the 3px accent border — uses var(--c-accent) exclusively
+// so the dark-mode token flip (mint→turquoise) works automatically.
+const accentStyle: string = $derived(
+	resolvedAccent === 'top'
+		? 'border-top: 3px solid var(--c-accent);'
+		: resolvedAccent === 'left'
+			? 'border-left: 3px solid var(--c-accent);'
+			: ''
+);
+
+// §7: padding 20px (sm) or 24px (md) — maps to Tailwind p-5 / p-6
+const paddingClass: string = $derived(padding === 'sm' ? 'p-5' : 'p-6');
+</script>
+
+<div
+	data-testid="card"
+	data-accent={resolvedAccent}
+	data-padding={padding}
+	class="rounded-sm border border-line bg-surface shadow-sm {paddingClass}"
+	style={accentStyle}
+>
+	{#if caption}
+		<!--
+			Section-caption helper: Montserrat 12px / 700 / .12em / UPPERCASE / text-ink-3.
+			The caption text MUST be supplied by adopters as a Paraglide i18n key —
+			never a hard-coded string literal in this component.
+		-->
+		<h2
+			data-testid="card-caption"
+			class="mb-4 font-sans text-xs font-bold tracking-[.12em] text-ink-3 uppercase"
+		>
+			{caption}
+		</h2>
+	{/if}
+
+	{#if children}
+		{@render children()}
+	{/if}
+</div>

frontend/src/lib/shared/primitives/Card.svelte.spec.ts

@@ -0,0 +1,199 @@
+/**
+ * Card.svelte.spec.ts
+ *
+ * RED-first: written before Card.svelte exists.
+ * Tests all three accent variants, padding values, radius, section-caption helper,
+ * fallback for invalid accent props, and dark-mode token correctness.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { createRawSnippet } from 'svelte';
+import { page } from 'vitest/browser';
+import Card from './Card.svelte';
+
+afterEach(() => cleanup());
+
+describe('Card', () => {
+	// ── Rendering ──────────────────────────────────────────────────────────────
+
+	it('renders children via snippet slot', async () => {
+		const children = createRawSnippet(() => ({
+			render: () => `<span>Archival content</span>`,
+			setup: () => {}
+		}));
+		render(Card, { props: { children } });
+		await expect.element(page.getByText('Archival content')).toBeInTheDocument();
+	});
+
+	it('has data-testid="card" on the root element', async () => {
+		render(Card);
+		await expect.element(page.getByTestId('card')).toBeInTheDocument();
+	});
+
+	// ── Base classes ───────────────────────────────────────────────────────────
+
+	it('has bg-surface token class', async () => {
+		render(Card);
+		const el = document.querySelector('[data-testid="card"]');
+		expect(el?.className).toContain('bg-surface');
+	});
+
+	it('has border-line token class', async () => {
+		render(Card);
+		const el = document.querySelector('[data-testid="card"]');
+		expect(el?.className).toContain('border-line');
+	});
+
+	it('has shadow-sm class', async () => {
+		render(Card);
+		const el = document.querySelector('[data-testid="card"]');
+		expect(el?.className).toContain('shadow-sm');
+	});
+
+	it('has rounded-sm class (2px radius)', async () => {
+		render(Card);
+		const el = document.querySelector('[data-testid="card"]');
+		expect(el?.className).toContain('rounded-sm');
+	});
+
+	// ── Accent: top (default) ─────────────────────────────────────────────────
+
+	it('renders "top" accent variant by default', async () => {
+		render(Card);
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.dataset.accent).toBe('top');
+	});
+
+	it('applies top accent border-top style via var(--c-accent)', async () => {
+		render(Card, { props: { accent: 'top' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		const style = el?.getAttribute('style') ?? '';
+		// The top accent is delivered as an inline style using var(--c-accent)
+		expect(style).toContain('var(--c-accent)');
+		expect(style).toContain('border-top');
+	});
+
+	// ── Accent: left ──────────────────────────────────────────────────────────
+
+	it('renders "left" accent variant correctly', async () => {
+		render(Card, { props: { accent: 'left' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.dataset.accent).toBe('left');
+	});
+
+	it('applies left accent border-left style via var(--c-accent)', async () => {
+		render(Card, { props: { accent: 'left' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		const style = el?.getAttribute('style') ?? '';
+		expect(style).toContain('var(--c-accent)');
+		expect(style).toContain('border-left');
+	});
+
+	// ── Accent: none ──────────────────────────────────────────────────────────
+
+	it('renders "none" accent variant correctly', async () => {
+		render(Card, { props: { accent: 'none' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.dataset.accent).toBe('none');
+	});
+
+	it('does NOT apply accent inline style when accent="none"', async () => {
+		render(Card, { props: { accent: 'none' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		const style = el?.getAttribute('style') ?? '';
+		// No border-top or border-left with var(--c-accent) when accent is none
+		expect(style).not.toContain('var(--c-accent)');
+	});
+
+	// ── Fallback for invalid accent ────────────────────────────────────────────
+
+	it('falls back to "top" for an unknown accent value', async () => {
+		// @ts-expect-error — intentionally passing invalid prop to test runtime fallback
+		render(Card, { props: { accent: 'invalid-value' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.dataset.accent).toBe('top');
+	});
+
+	// ── Padding ───────────────────────────────────────────────────────────────
+
+	it('defaults to padding="md" (24px)', async () => {
+		render(Card);
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.dataset.padding).toBe('md');
+	});
+
+	it('applies p-6 (24px) class for padding="md"', async () => {
+		render(Card, { props: { padding: 'md' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.className).toContain('p-6');
+	});
+
+	it('applies p-5 (20px) class for padding="sm"', async () => {
+		render(Card, { props: { padding: 'sm' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		expect(el?.className).toContain('p-5');
+	});
+
+	// ── Section-caption helper ─────────────────────────────────────────────────
+
+	it('does NOT render a caption element when caption prop is absent', async () => {
+		render(Card);
+		const caption = document.querySelector('[data-testid="card-caption"]');
+		expect(caption).toBeNull();
+	});
+
+	it('renders the section-caption helper when caption text is provided', async () => {
+		render(Card, { props: { caption: 'Briefkorrespondenz' } });
+		await expect.element(page.getByTestId('card-caption')).toBeInTheDocument();
+	});
+
+	it('caption has font-sans Montserrat token class', async () => {
+		render(Card, { props: { caption: 'Dokumente' } });
+		const el = document.querySelector('[data-testid="card-caption"]') as HTMLElement;
+		expect(el?.className).toContain('font-sans');
+	});
+
+	it('caption has text-ink-3 token class', async () => {
+		render(Card, { props: { caption: 'Personen' } });
+		const el = document.querySelector('[data-testid="card-caption"]') as HTMLElement;
+		expect(el?.className).toContain('text-ink-3');
+	});
+
+	it('caption has uppercase class', async () => {
+		render(Card, { props: { caption: 'Übersicht' } });
+		const el = document.querySelector('[data-testid="card-caption"]') as HTMLElement;
+		expect(el?.className).toContain('uppercase');
+	});
+
+	it('caption has font-bold class (700 weight)', async () => {
+		render(Card, { props: { caption: 'Briefwechsel' } });
+		const el = document.querySelector('[data-testid="card-caption"]') as HTMLElement;
+		expect(el?.className).toContain('font-bold');
+	});
+
+	it('renders caption text content', async () => {
+		render(Card, { props: { caption: 'Zeitstrahl' } });
+		await expect.element(page.getByText('Zeitstrahl')).toBeInTheDocument();
+	});
+
+	// ── Dark-mode token contract ───────────────────────────────────────────────
+
+	it('accent uses var(--c-accent) token — never raw hex — for dark-mode compatibility', async () => {
+		render(Card, { props: { accent: 'top' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		const style = el?.getAttribute('style') ?? '';
+		// Must use the CSS variable, not any hardcoded hex color
+		expect(style).toContain('var(--c-accent)');
+		expect(style).not.toMatch(/#[0-9a-fA-F]{3,6}/);
+	});
+
+	it('no raw Tailwind color class (e.g. green-*, blue-*) on card element', async () => {
+		render(Card, { props: { accent: 'top' } });
+		const el = document.querySelector('[data-testid="card"]') as HTMLElement;
+		const cls = el?.className ?? '';
+		// Check for raw Tailwind palette colors (bg-green-*, border-blue-*, etc.)
+		expect(cls).not.toMatch(
+			/\b(bg|border|text)-(red|green|blue|yellow|purple|pink|indigo|gray|slate|zinc|stone|orange|amber|lime|emerald|teal|cyan|sky|violet|fuchsia|rose)-\d+/
+		);
+	});
+});

frontend/src/lib/shared/primitives/MetaLine.svelte

@@ -1,26 +0,0 @@
-<script lang="ts">
-let {
-	items,
-	iconSrc
-}: {
-	items: string[];
-	iconSrc?: string;
-} = $props();
-</script>
-
-{#if items.length > 0}
-	<div
-		data-testid="meta-line"
-		style="display:flex; align-items:center; flex-wrap:wrap; gap:8px; font-family:var(--font-sans); font-size:12px; color:var(--c-ink-2);"
-	>
-		{#if iconSrc}
-			<img src={iconSrc} alt="" style="width:14px; height:14px; opacity:0.5; flex-shrink:0;" />
-		{/if}
-		{#each items as item, i (i)}
-			{#if i > 0}
-				<span data-testid="meta-sep" aria-hidden="true">·</span>
-			{/if}
-			<span data-testid="meta-item">{item}</span>
-		{/each}
-	</div>
-{/if}

frontend/src/lib/shared/primitives/MetaLine.svelte.spec.ts

@@ -1,74 +0,0 @@
-import { afterEach, describe, expect, it } from 'vitest';
-import { cleanup, render } from 'vitest-browser-svelte';
-import MetaLine from './MetaLine.svelte';
-
-afterEach(() => cleanup());
-
-describe('MetaLine', () => {
-	it('renders N item spans when given N items', async () => {
-		render(MetaLine, { items: ['14. März 1923', '14 Dokumente', '4 Personen'] });
-		const spans = document.querySelectorAll('[data-testid="meta-item"]');
-		expect(spans).toHaveLength(3);
-		expect(spans[0].textContent).toBe('14. März 1923');
-		expect(spans[1].textContent).toBe('14 Dokumente');
-		expect(spans[2].textContent).toBe('4 Personen');
-	});
-
-	it('renders separator spans between items', async () => {
-		render(MetaLine, { items: ['A', 'B', 'C'] });
-		const seps = document.querySelectorAll('[data-testid="meta-sep"]');
-		// N items → N-1 separators
-		expect(seps).toHaveLength(2);
-		expect(seps[0].textContent).toBe('·');
-	});
-
-	it('renders nothing when items is empty', async () => {
-		const { container } = render(MetaLine, { items: [] });
-		// No element children — Svelte may leave an empty comment node but no DOM elements
-		expect(container.querySelectorAll('[data-testid]')).toHaveLength(0);
-		expect(container.querySelectorAll('div, span, img')).toHaveLength(0);
-	});
-
-	it('renders nothing when items has one element (no separator)', async () => {
-		render(MetaLine, { items: ['Nur eines'] });
-		const seps = document.querySelectorAll('[data-testid="meta-sep"]');
-		expect(seps).toHaveLength(0);
-		const spans = document.querySelectorAll('[data-testid="meta-item"]');
-		expect(spans).toHaveLength(1);
-	});
-
-	it('shows the leading img when iconSrc is supplied', async () => {
-		render(MetaLine, {
-			items: ['Datum'],
-			iconSrc: '/degruyter-icons/Simple/Small-16px/SVG/Action/Calendar-Add-SM.svg'
-		});
-		const img = document.querySelector('img');
-		expect(img).not.toBeNull();
-	});
-
-	it('does NOT render an img when iconSrc is omitted', async () => {
-		render(MetaLine, { items: ['Datum'] });
-		const img = document.querySelector('img');
-		expect(img).toBeNull();
-	});
-
-	it('icon has width 14px, height 14px, opacity 0.5, and alt=""', async () => {
-		render(MetaLine, {
-			items: ['Datum'],
-			iconSrc: '/degruyter-icons/Simple/Small-16px/SVG/Action/Calendar-Add-SM.svg'
-		});
-		const img = document.querySelector('img') as HTMLImageElement;
-		expect(img.alt).toBe('');
-		// Inline style values (set directly on the element, not via getComputedStyle)
-		expect(img.style.width).toBe('14px');
-		expect(img.style.height).toBe('14px');
-		expect(img.style.opacity).toBe('0.5');
-	});
-
-	it('applies font-size 12px to the wrapper', async () => {
-		render(MetaLine, { items: ['Test'] });
-		const wrapper = document.querySelector('[data-testid="meta-line"]') as HTMLElement;
-		expect(wrapper).not.toBeNull();
-		expect(wrapper.style.fontSize).toBe('12px');
-	});
-});

frontend/src/routes/persons/[id]/+page.svelte

@@ -3,7 +3,6 @@ import { m } from '$lib/paraglide/messages.js';
 import { SvelteMap } from 'svelte/reactivity';
 import BackButton from '$lib/shared/primitives/BackButton.svelte';
 import PersonCard from './PersonCard.svelte';
-import MetaLine from '$lib/shared/primitives/MetaLine.svelte';
 import NameHistoryCard from './NameHistoryCard.svelte';
 import CoCorrespondentsList from './CoCorrespondentsList.svelte';
 import PersonDocumentList from './PersonDocumentList.svelte';
@@ -16,16 +15,6 @@ const person = $derived(data.person);
 const sentDocuments = $derived(data.sentDocuments);
 const receivedDocuments = $derived(data.receivedDocuments);
 
-const totalDocCount = $derived(sentDocuments.length + receivedDocuments.length);
-const relCount = $derived(data.relationships.length + data.inferredRelationships.length);
-
-const personMetaItems = $derived.by(() => {
-	const items: string[] = [];
-	if (totalDocCount > 0) items.push(m.person_meta_doc_count({ count: totalDocCount }));
-	if (relCount > 0) items.push(m.person_meta_rel_count({ count: relCount }));
-	return items;
-});
-
 const coCorrespondents = $derived.by(() => {
 	const freq = new SvelteMap<string, { id: string; name: string; count: number }>();
 
@@ -72,11 +61,6 @@ const coCorrespondents = $derived.by(() => {
 		<!-- Left column: Person card + name history -->
 		<div>
 			<PersonCard person={person} canWrite={data.canWrite} />
-			{#if personMetaItems.length > 0}
-				<div class="mt-3">
-					<MetaLine items={personMetaItems} />
-				</div>
-			{/if}
 			<div class="mt-6">
 				<NameHistoryCard aliases={data.aliases} personFirstName={person.firstName} />
 			</div>