Themes & Component Factory

Overview

Wiltkey implements a strict token-driven styling model. Hardcoded color constants, layout paddings, or border styles are forbidden in presentation widgets. Instead, the UI delegates all layout assets to an abstract factory that changes depending on the user's active theme. Themes define not just static colors, but entire custom widgets and visual effects (such as the synchronization or lock screen animations).

Theming Architecture

How it Works

1. Design System Tokens: All colors, typography styles, and structural layouts are defined as tokens inside WiltkeyTokens. Presentation widgets access them via the BuildContext extension helper:
   final tokens = context.wk; // returns WiltkeyTokens
2. Abstract Factory Routing: UI elements are instantiated dynamically. Instead of creating a raw Flutter Container or CustomPainter for themed items, widgets request them from the active component factory:
   Widget glyph = context.wkc.budgetIndicator(ourFraction: 0.7, ...);
   This resolves to the active theme's concrete implementation (e.g. CyberpunkComponents, GardenComponents, or PaperinkComponents).
3. Custom Animations & Effects: Themes declare custom visual effects files:
   • Cyberpunk: Neon purple/cyan, matrix particles, glitch sync visuals (cyberpunk_sync_visual.dart), purge nuke animations.
   • Garden (Dusk Garden): Sage/soils warm colors, flower petal canvas transitions (petal_flower.dart), wilt self-destruct nuke animations.
   • Paperink: Monochromatic ink, flat sketch lines, flood fill nuke animations.
   • Phosphor (Premium): Retro CRT terminal, green/magenta palette, power cell batteries, laser link cable sync.
   • Tideline (Premium): Sea-glass teal, cool foam, tide-gauge budget indicators, rising tide drown animations.
4. Profile Backdrops & Bespoke Animations (Mandatory Requirement): Every theme (both base and premium) MUST implement its own unique profileBackdrop() on its component class. Profile screens dynamically inherit the contact's chosen theme, creating a distinct visual identity per user:
   • Cyberpunk: Falling alphanumeric Matrix rain columns over a dark neon grid.
   • Garden: Dark dusk-green sky fading into fertile soil with atmospheric glow, swaying meadow grass blades, grounded blooming flowers, and drifting petals.
   • Paper & Ink: Hand-painted hanging and fluttering Ofuda paper slips over a woodgrain board.
   • Phosphor: Retro Space Invaders battle with a defense cannon behind the avatar firing laser bursts into marching ranks of alien invaders and mystery UFOs.
   • Tideline: Tranquil underwater world with an undulating surface waterline, refracting sunlight caustics, swimming fish silhouettes, and vertical clusters of buoyancy-scaled rising bubbles.
   Contract Rules for new themes:
   1. Accept a seed parameter (derived from peer keyHash/userId) to initialize math.Random(seed) so layout formations are stable and identical across peers.
   2. Honour context.reduceMotion by disabling swaying/flashing and rendering a calm, static scene.
   3. Never use the generic ProfileBackdropDefaults mixin for final themes — implement a bespoke backdrop that reflects the theme's core visual metaphor.

Dynamic Profile Backdrops & Animations

When previewing or visiting contact profile pages, themes render immersive custom animated backdrops via the profileBackdrop() builder in WiltkeyComponents:

Key Files & Symbols

Gotchas & Edge Cases