Skip to content

CSS Theming Guide

Date: 2026-03-23

How Theming Works

The theming system follows a base + override pattern:

  1. Base CSS (CommonV2.css) provides default styles for all components, layout, typography, and utilities shared across every client site.
  2. Client CSS (e.g., AbbeyStyles.css) overrides colors, fonts, buttons, header/footer, and any component styles specific to that credit union's brand.
  3. Culture CSS (optional, e.g., AbbeyStyles-cy.css) overrides language-specific styles (Welsh translations that affect layout widths, etc.).

The client stylesheet path is stored in Umbraco under the Site Style Configuration content node (siteStyleConfiguration document type), in the stylesheet property. The master layout reads this at runtime via SiteSettings.Styles.StyleSheet.

Load Order

CSS loads in this order in master.cshtml (later files win):

1. Bootstrap 5.3.3           ~/vendor/bootstrap/css/bootstrap.min.css
2. Bootstrap extras           bootstrap-negative-margins.css, bootstrap-select.css
3. Menu style CSS             ~/vendor/menu{N}/css/style.css (based on MenuStyle setting)
4. Slick slider               ~/vendor/slick/slick.css + slick-theme.css
5. Font Awesome 6 Pro         ~/vendor/fontawesome-pro/css/all.min.css
6. Fancybox + jQuery UI       vendor CSS
7. CommonV2.css               ~/content/CommonV2.css (base styles)
8. RTE.css                    ~/css/RTE.css
9. Block Grid CSS             ~/css/umbraco-blockgrid.css
10. Grid/Home slider CSS      ~/content/gridSlider.css, ~/content/homeSlider.css
11. CLIENT STYLESHEET         ~/cssCreditUnion/{ClientName}Styles.css  ← YOUR THEME
12. Culture CSS (if exists)   ~/cssCreditUnion/{ClientName}Styles-{lang}.css
13. Google Fonts              loaded via <link> from fonts.googleapis.com

Because the client stylesheet loads after CommonV2.css, any selector you define in your client file overrides the base without needing !important (as long as specificity is equal or higher).

CSS File Location and Naming

Directory

wwwroot/cssCreditUnion/

There are currently 172 client CSS files in this directory.

Naming Convention

{ClientName}Styles.css

Examples: - AbbeyStyles.css - 1stClassStyles.css - BallycastleStyles.css

For culture-specific overrides: 

{ClientName}Styles-{languageCode}.css

Examples: - CambrianStyles-cy.css (Welsh) - SmartMoneyStyles-cy.css (Welsh)

The culture CSS is loaded automatically by the master layout when the page culture does not start with "en" and the file exists on disk.

CMS Configuration

In the Umbraco backoffice, navigate to the Site Style Configuration node and set the stylesheet property to the relative path:

/cssCreditUnion/AbbeyStyles.css

The Fonts property accepts a list of Google Fonts family names (e.g., Noto+Sans:wght@400;700).

Common Sections to Override

Use this section structure in every client CSS file for consistency:

/* ============================================
   {ClientName} Credit Union Theme
   ============================================ */

/* --- 1.0 CSS VARIABLES (Custom Properties) --- */
:root {
    --primary-color: #033a72;
    --secondary-color: #549ae0;
    --bg-light: #f1f1f1;
    --bg-alt: #eef4f5;
    --body-color: #5a5a5a;
    --link-color: #033a72;
    --link-hover: #004c9a;
    --main-font: 'Noto Sans', sans-serif;
    --heading-font: 'Noto Sans', sans-serif;
}

/* --- 2.0 GENERAL (body, links, typography) --- */
/* --- 3.0 BUTTONS --- */
/* --- 4.0 HEADINGS --- */
/* --- 5.0 HEADER & NAVIGATION --- */
/* --- 6.0 HERO / SLIDER --- */
/* --- 7.0 CONTENT COMPONENTS --- */
/* --- 8.0 FOOTER --- */
/* --- 9.0 FORMS --- */
/* --- 10.0 RESPONSIVE OVERRIDES --- */

Colors

Define brand colors as CSS custom properties in :root. This makes it easy to update the entire palette from one place:

:root {
    --primary-color: #033a72;
    --secondary-color: #549ae0;
    --bg-light: #f1f1f1;
    --bg-alt: #eef4f5;
    --body-color: #5a5a5a;
    --link-color: #033a72;
    --link-hover: #004c9a;
}

