Troubleshooting Custom Font Display Issues in Theme Builder

Overview

When implementing custom fonts through the Magentrix Theme Builder, you may encounter inconsistent font rendering where your brand fonts appear correctly on some pages but revert to default system fonts (like Open Sans or Arial) on others. This article explains how to diagnose and resolve font import errors and CSS configuration issues that cause inconsistent typography across your portal.

Common symptoms:

• Custom fonts display correctly on certain pages (e.g., Dashboard, Engagement pages)
• Other pages show default browser fonts instead of your brand fonts (e.g., Course Library, course detail pages, specific module pages)
• Fonts appear inconsistent after clearing browser cache or accessing from different devices

Root cause: Typically caused by syntax errors in the custom font import statement or incomplete CSS font-family declarations in the Theme Builder's Custom CSS section.

Prerequisites

Before troubleshooting font issues, ensure you have:

• Administrator System Role permissions with access to Theme Builder
• Access to Setup > Manage > Company Preferences > System Settings > Theme Builder
• The correct font import URL or @font-face code from your font provider (e.g., Google Fonts, Adobe Fonts)
• Basic familiarity with CSS syntax (or ability to follow step-by-step instructions)

Steps to Resolve Font Display Issues

Step 1: Access Theme Builder Custom CSS

1. Navigate to Setup Home in your Magentrix portal
2. Click Manage > Company Preferences
3. Select System Settings
4. Click Open Theme Builder
5. In the Theme Builder interface, click the menu dropdown icon (top left)
6. Select CSS from the options

You should now see the Custom CSS editor where your font imports and styling rules are defined.

Step 2: Verify Font Import Statement

Check your @import or @font-face statement at the top of the Custom CSS section for syntax errors.

Common font import errors:

❌ Incorrect: Missing quotes, wrong parameter format, or typos in the URL

