ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read

• Status: Accepted (plan tenant-branding, tasks 001-009, 012, 2026-10-25). Two items NEEDS_REVIEW (below).
• Extends: ADR 0014 (the five keys are ordinary registry keys).
• Uses: ADR 0017 (the public read goes through the BFF route table and BffApiBridge).
• Plan: plans/tenant-branding/ (_index.md, 00-contract.md, progress 001-012).

Context

Every tenant saw the Dudoxx name, logo, palette and fonts. A new tenant needs its own name, logo and theme in the portal, and the platform needs one default for the public site and /auth. The mobile auth screen also showed the app name twice.

Decision

1. Five settings keys, category branding, in the existing registry: portal.branding.displayName (per-locale object, 1-48 chars), .palette, .font, .illustration, .logo ({ mode, style }). Platform default plus org override, no user tier; org-admin edits the org tier. Values are ids, never colours or font families. Table: settings.md §Branding keys.
2. Palettes are vendored registry brand files, not runtime colours: neutral, solace-grid and verdant-loop sit beside dudoxx.css in ddx-web/src/styles/brands/ and are selected by <html data-brand>. They are copies of the registry output, never hand-edited. The registry palettes were fixed upstream for WCAG AA and re-vendored; check-contrast.mjs now gates every brand in light and dark (248 of 248 pairs).
3. Fonts are next/font pairs chosen by <html data-font>: dudoxx (Urbanist), editorial (Fraunces), serif (Source Serif 4). A bridge in globals.css makes --font-display resolve on every palette: vendored palettes define --token-font-heading, not --token-font-display.
4. One writer. BrandThemeScope (components/providers/BrandingProvider.tsx) is the only code that sets data-brand and data-font. It is a layer stack: site scope (marketing and auth layouts), tenant scope (portal/[orgSlug]), and a preview layer for a draft, used by the branding wizard. A preview unmounts back to the layer below.
5. Logo is generated on the client. BrandLogo draws a monogram or wordmark SVG from the tenant name with semantic tokens; upload mode uses the org logo and falls back to the generated mark on error; platform uses /logo.png. BrandIllustration draws signal, grid or orbit SVG, or nothing.
6. Public platform read. GET /platform/branding returns only the five platform-tier values (strict projection, @Public()). /platform/branding is in the BFF PUBLIC_PATHS, so ddx-web reads it without a session through callUpstream ('use cache', tag platform-branding, revalidated by a platform branding write).
7. Portal identity fallback. An org with no org-tier displayName or logo shows its org name and uploaded org logo, else a mark generated from the org name. The platform name and logo appear on the site scope only.
8. Onboarding. Create-org redirects to <P>/settings/branding?onboarding=1, a five-step wizard with review (org-admin only), saving the changed keys sequentially at org tier with the org version.

Rejected: free colour input and per-surface colour pickers (breaks AA and the design system); a per-tenant theme table (the generic tier rows already carry the keys); presigned logo URLs (ADR 0011).

Consequences

• NEEDS_REVIEW a — font faces. Fraunces and Source Serif 4 are two extra next/font faces. They widen the three-face rule in ddx-web/DESIGN.md for tenant fonts only. The owner decides whether to keep the widening.
• NEEDS_REVIEW b — first paint. The palette is applied in a client effect (the textSize precedent). The first hard load after a palette change can paint the previous palette once (seen on /fr: first load dudoxx with the new name, second load neutral). The ddx_brand_palette and ddx_brand_font cookies are written but nothing reads them yet.
• Deferred: orphaned logo objects are not deleted (an upload stores bytes at once; leaving the wizard keeps them). Org.brandPreset is unused and untouched; the settings key is the runtime source.
• Open defects (progress/009.md): the platform settings page keeps "Seed value, never saved" until reload after a save; the wizard name step pre-fills the platform name as the tenant value; the wizard shows two button sets per step; the home hero title and site.brand.home label stay fixed text; verdant-loop dark KPI cards read red-brown.
• Not browser-tested: upload of a real PNG logo (the input accepts PNG, JPEG, WebP only; no SVG).
• Gate chain unchanged: ./ddx-manage.sh i18n, naming, bff-layers; check-contrast.mjs covers every vendored brand.

Last reconciled: 2026-10-25 · plan tenant-branding task 010

• ddx-documentation — dudoxx-web-boot

adr/

• ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides
• ADR 0002 — Auth: better-auth 1.7 in ddx-api
• ADR 0003 — Route shape: org slug, role, [entity]/[id], ?view=
• ADR 0004 — Database split: one Postgres 18 instance, six databases
• ADR 0005 — Frameworks and the approved dependency table
• ADR 0006 — API clients come from one factory
• ADR 0007 — Typed service container (DI / IoC)
• ADR 0008 — Singleton scope: what may live at module level
• ADR 0009 — One variant API for every inventory component
• ADR 0010 — Media path: presigned URLs from ddx-api after the org check
• ADR 0011 — Media proxy: MinIO only through ddx-api
• ADR 0012 — Density names: compact | cosy | large
• ADR 0013 — Platform super-admin acts as org-admin of the target org
• ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api
• ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain
• ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue
• ADR 0017 — Layered BFF: one route table, route classes, read models
• ADR 0018 — Cluster node registry, node identity, hot plug
• ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read
• Debug overlay

deploy/

• Deploy runbook — dudoxx-web-boot
• Entity kernel — guide
• Feature map — what each role can do
• Component inventory
• Naming constitution — dudoxx-web-boot
• Observability — one log layout, one key set
• Pattern reference — P1-P23 and groups A-K
• Port map — dudoxx-web-boot

research/

• RQ1 — Which release is "latest", and does it differ from the canon?
• RQ10 — SSE through the Next.js BFF route handler (desk half)
• RQ11 — Dev latency baseline: cold compile per route + next-server RSS
• RQ2 — Route group or dynamic org slug?
• RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix
• RQ4 — Separate databases or separate schemas?
• RQ5 — Which frameworks beyond shadcn earn a place?
• RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?
• RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?
• RQ8 — Media path: presigned URLs vs streaming through the BFF
• Template triage — create-nextjs code in ddx-web
• Settings — guide
• Local setup — dudoxx-web-boot
• Shell tree — SiteShell and PortalShell
• SSE event catalog
• Version pins — dudoxx-web-boot