2026-04-25 — DesignGUIDE/ retirement: 89% lineage coverage by docs/design/, 3 brand-asset gaps deferred

Retired the DesignGUIDE/ tree (9 files, 67 KB lineage source + 8 process/HTML artifacts). Audit confirmed 32 of 36 brief-v3 sections fully covered by the existing 15 design mdx pages. Three substantive gaps (favicons §6.3, OG-images §6.4, community avatars §6.5) deferred to a follow-up since they require asset-spec writing, not migration of existing content. Brief-v3 + DESIGN-GUIDE_v0.2 preserved out-of-tree at ~/.claude/files by dave/fragJulia/ for the follow-up's reference.

What changed

The legacy DesignGUIDE/ tree at the repo root has been deleted in its entirety. It held one canonical lineage document (fragjulia-design-brief-v3.md, 67 KB, 1,339 lines) plus 8 process and HTML artifacts that were never the live source of truth. The 15 design mdx pages under apps/docs/content/docs/design/ plus the live tokens at packages/ui/src/styles/tokens.css are the sole source of truth going forward.

Files deleted (9)

File	Bytes	Why deleted
`DesignGUIDE/fragjulia-design-brief-v3.md`	~67 KB	Lineage source — content covered by 15 mdx pages (89% coverage)
`DesignGUIDE/DESIGN-GUIDE_v0.2.md`	—	Older brief draft, superseded by v3 then by mdx tree
`DesignGUIDE/DESIGN-SYSTEM-AUDIT.md`	—	Internal process artifact, work product completed
`DesignGUIDE/docs-design-integration-proposals.md`	—	Pre-migration planning doc, decisions long since shipped
`DesignGUIDE/fragjulia-redesign-v3.html`	—	HTML mockup, superseded by live `apps/web/app/`
`DesignGUIDE/fragjulia-illustrations-v3.html`	—	HTML mockup, superseded by `packages/ui/src/illustrations/`
`DesignGUIDE/og-home-preview.html`	—	OG preview prototype, never used in production
`DesignGUIDE/og-all-variants.html`	—	OG preview prototype, never used in production
`DesignGUIDE/logodesign_draft`	1 byte	Empty placeholder file

Preservation

DesignGUIDE/fragjulia-design-brief-v3.md and DesignGUIDE/DESIGN-GUIDE_v0.2.md were preserved out-of-tree at ~/.claude/files by dave/fragJulia/ before deletion. They remain accessible to the follow-up issue that fills the three brand-asset gaps below — those gaps reference brief-v3 sections (§6.3, §6.4, §6.5) and the preserved copy is the canonical reference for that work.

Coverage audit

A side-by-side audit walked all 36 sections of brief-v3 against the 15 design mdx pages. Findings: 32 of 36 sections (89%) are fully covered. The three substantive gaps and one partial overlap are deferred as a follow-up:

§6.3 Favicons — favicon spec (sizes, mask-icon, theme-color, dark-mode treatment) not yet documented in the mdx tree.
§6.4 OG images — share-card spec (template, typography, aspect ratios, per-page variants) not yet documented.
§6.5 Community avatars — anonymous avatar generation spec (deterministic seed → palette + shape + accent) not yet documented.

These three are asset-design specifications, not migrations of already-written content; closing them requires writing new asset specs that didn't exist in brief-v3 (favicons/OG were partial; avatars were a sketch). They are tracked separately so this PR closes #646 cleanly without expanding scope into asset design.

Code/docs comment rewrites

In-repo references that previously named DesignGUIDE/fragjulia-design-brief-v3.md as the source of truth or as a reference were rewritten to point at the live SoT:

packages/ui/src/styles/tokens.css — header comment now points at apps/docs/content/docs/design/*.mdx + this file as live SoT.
packages/ui/src/tokens.ts — header comment updated to reference the mdx tree + live tokens.
apps/docs/app/global.css — comments referencing DesignGUIDE §2.1 (colors) and §2.3 (typography) rewritten to color.mdx and typography.mdx.
apps/docs/content/docs/dev/architecture.mdx — Reference list entry rewritten to point at apps/docs/content/docs/design/*.mdx. Monorepo-structure block no longer lists DesignGUIDE/.
apps/web/app/api/chat/export/pdf/route.ts — // Colors (from DesignGUIDE) rewritten to point at color.mdx.
apps/web/app/chat/page.tsx — per DesignGUIDE §3.2 JSDoc rewritten to page-templates.mdx (Chat section).
apps/web/app/globals.css — chat-bubble comment rewritten to point at page-templates.mdx (Chat section).
apps/web/app/magazin/magazin-list.tsx — two per DesignGUIDE 3.8 comments rewritten to point at page-templates.mdx (Magazin section).
apps/web/components/fj-accent-wrapper.tsx — JSDoc rewritten to point at components.mdx.
CLAUDE.md (root) — Design system section now states retirement instead of "deprecated and pending migration".
apps/docs/content/docs/operations/ssot-discipline.mdx — Migration table row marked Done.
13 design mdx pages — trailing Quelle: lineage citation footers dropped (the files now stand on their own as canonical SoT).

Why

DesignGUIDE/fragjulia-design-brief-v3.md was always the lineage source for the design system — the long-form narrative that the 15 mdx pages were derived from. Once the mdx tree had reached 89% coverage of brief-v3's content, the legacy tree stopped being useful and started being a liability:

SoT ambiguity. Multiple files claiming to be the source of truth contradicted the SSOT discipline (apps/docs/content/docs/operations/ssot-discipline.mdx). New contributors didn't know which file to update first; some updated the legacy doc and some updated the mdx pages, and the two drifted.
Stale copy by default. The brief-v3 doc was the easy place to look but the slow place to change. The mdx pages got updates first because they ship to docs.fragjulia.de.
Dead-weight artifacts. Eight of the nine files in DesignGUIDE/ were process or HTML-mockup artifacts whose decisions had long since shipped to live code. Keeping them around invited future readers to treat them as live spec.

The 15 mdx pages plus tokens.css are the live SoT — they ship to docs.fragjulia.de, they're keyed off the same tokens that apps/web consumes at runtime, and they're under the same docs-guard CI as the rest of the docs site.