@import url(https://fonts.googleapis.com/css2?family=Outfit:wght@400;700display=swap);

✅ Correct: Proper URL formatting with all parameters

@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;700&display=swap');

What to look for:

• Missing & before URL parameters (e.g., &display=swap)
• Missing quotes around the URL (should be url('...') not url(...))
• Typos in the font family name or weight parameters
• Incorrect protocol (should be https:// not http://)

To verify your font URL works:

1. Copy the URL from inside the @import statement
2. Paste it directly into a new browser tab
3. If it loads CSS code, the URL is valid; if you see an error, the URL needs correction

Step 3: Correct the Font Import Statement

Once you've identified errors in the import statement:

1. For Google Fonts:

   • Go to Google Fonts
   • Select your desired font and weights
   • Click "View selected families"
   • Copy the @import code provided
   • Paste it at the very top of your Custom CSS section

2. For other font providers:

   • Obtain the correct @import or @font-face code from your font service
   • Ensure the URL is publicly accessible (not behind authentication)
   • Paste the code at the top of Custom CSS

Example of correct Google Fonts import:

@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&display=swap');

Step 4: Apply Font Globally with CSS Rules

After fixing the import statement, explicitly define where the custom font should be applied across your portal.

Add the following CSS rules below your @import statement:

/* Apply custom font to body text */
body, 
p, 
li, 
span, 
div {
  font-family: 'Outfit', sans-serif;
}

/* Apply font to headings */
h1, 
h2, 
h3, 
h4, 
h5, 
h6,
.page-title,
.section-header {
  font-family: 'Outfit', sans-serif;
  font-weight: 600;
}

Important notes:

• Replace 'Outfit' with your actual font name (use the exact name from the import statement)
• Keep the generic fallback font family (e.g., sans-serif or serif) after your custom font
• Add font-weight values that match the weights you imported

Step 5: Save and Publish Changes

1. In the Custom CSS editor, check the Enabled checkbox
2. Click Apply to save your CSS changes
3. In the Theme Builder interface, click Publish (top right)
4. Click Yes to confirm publication
5. Important: Changes go live immediately across the entire portal

<img src="placeholder-for-publish-button-screenshot.png" alt="Screenshot showing the Publish button location in Theme Builder" />

Step 6: Clear Cache and Verify Font Display

To confirm the fix worked:

1. Hard refresh your browser:

   • Windows/Linux: Press Ctrl + Shift + R or Ctrl + F5
   • Mac: Press Cmd + Shift + R

2. Test in incognito/private browsing mode:

   • This ensures you're seeing the latest changes without cached files

3. Verify font display on multiple page types:

   • Dashboard/Home page
   • Course Library (if applicable)
   • Individual course detail pages
   • Navigation menus and headers
   • Article or Wiki pages

4. Check browser Developer Tools:

   • Right-click any text element and select Inspect
   • In the Styles panel, verify that font-family shows your custom font name
   • If you see your font crossed out, there's still a CSS specificity or import issue

Troubleshooting

Problem: Fonts still showing default after following all steps

Possible causes and solutions:

1. Browser cache not fully cleared

   • Solution: Close all browser windows and reopen, or test in a different browser

2. Font URL is not publicly accessible

   • Solution: Verify the font URL loads when pasted directly in a browser
   • Check that the URL doesn't require authentication

3. CSS specificity conflict

   • Solution: Add !important flag as a temporary test:

     body { font-family: 'Outfit', sans-serif !important; }
     

   • If this works, you have a specificity issue and need to make your selectors more specific

4. Font name mismatch

   • Solution: Ensure the font name in your font-family declaration exactly matches the name from the import statement (case-sensitive)

Problem: Fonts display correctly in Chrome but not Safari/Firefox

Solution: Some font services use browser-specific formats. Ensure your font import includes multiple format options:

@font-face {
  font-family: 'YourFont';
  src: url('font.woff2') format('woff2'),
       url('font.woff') format('woff'),
       url('font.ttf') format('truetype');
}

For Google Fonts, this is handled automatically in the URL parameters by including &display=swap.

Problem: Fonts load slowly or cause flash of unstyled text (FOUT)

Solution: Add font-display: swap; to your font import to improve perceived performance:

@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;700&display=swap');

This tells the browser to show fallback fonts immediately while loading custom fonts in the background.

Best Practices

✅ Test font URLs before implementation: Always verify font URLs load correctly in a browser before adding to Theme Builder

✅ Keep imports at the top: Place all @import statements at the very beginning of your Custom CSS section

✅ Use consistent fallback fonts: Always include generic fallback fonts (e.g., sans-serif, serif, monospace) after custom fonts

✅ Limit font weights: Only import the font weights you actually use to improve page load performance

✅ Document your font stack: Keep a comment in your CSS noting which fonts are used where for future reference:

/* Brand Fonts:
   - Outfit: Body copy and general text
   - Montserrat: Headings and titles
*/

✅ Preview before publishing: Always use Theme Builder's preview feature to test changes across different page types and devices

❌ Avoid: Altering core Magentrix functionality with JavaScript (stick to CSS for styling)

❌ Avoid: Using local font files uploaded to Theme Builder (use CDN-hosted fonts for better performance and reliability)

Related Resources

Magentrix Documentation:

• Using the Theme Builder - Complete guide to Theme Builder features and configuration

Magentrix Features:

• Magentrix Theme Builder - No-code theme customization capabilities for brand consistency

External Resources:

• Google Fonts - Free, professionally designed web fonts
• Adobe Fonts - Premium font library (requires Adobe Creative Cloud subscription)

Need Additional Help?

If you've followed all troubleshooting steps and fonts still aren't displaying correctly:

1. Take screenshots showing:

   • The Custom CSS section with your font import and rules
   • The page(s) where fonts display incorrectly
   • Browser Developer Tools showing the computed font-family value

2. Open a support ticket with:

   • Your portal URL
   • Description of which pages show incorrect fonts
   • Browser and device information
   • Screenshots from step 1

3. Include CSS details:

   • Copy and paste your complete Custom CSS code (from Theme Builder)
   • Note any custom JavaScript that might affect styling