ds-galo/openspec/changes/archive/2026-10-11-add-halo-branding/design.md

Design

Context

See proposal.md - Why. Current state that shapes the approach:

• frontend/src/app.html:6 already points at %sveltekit.assets%/favicon.png, but frontend/static/ does not exist, so the request 404s.
• The icon system (ui-iconography) requires self-contained inline vector icons with no external requests, and icons that inherit the theme color.
• Theme colors live as CSS custom properties on :root per theme (--primary = blue light/dark, orange neutral), defined in frontend/src/app.css.
• Static assets flow through frontend/static/ -> frontend/build/ -> backend/static/ -> go:embed -> served by the static handler. No backend change is needed.

Goals / Non-Goals

Goals:

• One recognizable halo mark, legible down to 16px, used consistently as UI emblem and favicon.
• Theme-awareness in both the UI emblem and the browser/touch icon.
• Zero external requests for any brand asset.

Non-Goals:

• Changing the wordmark, typography, or theme palette.
• Open Graph / social preview images, PWA manifest icons, or app-store assets.
• Any backend or API change.

Decisions

D1. Concept: pure halo (variant A)

A sun disc with a separated outer ring. Alternatives: rays/glow (rejected - detail collapses at 16px) and an aperture hybrid (rejected - two meanings compete at small sizes). Geometry keeps a clear gap between disc and ring so the halo reads as a halo.

D2. Two-tone color with monochrome fallback

In the UI, the disc uses --primary and the ring uses --primary at reduced opacity; a single-color currentColor fallback keeps the mark usable where the two-tone treatment does not apply. Alternative: strictly monochrome (rejected - loses the "sun inside a halo" reading).

D3. Inline SVG for UI, static files for favicon

The UI emblem is an inline SVG component so it inherits currentColor/theme and satisfies the no-external-requests rule, mirroring the existing icon approach. The favicon cannot use CSS custom properties, so it is a standalone asset that carries its own theme rules.

D4. Favicon formats

Ship favicon.svg with an embedded prefers-color-scheme rule (dark and light variants), plus favicon.png and apple-touch-icon.png fallbacks. app.html references the SVG and keeps a PNG fallback. Alternative: .ico only (rejected - no theme awareness).

D5. Placement

Emblem in the AppShell header, the public/login layout, and the share-page header, always next to the "Galo" wordmark, where it is decorative (hidden from assistive tech).

D6. Asset pipeline

Files live in frontend/static/; the existing make frontend copy step carries them into backend/static/ for embedding, so the backend serves them unchanged.

Risks / Trade-offs

• [Mark illegible at 16px] -> Keep geometry minimal (thick-enough ring, clear gap) and verify a 16px render.
• [SVG favicon not supported everywhere] -> Provide the PNG fallback in app.html.
• [Favicon cannot use theme CSS variables] -> Embed prefers-color-scheme rules directly in the SVG.
• [Asset bloat] -> Keep the SVG hand-written and small; PNGs limited to the needed sizes.