.. _finding_what_to_change:

Finding What to Change
======================

.. contents:: On this page
   :local:
   :depth: 2

One of the most common challenges when customizing an Open edX site is identifying which
CSS variable or style rule controls a specific visual element. This section provides a
recommended methodology for systematically discovering and applying the right changes.

Recommended Workflow
---------------------

The following sequence minimizes the risk of unintended side effects and produces
consistent, maintainable themes:

1. **Start with the base palette**
   Set your version of ``white``, ``black``, and the primary/brand colors in the core
   theme. These foundational colors propagate automatically through the variable hierarchy
   to most components, giving you an immediate sense of how your brand colors look across
   the platform.

2. **Refine semantic colors**
   Adjust the semantic colors — ``primary``, ``brand``, and ``info`` — to match your
   organization's identity precisely. These variables have broad scope and affect buttons,
   links, navigation elements, and informational components throughout the site.

3. **Create a variant and explore component colors**
   Add a ``light`` variant (and optionally a ``dark`` variant) and begin overriding
   body background, text, and surface colors. Use the variant's color override fields
   to experiment without affecting the base theme.

4. **Target specific elements**
   Once the broad strokes are correct, identify specific components that need individual
   attention and use custom Paragon properties or custom CSS to address them.

Using the Browser Inspector
-----------------------------

The most reliable way to find which CSS property controls a specific element is to use
your browser's built-in developer tools:

#. Open your Open edX site in a browser.
#. Right-click the element you want to change and select **Inspect** (or press
   F12 and select the element with the picker tool).
#. In the **Styles** panel, look for CSS declarations that use ``var(--pgn-...)``
   references. These are the Paragon variables controlling the element's appearance.
#. Note the variable name (e.g., ``--pgn-color-primary-base``).
#. Return to Branding by Aulasneo and add that variable as a custom Paragon property
   (see :ref:`custom_paragon_properties`).
#. Save the change and perform a hard browser refresh to see the result.

.. tip::

   In Chrome and Firefox, you can edit CSS variable values directly in the developer
   tools to preview changes before committing them. This is a fast way to experiment
   without creating a new build each time.

When No Paragon Variable Is Found
------------------------------------

If the browser inspector shows that an element's style does not reference any
``--pgn-*`` variable, the component may be styled with hardcoded CSS that is not exposed
through the Paragon token system. In this case:

#. Copy the CSS selector shown in the inspector (e.g., ``.course-card .card-title``).
#. Compose a CSS override using that selector and add it to the **Custom CSS** field of
   your core theme or the relevant variant.
#. Use the ``!important`` declaration if the existing rule has higher specificity than
   your override.

See :ref:`advanced_css` for guidance on writing effective custom CSS overrides.

Checking the Style Map
-----------------------

Before adding a custom Paragon property for a specific variable, check the
:ref:`style_map` to understand:

* Whether the variable has a parent variable that, if changed, would affect this and
  related components simultaneously (a more efficient change).
* Whether the variable is actually used in the current version of Open edX (variables
  that exist in Paragon but are unreferenced by any MFE component will have no visible
  effect).

Common Variable Patterns
-------------------------

The following table lists common visual concerns and the Paragon variable categories
most likely to be relevant:

.. list-table:: Common Visual Concerns and Variable Patterns
   :header-rows: 1
   :widths: 35 65

   * - Visual Element
     - Variable Pattern to Look For
   * - Primary buttons and links
     - ``--pgn-color-primary-*``, ``--pgn-color-btn-*``
   * - Navigation header background
     - ``--pgn-color-*-nav-*``, custom CSS for ``.site-header``
   * - Page background color
     - ``--pgn-color-body-bg``, variant ``body_background_color``
   * - Body text color
     - ``--pgn-color-body-color``, variant ``body_text_color``
   * - Warning and alert colors
     - ``--pgn-color-warning-*``, ``--pgn-color-yellow``
   * - Card borders and backgrounds
     - ``--pgn-color-border-*``, ``--pgn-color-card-*``
   * - Input field borders and focus
     - ``--pgn-color-input-*``, ``input_focus_color`` in variant
   * - Heading color
     - ``--pgn-color-headings-*``, variant ``headings_color``
   * - Footer background
     - Custom CSS targeting the footer component

`Back to Home <index.html>`_