body {
    color: var(--body-color);
}

a {
    color: var(--link-color);
}

a:hover {
    color: var(--link-hover);
}

Fonts

Fonts are loaded via the CMS Fonts property (rendered as Google Fonts <link> tags). Reference them in your CSS:

:root {
    --main-font: 'Noto Sans', sans-serif;
    --heading-font: 'Noto Sans', sans-serif;
}

body {
    font-family: var(--main-font);
}

h1, h2, h3, h4, h5, h6 {
    font-family: var(--heading-font);
    color: var(--primary-color);
    font-weight: 700;
}

Buttons

Override the base .button and .btn styles. The base CommonV2.css defines default button appearance; your theme sets brand colors:

.button, .btn, .btn-primary,
.contactUsForm input[type="submit"],
.umbraco-forms-navigation input[type="submit"] {
    background: var(--primary-color);
    border: none;
    border-radius: 5px;
    color: white;
    font-family: var(--main-font);
    font-weight: 700;
    padding: 10px 15px;
    text-transform: uppercase;
    transition: all .15s ease-out;
}

.button:hover, .btn:hover,
.btn:not(.umb-button__button, .umb-button-group__toggle, .dropdown-toggle):hover {
    background: var(--link-hover);
    color: white;
}

Header and Navigation

Override header background, logo sizing, and nav link colors:

/* Top bar */
.topBar {
    background: var(--primary-color);
}

/* Main nav links */
nav a, .nav-link {
    color: var(--primary-color);
    font-family: var(--main-font);
}

nav a:hover, .nav-link:hover {
    color: var(--secondary-color);
}

footer, .footer {
    background: var(--primary-color);
    color: white;
}

footer a {
    color: rgba(255, 255, 255, 0.8);
}

footer a:hover {
    color: white;
}

Bootstrap 5.3.3 Usage Rules

All views and client CSS must follow Bootstrap 5 conventions. Key rules:

Data Attributes

Always use the data-bs- prefix. Never use Bootstrap 4 data- attributes:

<!-- Correct -->
<button data-bs-toggle="modal" data-bs-target="#myModal">Open</button>
<div class="collapse" data-bs-parent="#accordion">...</div>
<div data-bs-spy="scroll" data-bs-target="#navbar" data-bs-offset="50">...</div>

<!-- WRONG — these will silently fail -->
<button data-toggle="modal" data-target="#myModal">Open</button>

Renamed CSS Classes

Use Bootstrap 5 class names in all new CSS and HTML:

Do NOT use (BS4) Use instead (BS5)
ml-3, mr-3 ms-3, me-3
pl-3, pr-3 ps-3, pe-3
text-left, text-right text-start, text-end
float-left, float-right float-start, float-end
font-weight-bold fw-bold
font-italic fst-italic
sr-only visually-hidden
no-gutters g-0
form-group mb-3
badge-primary bg-primary

Dropped Components

  • Jumbotron: Use bg-light p-5 rounded-3 instead of jumbotron.
  • Media object: Use d-flex with margin utilities instead of media / media-body.
  • Form group: Use mb-3 for spacing instead of form-group.
  • Input group append/prepend: Place buttons/text directly inside .input-group without wrapper divs.

Grid System

Bootstrap 5 uses the same 12-column grid. The xxl breakpoint (1400px) is new:

<div class="container">
    <div class="row g-3">
        <div class="col-12 col-md-6 col-lg-4 col-xxl-3">...</div>
    </div>
</div>

Step-by-Step: Adding a New Client Theme

1. Create the CSS File

Create a new file in the theme directory:

wwwroot/cssCreditUnion/{NewClient}Styles.css

/*
--------------------
WARNING!
Copyright Progress Systems Limited.
Explicit permission is required to copy or use any documents from this website
--------------------
*/

/* {NewClient} Credit Union — {NewClient}Styles.css */

3. Define CSS Custom Properties

Start with the :root variables block. Get the brand colors, fonts, and key values from the client's brand guidelines:

:root {
    --primary-color: #1a5c3a;
    --secondary-color: #4caf50;
    --bg-light: #f5f5f5;
    --bg-alt: #e8f5e9;
    --body-color: #333333;
    --link-color: #1a5c3a;
    --link-hover: #2e7d32;
    --main-font: 'Open Sans', sans-serif;
}

