Theming & White-Label Customization
Relevant source files
The following files were used as context for generating this wiki page:
- src/lib/theme.ts
- src/lib/theme-settings.ts
- src/lib/theme-site-identity.ts
- src/app/[locale]/admin/theme/_components/AdminThemeSettingsFormInner.tsx
- src/app/[locale]/admin/(general)/_components/AdminGeneralSettingsForm.tsx/_components/AdminGeneralSettingsForm.tsx)
- src/app/[locale]/admin/(general)/_actions/update-general-settings.ts/_actions/update-general-settings.ts)
- tests/unit/theme.test.ts
- tests/unit/theme-site-identity.test.ts
Theming and white-label customization in the Prediction Market platform allows administrators to tailor the visual identity, brand metadata, and functional integrations of the site. The system is split into two primary domains: visual aesthetics (colors, border radii, presets) and brand identity (logos, site names, social links, and SEO metadata). This customization ensures the platform can be rebranded for different operators while maintaining a consistent core functionality.
The system utilizes a combination of server-side settings persistence in a database and client-side CSS variable injection to apply themes dynamically. Operators can modify these settings via an administrative interface that provides real-time previews for both light and dark modes.
Sources: src/lib/theme-settings.ts, src/app/[locale]/admin/theme/_components/AdminThemeSettingsFormInner.tsx
Visual Theming Architecture
The visual theme is driven by Theme Tokens, which are CSS variables mapped to specific UI elements. These tokens are organized into Presets but can be individually overridden for both light and dark modes.
Theme Tokens and Presets
The system defines a standard set of tokens such as primary, background, accent, and destructive. These tokens support hex and oklch() color formats. Four default presets are available to provide a baseline aesthetic:
- Default: Standard palette.
- Midnight: Cool blue-purple tones.
- Lime: High-energy green accents.
- Amber: Warm amber tones.
Sources: src/lib/theme.ts:47-92, tests/unit/theme.test.ts:16-25
CSS Variable Injection
The buildThemeCssText function converts theme overrides and border radius settings into a CSS string. This string is injected into the document head within a style tag (ID theme-vars) and applied via data attributes (data-theme-preset) and class selectors (.dark).
The diagram shows the flow from administrative configuration to the live application of styles on the user interface.
Sources: src/lib/theme.ts:241-274, src/app/[locale]/admin/theme/_components/AdminThemeSettingsFormInner.tsx:90-112
Site Identity & White-Labeling
White-labeling is managed through the ThemeSiteIdentity interface, which encapsulates all brand-specific configurations.
Brand Assets and Metadata
Administrators can configure the site name, description (for SEO), and logos. The logo supports two modes:
- SVG Mode: A sanitized SVG string provided via the admin panel. The system automatically normalizes root dimensions and removes fixed width/height attributes to ensure responsiveness.
- Image Mode: Uploaded image files (PNG, JPG, WebP) processed and stored as public assets.
Sources: src/lib/theme-site-identity.ts:46-64, src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:402-427
Social and Integration Metadata
The platform supports linking various social media platforms and external tools. The getThemeSiteSameAs helper aggregates these links for use in structured data (JSON-LD) to improve search engine visibility.
| Field | Description | Validation |
|---|---|---|
name | The public name of the site. | Required, max 80 chars. |
description | Site metadata description. | Required, max 180 chars. |
supportUrl | Contact link for users. | Normalizes emails to mailto:. |
googleAnalyticsId | G-XXXX tracking ID. | Format: ^G-[A-Z0-9]+$. |
socialLinks | Twitter, Discord, FB, etc. | Validates HTTP/HTTPS protocols. |
Sources: src/lib/theme-site-identity.ts:178-306, tests/unit/structuredData.test.ts:77-94
Data Flow & Persistence
Theme and identity settings are stored in a centralized database managed by the SettingsRepository. Settings are categorized into groups like theme and general.
Settings Update Process
When an administrator saves changes, a Server Action (updateGeneralSettingsAction) handles file uploads (logos, PWA icons, PDFs), encrypts sensitive API keys, and updates the repository.
The sequence diagram illustrates the multi-step process of persisting white-label configurations, including external asset storage and cache invalidation.
Sources: src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:489-738, src/lib/theme-settings.ts:430-520
Runtime Resolution
At runtime, the loadRuntimeThemeState function retrieves settings from the database and resolves them against defaults. If the database is unavailable or settings are missing, it falls back to a hardcoded default theme state.
Sources: src/lib/theme-settings.ts:522-536
Progressive Web App (PWA) Customization
Operators can provide custom icons for PWA functionality. The system requires two specific sizes (192x192 and 512x512) and automatically generates an apple-touch-icon. If custom icons are not provided, the platform serves default brand icons.
Sources: src/lib/theme-site-identity.ts:98-124, src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:430-454
Summary
The Theming & White-Label Customization system provides a robust framework for operators to brand the prediction market platform. By combining strict validation (SVG sanitization, color format checks) with flexible overrides (CSS tokens) and integrated asset management (automatic image resizing and storage), the platform achieves a balance between aesthetic flexibility and structural integrity. All branding elements—from UI colors to SEO metadata and PWA icons—are manageable through a unified administrative interface.