.. _theme_variants: Customizing Theme Variants ========================== .. contents:: On this page :local: :depth: 2 Theme **variants** are named layers of color and CSS overrides applied on top of the base CSS theme. They allow you to define distinct visual modes — most commonly a ``light`` and a ``dark`` mode — while reusing the core palette and typography defined in the parent theme. Understanding Variants ----------------------- Each CSS theme can have multiple variants. When the Open edX MFE layer loads a theme, it applies the base theme CSS first, then overlays the variant's CSS on top. The result is a complete visual style for the given mode. The two variants that receive special treatment by browsers and operating systems are: ``light`` The default daytime appearance. Browsers and operating systems automatically activate this variant when the user's system preference is set to light mode. ``dark`` An inverted, low-luminance appearance optimized for nighttime or low-light environments. Activated automatically when the system preference is set to dark mode. Any other variant names you define are accessible via the theme switcher available at the bottom of every Open edX MFE page (provided you have rebuilt the MFE image as described in :ref:`installation`). Creating a Variant ------------------- #. Navigate to **Themes** in the main navigation and open the theme you want to extend. #. Click **Add Variant**. #. Enter a ``slug`` — a lowercase, hyphen-separated identifier (e.g., ``light``, ``dark``, ``high-contrast``). This slug is used in the Tutor configuration and in the CSS file name. #. Set the variant-specific color overrides as described below. #. Optionally add variant-specific custom CSS. #. Click **Save Variant**. .. figure:: screenshots/updating_dark_variant.jpg :alt: Editing the dark theme variant :width: 100% The variant editor provides individual color override fields for all major semantic and component color categories. Variant Color Overrides ------------------------ Variants expose a comprehensive set of color fields. Setting a field in a variant overrides the corresponding value from the parent theme; leaving a field empty causes the theme's value to be used instead. The available override fields are: .. list-table:: Variant Color Override Fields :header-rows: 1 :widths: 35 65 * - Field - Description * - ``primary_color`` - Overrides the primary brand color for this variant. * - ``secondary_color`` - Overrides the secondary color. * - ``brand_color`` - Overrides the brand color. * - ``success_color`` - Overrides the success state color. * - ``info_color`` - Overrides the informational state color. * - ``warning_color`` - Overrides the warning state color. * - ``danger_color`` - Overrides the danger/error state color. * - ``accent_a_color`` - Overrides accent color A. * - ``accent_b_color`` - Overrides accent color B. * - ``nav_link_text_color`` - Controls the color of navigation link text. * - ``headings_color`` - Controls the color of heading elements (H1–H6). * - ``light_base_color`` - The base color used for "light" surface treatments. * - ``dark_base_color`` - The base color used for "dark" surface treatments. * - ``gray_base_color`` - The base neutral/gray color. * - ``border_color`` - Overrides the default border color for components. * - ``input_focus_color`` - The color of the focus ring for form inputs. * - ``background_color`` - Overrides the general page/section background. * - ``body_background_color`` - Overrides the ```` element background color. * - ``body_text_color`` - Overrides the default body text color. Custom CSS per Variant ----------------------- Each variant has its own **Custom CSS** field. CSS entered here is scoped to the variant and is applied in addition to the parent theme's custom CSS. This is useful for variant-specific structural adjustments, such as changing icon colors or adjusting background images for dark mode. Example — adding a dark overlay to the home page banner in dark mode: .. code-block:: css .home-banner { background-color: rgba(0, 0, 0, 0.7) !important; } Automatic Light/Dark Switching -------------------------------- When both a ``light`` and ``dark`` variant are defined, and the end user's MFE has been rebuilt with the Tutor Branding Plugin, a **theme switcher** appears at the bottom of every Open edX MFE page. This switcher provides the following options: * **Auto** — follows the operating system preference (recommended). * **Light** — forces the light variant regardless of system preference. * **Dark** — forces the dark variant regardless of system preference. * Any additional variants you have defined are also listed. Custom Paragon Properties per Variant --------------------------------------- In addition to the color fields described above, you can attach custom Paragon properties directly to a variant for fine-grained CSS variable control. See :ref:`custom_paragon_properties` for full instructions. Deleting a Variant ------------------- Click **Delete Variant** in the variant editor. Deleting a variant removes its compiled CSS from any subsequent build. If a build has already been published that includes this variant, the change will not be reflected in the live site until a new build is created and the Tutor command is re-run. `Back to Home `_