refactor(docs): repair the illustration layer's token discipline

[marcelxpfeifer]

What & why

Part of the Owlat next-layer UX plan (2026-07-10), workstream D — close the Fluid Functionalism gaps, implementing locked principle 4: one visual system — FF tokens only, zero hardcoded hex/duration/weight.

The apps/docs illustration layer was the single biggest concentration of non-token values in the app. This is a token-correctness sweep, not a redesign — every diagram renders identically.

Changes (three atomic commits)

1. Drop stale hex fallbacks from the three inline-SVG illustration components (AuthFlowIllustration, EmailPipelineIllustration, MtaArchitectureIllustration). Every token reference carried a hardcoded var(--token, #hex) fallback and several had drifted stale — e.g. var(--color-bg-surface, #1c1916) when the token now resolves to #252525, and var(--color-border-default, #262320) vs the current #2e2e2e. The FF token stylesheet (packages/ui/assets/css/index.css) is imported globally by the docs app, so these tokens are always defined and the hex fallbacks are dead backstops that can only drift stale. Removing them deletes 300+ hardcoded hex values and makes the stale-fallback class of bug impossible to reintroduce (refreshing the hex would just re-arm the same footgun).
2. FF font-weight tokens: font-weight: 600/500 → var(--font-weight-semibold|medium) (FF 550/450) in CSS; inline-SVG font-weight="600" presentation attributes (which cannot parse var()) → numeric 550. Existing FF weights (400/550/700) unchanged.
3. Route the node-in entrance through motion tokens: all three illustrations' decorative choreo-tier reveal now use var(--motion-choreo) var(--ease-spring) directly — removing the last raw duration+curve pair (AuthFlow's 0.7s cubic-bezier(0.16,1,0.3,1)) and the redundant 800ms/cubic-bezier fallbacks.

Acceptance criteria

• No stale var(--token, #fallback) hex fallbacks remain in the touched files (grep-guard: 0)
• No non-FF font weights (600/500) remain (grep-guard: 0)
• No raw cubic-bezier / hardcoded animation duration in the entrance reveals (grep-guard: 0)
• Diagrams stay visually identical (tokens resolve to the same values; entrance timing aligned to the existing sibling illustrations)
• Dark and light both covered (the tokens themselves carry per-theme values)

Deliberately out of scope (preserve visuals)

• Standalone raw hex that are not token fallbacks stay: flood-color="#000" (SVG drop-shadow primitive) and DomainFlow's #c45a5a error-red used directly in color/color-mix — tokenizing it would change the exact rendered colour.
• The long infinite pulse/dash loops (2–10s) have no motion-tier equivalent (tiers cap at --motion-choreo = 800ms); routing them through a tier would drastically change speed, so they are left untouched.

Preserved behavior

• No routes, flows, permissions, or component APIs touched — pure presentational token discipline inside apps/docs diagram components.
• All illustration/content component tag names, props, and structure unchanged.

Test notes

Primarily visual; enforced by grep-guard at review/CI. Verified locally: 0 stale hex fallbacks, 0 non-FF weights, 0 raw cubic-bezier in the touched files; oxlint clean on both changed directories.

Auto-merge pipeline: squash-merges on reviewer approval + green CI.

[marcelxpfeifer]

Review — round 1

Verdict: APPROVE

Verified this is a pure token-correctness sweep, exactly as spec'd — no redesign, no security/logic surface touched.

Blocking

none

Improvements

none

Notes (verified, no action needed)

• Stale-fallback removals are correct: confirmed --color-border-default now resolves to #2e2e2e (old fallback #262320 was stale) and --color-bg-surface→#252525 (old #1c1916 stale). packages/ui/assets/css/index.css is imported globally via apps/docs/app/assets/css/main.css, so the tokens are always defined and the hex fallbacks were dead backstops — safe to drop.
• Grep-guard clean at head across all 27 touched files: 0 remaining var(--token, #hex) fallbacks, 0 leftover CSS font-weight: 600/500, 0 leftover 600/500 SVG presentation attrs, 0 raw cubic-bezier/ms in the entrance reveals.
• FF weight tokens verified: --font-weight-medium: 450, --font-weight-semibold: 550; inline-SVG attrs correctly use numeric 550 (can't parse var()).
• Motion verified: --motion-choreo: 800ms, --ease-spring exist; all three illustrations now consume var(--motion-choreo) var(--ease-spring) directly. AuthFlow's entrance shifts 0.7s→0.8s + curve to match its two sibling illustrations — a one-time decorative reveal, spec-sanctioned ("route durations through the motion tiers") and disclosed in the PR body.
• Deliberately-preserved standalone hex (DomainFlow's #c45a5a, flood-color="#000") are pre-existing, untouched, and not token fallbacks — correctly out of scope since no exact-matching token exists.
• Diff is focused (docs illustration layer only), 3 atomic conventional commits (hex / weights / motion), no AI attribution.
• CI fully green (all checks pass).