Theming & Localization

Relevant source files

The following files were used as context for generating this wiki page:

• app/Support/Theme/ThemeManager.php
• app/Support/Locale/LocaleManager.php
• app/Http/Controllers/Locale/ChangeLocaleController.php
• config/themes.php
• lang/en/ui.php
• tests/Feature/Theme/CssTokensTest.php
• tests/Feature/Theme/ProjectDefaultThemeIntegrationTest.php
• tests/Feature/I18n/TranslationFilesTest.php
• resources/views/layouts/guest.blade.php

The RateGuru platform implements a robust system for visual customization and multi-language support. Theming is managed through a tokenized CSS approach supporting Light, Dark, and System modes, while localization provides a consistent user interface across multiple supported locales including English, Russian, and Bulgarian. These systems ensure the application remains accessible and visually consistent with the PlateRate design contract across different user preferences and regions.

Sources: tests/Feature/Theme/CssTokensTest.php, tests/Feature/I18n/TranslationFilesTest.php, AGENTS.md:52-60

Theming System Architecture

Theming in RateGuru is driven by the ThemeManager and a set of CSS design tokens. The system supports three primary preferences: light, dark, and system. Visual styles are applied using a data-theme attribute on the HTML element, which triggers specific CSS variable overrides defined in the project's stylesheets.

Theme Resolution Logic

The application determines the active theme by checking user preferences stored in localStorage (via rateguru.theme.preference) or falling back to the project's default settings defined in ProjectSettings. If no specific preference is set, the system defaults to the system setting, which typically applies the dark theme by default.

The diagram above shows the priority logic used to determine which visual theme is applied to the UI shell.
Sources: tests/Feature/Theme/ThemeDocsTest.php, tests/Feature/Theme/ProjectDefaultThemeIntegrationTest.php:12-25, resources/views/layouts/guest.blade.php:2

CSS Design Tokens

RateGuru uses semantic CSS variables (tokens) to ensure consistency. These tokens are redefined within [data-theme="light"] and [data-theme="dark"] selectors.

Token	Light Value	Dark Value	Description
--rg-bg	#f7f7fb	(System Default)	Main application background
--rg-surface	#ffffff	(System Default)	Card and panel surfaces
--rg-text	#14141c	#e8e8ee	Primary text color
--rg-border	#e2e2ec	(System Default)	UI borders and dividers
--rg-accent	#7c3aed	#a855f7	Brand accent color

Sources: tests/Feature/Theme/CssTokensTest.php:3-23

Localization (I18n)

Localization is handled by the LocaleManager and standard Laravel translation files. The system supports a multilingual UI where translation keys remain consistent across all supported languages.

Supported Locales

The platform currently supports the following locales:

• English (en): The primary development locale.
• Russian (ru)
• Bulgarian (bg)

Sources: tests/Feature/I18n/TranslationFilesTest.php:3-7

Locale Management Flow

The ChangeLocaleController facilitates switching between languages. When a user selects a different language via the UI language switcher, the application updates the locale session and redirects the user.

The sequence diagram illustrates the process of changing the active application language.
Sources: app/Http/Controllers/Locale/ChangeLocaleController.php, tests/Feature/I18n/Phase46ReviewChecklistTest.php

Translation File Structure

Translations are organized into functional files within the lang/ directory:

• ui.php: Contains all public-facing interface strings (e.g., "Search tags", "Categories").
• auth.php: Authentication-related messages.
• validation.php: Form validation error messages.

Consistency is enforced via tests ensuring that every key present in the English ui.php file is also present in the ru and bg counterparts.
Sources: tests/Feature/I18n/TranslationFilesTest.php:11-17, lang/en/ui.php

Integration in Application Shell

Both theming and localization are integrated into the root layout templates (app.blade.php and guest.blade.php). The layout injects a theme-bootstrap.js script early in the <head> to prevent "flash of unstyled content" (FOUC) by applying the correct data-theme attribute before the body renders.

Layout Implementation details

• HTML Attributes: The <html> tag dynamically sets lang, data-theme, and data-theme-preference.
• CSS Variable Usage: Blade components and layouts use Tailwind classes mapped to theme tokens, such as bg-rg-bg and text-rg-text.

Sources: resources/views/layouts/guest.blade.php:2-15, tests/Feature/ApplicationShellTest.php:12-18

Summary

Theming and Localization in RateGuru are architectural pillars that support the project's goal of being a flexible, generic rating platform. By using ThemeManager for preference resolution and LocaleManager for language steering, the application provides a customized experience that respects both system-level settings and explicit user choices. The use of CSS tokens ensures that UI components remain visually compliant with the RateGuru design contract regardless of the active theme.