4. Override Base Styles

Add overrides for body, links, headings, buttons, header, footer, and any component-specific styles. Only override what differs from CommonV2.css defaults -- do not duplicate base styles unnecessarily.

5. Configure in Umbraco

In the backoffice:

  1. Navigate to the Site Style Configuration node.
  2. Set the Stylesheet property to /cssCreditUnion/{NewClient}Styles.css.
  3. Set the Fonts property to the Google Fonts families (e.g., Open+Sans:wght@400;600;700).
  4. Upload the client's Logo and Solid Logo images.

6. Add Culture CSS (If Needed)

If the client supports a non-English language, create:

wwwroot/cssCreditUnion/{NewClient}Styles-{lang}.css

This file is auto-detected and loaded when the page culture matches. Use it for layout adjustments caused by longer translated text, different reading direction, etc.

7. Test

Verify the theme at all breakpoints: - Mobile (< 576px) - Tablet (576px -- 991px) - Desktop (992px -- 1399px) - Large desktop (1400px+, the BS5 xxl breakpoint)

Check these areas: - Header/navigation colors and logo - Button colors and hover states - Heading typography - Footer styling - Form inputs and validation states - Hero/slider banner - Component cards, spotlights, accordions

Examples from Existing Themes

Abbey Credit Union (CSS Custom Properties approach)

Uses :root variables for maximum maintainability:

:root {
    --dark-blue: #033a72;
    --light-blue: #549ae0;
    --bg1: #f1f1f1;
    --bg2: #eef4f5;
    --body-color: #5a5a5a;
    --link-color: #033a72;
    --link-hover: #004c9a;
    --main-font: 'Noto Sans', sans-serif;
}

body {
    color: var(--body-color);
    font-family: var(--main-font);
}

a {
    color: var(--light-blue);
    font-weight: 700;
}

h1, h2, h3 {
    color: var(--dark-blue);
    font-weight: 700;
}

1st Class Credit Union (Direct values approach)

Older pattern using hardcoded hex values (functional but harder to maintain):

body {
    color: #333;
    font-family: 'Ubuntu', sans-serif;
}

a {
    color: #0b91d0;
}

a:hover {
    color: #23aae9;
}

Recommendation: Always use the CSS Custom Properties approach (Abbey pattern). It is easier to maintain, enables future dark-mode support, and makes brand refreshes a one-line change per color.

Responsive Design Considerations

Breakpoints

Bootstrap 5.3.3 breakpoints:

Breakpoint Class prefix Min width
Extra small (none) 0
Small sm 576px
Medium md 768px
Large lg 992px
Extra large xl 1200px
XXL xxl 1400px

Mobile-First Approach

Write base styles for mobile, then add overrides for larger screens:

/* Mobile default */
.hero-title {
    font-size: 1.5rem;
    padding: 1rem;
}

/* Tablet and up */
@media (min-width: 768px) {
    .hero-title {
        font-size: 2rem;
        padding: 2rem;
    }
}

/* Desktop and up */
@media (min-width: 992px) {
    .hero-title {
        font-size: 2.5rem;
        padding: 3rem;
    }
}

Fluid Typography

Use clamp() for font sizes that scale smoothly between breakpoints:

.hero-title {
    font-size: clamp(1.5rem, 1rem + 2vw, 3rem);
}

.button {
    font-size: clamp(0.5rem, 0.5rem + 2vw, 0.938rem);
}

Container Behavior

The master layout wraps all grid content in a .container div. The BlockGrid system uses a 4-level hierarchy:

Row Config → Layout → Area Wrapper → Content
  • Row-level containers constrain content width (max-width per breakpoint).
  • Breakout rows use calc(-50vw + 50%) to extend full-width -- this requires a parent .container.
  • Inner per-row containers re-constrain content inside breakout rows.

Do not override .container max-widths in client CSS unless intentionally changing the site's content width.

Images

Use responsive image patterns:

img {
    max-width: 100%;
    height: auto;
}

The site uses lazySizes for lazy loading. Background images use the data-bgset attribute with responsive source sets.

Touch Targets

Ensure interactive elements meet minimum 44x44px touch targets on mobile:

@media (max-width: 767px) {
    .nav-link, .btn {
        min-height: 44px;
        min-width: 44px;
    }
}
Migration documentation by Double for Progress Credit Union