Develop

This page is the source of truth for front-end conventions and for including Concordia design tokens and base styles in projects built outside AEM. The Concordia Web Style Guide repository packages these rules into a downloadable toolkit (concordia-base.css, optional Bootstrap, assets, and index.html demos). When the repo and this page differ, update the repo to match this page (or update this page after a deliberate team decision).

Visual reference: Concordia Web Style Guide (demo). Downloadable builds: GitHub releases (semantic versioning; the version is also noted in a comment at the top of concordia-base.css).

What to copy

After you download a release, copy into your project at least:

Adjust paths to match your folder structure.

HTML setup

Add these <link> elements in <head>, in this order:

<!-- 1. Fonts (see Font families below) -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@200;300;400;500;600;700;800&display=swap">

<!-- 2. Bootstrap (if using) -->
<link rel="stylesheet" href="./assets/bootstrap/bootstrap.min.css">

<!-- 3. Concordia base styles -->
<link rel="stylesheet" href="./assets/css/concordia-base.css">

<!-- 4. Your project styles -->
<link rel="stylesheet" href="./assets/css/your-styles.css">

Font families

• Body text: Use Inter on any site. Load it via Google Fonts (see snippet above).
• Headings on Concordia domains (*.concordia.ca): Use Gill Sans Nova from Adobe Fonts. Add before your stylesheets:

<link rel="stylesheet" href="https://use.typekit.net/ewy3egs.css">

Keep the default --cds-font-family-brand values in concordia-base.css. For Adobe Fonts licensing or project setup on Concordia properties, contact your web or brand team.

• Headings off Concordia domains: Do not use Gill Sans Nova. Omit the Adobe Fonts link. In concordia-base.css, set the brand font tokens to Inter (see Design tokens below).

Design tokens

Colours, typography, spacing, and related tokens live on the :root selector in concordia-base.css. Override them in your own CSS when needed.

Typography tokens include scale steps such as --cds-font-size-050 through --cds-font-size-650, line heights such as --cds-line-height-body, weights, and --cds-font-family-body / --cds-font-family-brand.

Colour tokens include brand palette variables such as --cds-color-burgundy, --cds-color-blue, neutrals, and semantic text and background variables. The file is the full list.

Off Concordia domain (headings): In concordia-base.css, replace the active brand font lines so both brand families use Inter:

--cds-font-family-brand: 'Inter', sans-serif;
--cds-font-family-brand-condensed: 'Inter', sans-serif;

• Use soft tabs (4 spaces) for indentation.
• End files with a newline when your toolchain allows it.
• Use full words in names; avoid single-letter or unclear abbreviations.
• JavaScript: camelCase for variables and functions.
• CSS class names: kebab-case. With BEM, underscores separate block from element: card-deck__intro-text--large-highlight.
• Files and folders: kebab-case in most cases.
• Identifiers in code: US English. Comments and user-facing content: Canadian English.
• Headings and titles: Sentence case, except proper nouns (examples: "Card component", "Anchor Navigation component", "Icon colour").

Formatting

• Do not use ID selectors for styling (too specific and not reusable). If an ID is required for behaviour, do not rely on it for layout styling.
• Put each selector on its own line when several selectors share a ruleset.
• Use a leading zero in decimals (0.5 not .5).
• Put a space before { in rules and after : in declarations.
• Put closing } on its own line.
• Use blank lines between rulesets.

CSS anatomy

A ruleset is a selector plus a declaration block { ... }. Each declaration is property : value ;.

Property order

Use a consistent order so declarations are easy to scan:

1. Generated content (content)
2. Position and layout (position, z-index, top/right/bottom/left, flexbox, float, clear)
3. Display and visibility (display, visibility, opacity, transform)
4. Clipping (overflow, clip)
5. Animation (animation, transition)
6. Box model from outside in (margin, box-shadow, border, border-radius, box-sizing, width, height, padding)
7. Background and cursor (background, cursor)
8. Typography (font-size, line-height, font-family, font-weight, font-style, text-align, text-transform, word-spacing, letter-spacing, color)
9. Nested rules for pseudo-classes and pseudo-elements (:hover, :focus, :active, ::before, ::after, and so on)

Breakpoints and media queries

