Advanced CSS Styling

While Paragon design tokens cover a wide range of visual properties, some front-end characteristics require deeper CSS customization. Branding by Aulasneo provides a Custom CSS field on both the core theme and each theme variant, allowing you to inject raw CSS that is applied at runtime without rebuilding Docker images or restarting services.

When to Use Custom CSS

Use custom CSS when:

  • The visual property you need to change is not exposed as a Paragon variable.

  • A Paragon variable exists but is overridden by a higher-specificity rule in the MFE component’s own stylesheet.

  • You need to make structural changes, such as hiding an element, adjusting layout dimensions, or overriding animation behavior.

When a Paragon custom property can accomplish the same result, prefer that approach over raw CSS, as it integrates better with the variable inheritance system and is less likely to break after Open edX upgrades.

Scope of Custom CSS

Custom CSS can be added at two levels:

Core theme level

CSS added here applies globally, regardless of the active variant. It is loaded as part of the core theme stylesheet.

Variant level

CSS added here applies only when that variant is active. It is loaded as part of the variant stylesheet and stacks on top of the core theme CSS.

Writing Effective CSS Overrides

The following practices help ensure your custom CSS is robust and does not produce unintended side effects:

Be specific with selectors

Use the most precise selector that targets only the element you intend to change. Overly broad selectors (e.g., targeting div or .container) risk affecting many unrelated parts of the site.

Use ``!important`` when necessary

Paragon component stylesheets and MFE-specific CSS often have high specificity. If your override is not being applied, adding !important ensures your rule takes precedence.

.some-component .title {
    color: #3a7bd5 !important;
}
Test with the browser inspector first

Before saving CSS to the theme, prototype it in the browser’s developer tools. This allows you to confirm the selector is correct and the change has the desired effect before it is applied site-wide.

Prefer class selectors over tag selectors

Classes are more specific and less likely to produce unintended side effects than targeting HTML tags directly.

Practical Examples

The following examples illustrate common customizations achievable with custom CSS.

Remove the animated welcome banner on the home page

.home-banner .animation-wrapper {
    animation: none !important;
}

Change the site header background to a custom color

.site-header {
    background-color: #1a1a2e !important;
}

Hide the footer “Powered by Open edX” badge

.footer-logo {
    display: none !important;
}

Reduce the font size of course card titles

.course-card .course-title {
    font-size: 0.95rem !important;
}

Apply a gradient background to the home page hero section

.home-banner {
    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%) !important;
}

Variant-Specific CSS

Custom CSS at the variant level allows you to apply mode-specific styling. For example, you might want a different navigation bar treatment in dark mode:

/* Added to the 'dark' variant's Custom CSS field */
.site-header {
    border-bottom: 1px solid rgba(255, 255, 255, 0.1) !important;
}

Limitations and Cautions

  • No validation: Custom CSS is injected as written. Syntax errors, missing semicolons, or malformed rules will silently fail or, in severe cases, break the layout of affected pages.

  • Upgrade risk: CSS class names in Open edX MFEs can change between platform versions. Selectors that work today may stop working after an Open edX upgrade. Review your custom CSS after each major platform upgrade.

  • Performance: Large amounts of custom CSS can affect page load time. Keep overrides focused and remove rules that are no longer needed.

  • Scope awareness: Custom CSS at the core theme level affects all pages. If you want a change to apply only in a specific mode, add it to the relevant variant instead.

Back to Home