docs/android/theme-plan.md

Android theme plan — mirroring the website frontend

This is a summary of the website frontend theme (source of truth: website/client/src/styles/theme.css, applied at runtime by website/client/src/contexts/SiteContext.jsx) so the native Android client can present a visually consistent brand. Where the web uses CSS custom properties, the Android equivalent is a Compose MaterialTheme ColorScheme + Typography.

Overall character

A dark, moody, "arcane fantasy" theme — deep blue-black backgrounds, muted slate-blue accent, parchment-white text, and an engraved serif display face. It reads like a leather-and-moonlight fantasy ledger, not a bright consumer app. There is no light mode on the web; the app should ship dark-only to match.

Color tokens

The web theme is a flat set of CSS variables under :root. Map them to Compose as follows (hex is authoritative):

Web token	Hex	Role	Compose slot (suggested)
--bg	#0e1318	App background	background
--bg-deep	#0b0f14	Deepest surface / on-accent text	surfaceDim / onPrimary
--panel-a	#192231	Card gradient top	surface
--panel-b	#141a21	Card gradient bottom	surfaceContainer
--panel-flat	#11161d	Flat panels, toolbars	surfaceContainerLow
--line	#2a3544	Borders / dividers	outline
--line-soft	#1d2733	Subtle row dividers	outlineVariant
--accent	#7f99bd	Primary accent (brand-overridable)	primary
--accent-bright	#cdd9e8	Primary button fill, active states	primaryContainer / bright
--ink	#eef3f8	Highest-contrast text	onBackground
--head	#e6edf6	Headings	heading color
--text	#c4cdd8	Body prose	onSurface
--muted	#aeb8c4	Secondary text	onSurfaceVariant
--dim	#6f7d8e	Meta / captions / placeholders	dim / disabled text
--blue	#13243c	Accent hover/active background	secondaryContainer
--mode-live	#5fb98a	"Shard live" status (green)	success
--mode-maint	#e6c26a	"Maintenance" status (amber)	warning

Semantic / status colors (used in badges, diffs, moderation)

• Success / published / live: green #5fb98a (fills at ~16–22% alpha, text #7fd0a4).
• Warning / maintenance / moderation (kick/mute/warn): amber #e0b070 / #e6c26a.
• Danger / ban / red-link / errors: desaturated red #d98b84 (borders #6e3b38).
• Admin badge: near-white #d8e2ef on #3a4a5e.

Branding is data, not code

The --accent value is overridden at runtime per shard instance. On the web, SiteContext reads brand.accent from the site settings API and sets the CSS variable, so one build reskins for any shard. The Android app should do the same: fetch the brand payload (name, accent, colors, logo/hero/favicon) from the website API and derive the primary color at runtime rather than hardcoding #7f99bd. Default to #7f99bd when the brand payload is absent/offline.

Typography

Three font families, by role:

• Display (--display): Cinzel, falling back to Georgia serif — an engraved Roman capitals face used for the logo, h1/.h1, and prose h2/h3. Bundle Cinzel as an app font; this face carries the brand.
• Serif body (--serif): Georgia / Times New Roman — default body and prose text; line-height ≈ 1.6.
• Sans (--sans): Helvetica Neue / Arial — UI chrome: buttons, pills, form labels, table headers, badges, meta. Labels/eyebrows/kickers are UPPERCASE with wide letter-spacing (0.1–0.18em) and small (0.68–0.86rem).

Heading scale is fluid on web (h1 clamps ~2.4–3.6rem); pick fixed Material type scale equivalents (e.g. display for h1, headline for h2, title for h3).

Shape, elevation & motion

• Corners: cards/panels 10–12px radius; inputs/small elements 8px; pills and buttons are fully rounded (999px / capsule).
• Cards: vertical gradient --panel-a → --panel-b, 1px --line border, soft drop shadow (0 14px 34px rgba(0,0,0,0.3)). On hover the web lifts -3px and brightens the border to --accent — translate to a pressed/focused accent border on Android.
• Buttons: primary = bright fill (--accent-bright) with dark text; ghost/secondary = translucent dark fill with accent-on-hover border.
• Motion: short, subtle transitions (0.12–0.18s). Keep animations understated.

Signature accents (nice-to-have)

• The "moon" motif: a radial-gradient sphere (#eef3f8 → #9fb0c6 → #5d6e88) — a small brand flourish worth reproducing.
• Accent-tinted focus rings and left-border "note" callouts (border-left: 3px solid --accent over a translucent --blue background).

Implementation note for Compose

Define one darkColorScheme(...) from the table above, a Typography binding the three families, and a Shapes set (small = 8.dp, medium = 10.dp, capsule for buttons). Load accent from the brand API into a state holder and rebuild the primary (and derived primaryContainer) at runtime so a shard's custom accent flows through the whole UI — exactly as SiteContext does on the web.