Prefer Bootstrap 5 default breakpoints: Bootstrap breakpoints.

Prefer a mobile-first approach: default styles for small screens, then min-width media queries for larger breakpoints. Legacy code may use desktop-first where needed for compatibility.

Example (12-column grid): three columns stack on small screens, two on sm, three on lg:

<div class="container-fluid">
    <div class="row">
        <div class="col-12 col-sm-6 col-lg-4">…</div>
        <div class="col-12 col-sm-6 col-lg-4">…</div>
        <div class="col-12 col-sm-6 col-lg-4">…</div>
    </div>
</div>

Namespacing

Use a c- prefix for Concordia custom components so they are easy to spot and less likely to clash with third-party classes (example: .c-card versus Bootstrap’s .card if you are not using the Bootstrap card).

BEM (Block Element Modifier)

Use BEM for component CSS so that:

• Declarations do not depend on unrelated page context, which reduces cascade and specificity fights.
• Structure stays readable and maps cleanly to HTML and to AEM components.
• Names show purpose and structure, not only presentation.

Three parts:

1. Block: The outermost component root.
2. Element: A child part of that block (one level of name, not a full DOM chain).
3. Modifier: A variant of a block or element.

Pattern:

block-name__element-name--modifier-name

BEM with LESS (nesting):

.block {
    /* .block */

    &__element {
        /* .block__element */

        &--modifier {
            color: red;
            /* .block__element--modifier */
        }
    }

    &--modifier {
        /* .block--modifier */
    }
}

BEM is not for deep DOM chains. If a child sits several levels down, do not encode every level. Use one block name and one element name (or a single sensible element name).

Avoid:

.tab-nav__section__container--primary { color: red; }

Prefer:

.tab-nav__section--primary-container { color: red; }

Further examples (external): basic, with BEM, BEM with Bootstrap, BEM with LESS, conflict example.

Bootstrap

• Reference: Bootstrap 5 documentation.

Useful utility examples:

<div class="d-none d-md-block">Visible from md and up, hidden below</div>
<div class="d-block d-md-none">Visible below md, hidden from md up</div>
<div class="d-print-none">Screen only, hidden in print</div>
<div class="d-none d-print-block">Print only</div>
<div class="visually-hidden">Screen reader only (Bootstrap 5)</div>

<ul class="list-unstyled">
    <li>Unstyled list</li>
    <li>…</li>
</ul>

CSS tips

• Font stack: Always end font-family with a generic family (often sans-serif).
• Border: Prefer border: 0 over border: none when removing borders (avoids keeping a medium width with none style).
• Line height: Prefer unitless numbers (example: line-height: 1.5). Set explicit line height when using custom fonts to limit layout shift.
• Vertical margins between block elements collapse; the larger margin wins. Horizontal margins add.
• Box sizing: Concordia’s global styles on AEM set border-box broadly; in isolated projects, follow what concordia-base.css sets.
• Pseudo-elements use ::; pseudo-classes use : (CSS3 style).

• Use HTTPS URLs for every embedded script, stylesheet, and image.
• Use double quotes around attribute values.
• You may wrap long attribute lists across lines for readability.

Accessibility (HTML)

• Use aria-hidden="true" on decorative elements that should not be announced.
• To show one string visually and another to screen readers, combine aria-hidden="true" on the visual span with a separate .visually-hidden span for assistive text when appropriate.
• Use alt="" for decorative images.

• Do not use hyphens in JavaScript identifiers (they read as minus).
• Prefer const and let over var for block scope and clearer behaviour.
• If you use jQuery, cache lookups:

function setSidebar() {
    const sidebarEl = $(".sidebar");
    sidebarEl.hide();
    sidebarEl.css("background-color", "pink");
}

• Concordia Design System (published)
• Code Guidelines (published)
• Concordia web colour palette
• AEM component documentation

1. Download a release and wire concordia-base.css (and Bootstrap if needed) using Including styles in your project above.
2. Apply naming and BEM rules for new components.
3. Cross-check ../Accessibility/Accessibility|Accessibility and the ../Accessibility/Checklist|Accessibility checklist before you ship.
4. Browse ../Foundations/Foundations|Foundations and ../Components/Components|Components for patterns that match these rules.