UI & Customization

Themes & Component Factory

Token-based styling systems, abstract factories, registry routing, and custom visual effects.

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

ChatScreen UI context.wk context.wkc Component Factory WiltkeyComponents budgetIndicator() syncVisual() Cyberpunk Theme Garden Theme

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 pedal canvas transitions (petal_flower.dart), wilt self-destruct nuke animations.
    • Paperink: Monochromatic ink, flat sketch lines, flood fill nuke animations.

Key Files & Symbols

File Path Symbol Name Description
lib/core/theme/wiltkey_tokens.dart WiltkeyTokens Concrete ThemeExtension holding the token values (colors, typography, sizing) for the active theme.
lib/core/theme/wiltkey_components.dart WiltkeyComponents Abstract base specifying themed component builders (e.g., budgetIndicator(), syncVisual(), nukeOverlay()); each theme subclasses it (CyberpunkComponents, etc.).
lib/core/theme/theme_registry.dart WiltkeyThemeRegistry Holds registered themes list and loads/persists chosen theme IDs.
lib/core/theme/wk.dart context.wk / context.wkc Extension shortcuts for direct build context token and factory lookups.

Gotchas & Edge Cases

⚠️ THEME PERSISTENCE IS EXEMPT FROM NUKES
Theme configurations are stored in SharedPreferences using a separate key prefix (wk_theme_id). They are intentionally exempt from the clearAll() wipe sequence. This is a deliberate project design choice: the appearance settings do not contain private information, and a user's chosen aesthetic should survive a self-destruct/reset.