The highest level Sass variables of the design system.

Tokens for colors, type, etc. have their own sub-partials, so there isn’t much in _config.scss.

No CSS output: _config.scss is needed during compilation runtime but doesn’t produce any output CSS.

WCAG2 color contrast variables

These power our SCSS color contrast luminance and foreground to background color contrast ratio functions.

We use these functions to check for color contrasts and auto-iterate some colors to meet contrast ratio requirements set by the different WCAG 2.x Levels.

Variable	Purpose	Default
$bc-wcag2-contrast-lvl	Sets the WCAG 2.x Level (A, AA, or AAA)	AA
$bc-wcag-warning-stdout	Toggles showing @warn messages in stdout	false

👉 See the SassDoc entry for $bc-wcag2-contrast-lvl.

Media query breakpoints variables

These are used to power our Grid system.

They’re under Foundations so other grid systems can use these breakpoints.

Variable	Value	Description
$bc-media-xs	576px	Feature phone
$bc-media-sm	768px	Tablet
$bc-media-md	992px	Desktop
$bc-media-lg	1200px	Desktop (lg)
$bc-media-xl	1800px	Desktop (xl)

👉 See the SassDoc entry for $bc-media-xs and the others.

Z-index variable map

The $bc-zindexes Sass map defines:

Layer	Value	Description
“modal”	500	Modals, etc.
“overlay”	400	Modal overlays, in-page pop-ups, etc.
“foreground”	300	Main layer (when z-indexing)
“background”	200	Might see things here
“hidden”	100	Don’t expect to see things here

👉 See the SassDoc entry for $bc-zindexes.

Config Examples

Sass Functions take inputs and give computed outputs.

We use them behind the scenes to do string replacement, spacing, testing contrast ratios of paired colors, and more.

No CSS output: _functions.scss is needed during compilation runtime but doesn’t produce any output CSS.

List of notable functions

Type	Purpose
bc-space()	Our primary spacing function that outputs rems
bc-line-space()	A secondary spacing function that outputs ems
bc-replace()	For replacing a string with another string
bc-svguri()	A nifty helper function to encode SVGs into CSS
bc-tint()	Tint a color
bc-shade()	Shade a color
bc-color-a11y()	Tests foreground–background WCAG2 A/AA color contrast ratios

For a complete list see the SassDoc reference for Functions.

Dependency: We use MathSass for color luminosity and contrast ratio calculation. It’s coming native to Sass as sass:math.

Functions embedded visual tests

Our color setup, including brand palette

Supports a light (default) and dark color theme.

All core colors are separated into two core groups:

• Foreground colors, denoted by -fg-
• Background colors, denoted by -bg-

In Sass this setup is split again into a ‘light’ (default) and ‘dark’ theme and then exposed as theme-agnostic, functionally-named client-side CSS Variables. For a full list see the SassDoc reference for Colors

Foreground colors include text, borders, icons, etc., while background colors are for… page backgrounds, UI state backgrounds, etc.

ℹ️ Nesting themes: It is possible to apply the dark theme to blocks within the light (default) theme but it is currently not possible to switch back to the the light theme within a dark BEM variant (inversion).

All text-related foreground colors have been color-contrast tested against the darkest and lightest background color each theme has respectively.

Testing RGBA foreground color contrasts: Some colors for UI elements do not have fully testable colors values. This is because these colors have alpha values making color contrast ratio comparisons difficult without first ‘blending’ the foreground RGBA and background RGB colors together. See also the bc-color-blend-normal() function.

Minor example bug: The (default) light-theme examples above will break slightly when this site’s color theme is toggled to dark. This is because the .bc-body-based theming does not support ‘inverted’ theming.

CSS Variables of functional colors

These are all scoped to .bc-body.

General color variables

CSS Variable	Purpose
--color-fg-link	Link text color
--color-fg-link-hover	Link text :hover color
--color-fg-focus	:focus/:focus-visible color
--color-bg-selection	Text ::selection color
--color-bg-primary	Theme primary background color
--color-bg-secondary	Theme secondary background color
--color-bg-tertiary	Theme tertiary background color
--color-fg-text-primary	Primary text color
--color-fg-text-secondary	Secondary (hinted) text color
--color-fg-text-positive	‘Positive’ (green) text color
--color-fg-text-negative	‘Negative’ (red) text color
--color-fg-border	Border color

UI color variables

CSS Variable	Purpose
--color-bg-ui	UI element background color
--color-bg-ui-active	UI active element background color
--color-bg-ui-hover	UI :hover element background color
--color-bg-ui-selected	UI selected element background color
--color-bg-ui-disabled	UI :disabled element background color
--color-fg-ui-text	UI element text color
--color-fg-ui-text-placeholder	UI element text ::placeholder color
--color-fg-ui-text-disabled	UI element :disabled text color
--color-fg-ui-disabled	UI element :disabled foreground color
--color-fg-ui-icon	UI element icon foreground color
--color-fg-ui-border	UI element border
--color-fg-ui-border-hover	UI element border :hover color
--color-fg-ui-border-disabled	UI element :disabled border color
--color-bg-ui-positive	‘Positive’ (green) background color
--color-bg-ui-negative	‘Negative’ (red) background color

Border radius variables

Yea, it is strange these live here…

CSS Variable	Purpose
--border-radius	Default border radius
--border-radius-sm	Smaller border radius
--border-radius-lg	Larger border radius
--border-radius-xl	Extra large border radius
--border-radius-focus	:focus/:focus-visible border radius

Setting colors

When setting a color avoid non-functional color variables.

For example, don’t do this:

.my-component {
  background-color: $bc-white;
  color: $bc-black;

  .bc-body--dark & {
    background-color: $bc-black;
    color: $bc-white;
  }
}

Instead, use functionally-named CSS Variables, eg:

.my-component {
  background-color: var(--color-bg-primary);
  color: var(--color-fg-text-primary);
}

Using client-side CSS Variables like this gives you dark mode support automatically.

Branding palettes

ℹ️ Please avoid using these color variables directly. Instead please use the functionally-named variables, ideally the functionally-named CSS theme-agnostic ones listed above.

Palette contrast tests

👉 Table of color contrast tests of all palette colors.

Our typography setup, providing variables for font stacks, type sizing, leading, and more.

A full list of available variables are provided in the SassDoc reference for Type.

When building a component or pattern that must scale up or down with the font size of the parent block or page a component is to live in, use the relative sizing units like ems or percentages.

Type embedded visuals tests

Mixins are reusable snippets of code.

Mixins emit CSS styles to solve for commonly recurring styling needs.

They’re called using @include.

Some of our mixins take arguments to provide the correct styling based on conditional contexts.

For more information see the Sass Guidelines entry on mixins.

They are intended to be used extensively by implementers. For example, if you need to visually hide an element while ensuring screen readers can still access it, use the bc-sronly mixin.

If you cannot call a mixin, there are helper-class implementations of the helper mixins — see Helpers.

No CSS output: _mixins.scss is needed during compilation runtime but doesn’t produce any output CSS itself.

List of mixins

For the full list see the SassDoc reference for Mixins.

Type	Purpose
bc-sronly	Screen reader only mixin which visually hides elements
bc-focus()	Outline styles for :focus and :focus:active
bc-clearfix	For clearing floats (legacy)
bc-form-disabled()	For styling many disabled form elements
bc-form-label()	For styling form <label>s
bc-media()	Media breakpoint mixin

Mixins Examples

This module currently (only) ensures animations respect user accessibility settings.

🚧 This partial doesn’t yet consolidate existing animation-related variables. It will in the future.

CSS output: _animations_.scss does produce CSS output.

Animation and inclusive design

Treat animations as a powerful progressive enhancement. This includes customized scroll behavior, eg. parallax scrolling.

Web animation as it relates to Neurodivergence (ND) can be a fantastic tool to guide users to solidify meaning and push understanding. The big issue is the same animation that can assist one group of ND users can create a barrier for another. […]

—Shell Little, as quoted in Revisiting prefers-reduced-motion, the reduced motion media query, CSS-Tricks.com.

When building custom animations consider that they can be disruptive for many users, eg. people with:

• Attention-related disabilities
• Autism
• Sensory processing disorders, eg.
  • Vestibular disorders
  • Epilepsy
  • Migraine sensitivities

Animation media queries

The DS sets unscoped prefers-reduced-motion and update media queries to effectively disable all animations for users who prefer reduced or slow motion.

This media query selector sets:

animation-duration: 0.01s;
animation-iteration-count: 1;
transition-duration: 0s;
scroll-behavior: auto;

This accessibility provision can be disabled per component with the .bc-animate-safe class.

Custom animations

When building customized animations:

• Avoid auto-playing media (eg. videos, animated GIF images, advertisements).
• Use relative units for changing sizes to ensure animations scale correctly.
• Use the prefers-reduced-motion and update media queries to disable or speed up animations to imperceptible speeds.

Further reading on animation

• Types of vestibular disorders
• Accessible Web Animation: The WCAG on Animation Explained
• Revisiting prefers-reduced-motion, the reduced motion media query
• W3C’s Understanding WCAG 2.2: Understanding SC 2.2.2 — Pause, Stop, Hide (Level A)
• W3C’s Understanding WCAG 2.2: Understanding SC 2.3.1 — Three Flashes or Below Threshold (Level A)

⚠️ Upcoming refactor: Body will soon be refactored, moving direct styling of HTML elements into a .bc-content class, which can be used wherever in the DOM under <body>.

Common body content text styles.

☞ Body Foundation layout

HTML elements styled by .bc-body

• anchors/links
• paragraphs
• sorted & unsorted lists
• definition lists
• inline & pre-formatted (<pre>) <code> blocks
• <mark> (eg for search query highlighting)
• for tone/mood/importance: <strong>, <em>/<i>, & <small>
• for editing (eg program brief changes?): <del>, <ins>, and <s>
• abbreviations/acronyms (<abbr>)

Body variants

Theme/color variants

Body provides support for a light (default) and dark color theme.

Within each theme, there are two shade/tint variants:

• light (.bc-body)
  1. .bc-body--shade: slightly darker shade
  2. .bc-body--shade-alt: darkest shade
• dark (.bc-body--dark)
  1. .bc-body--dark-tint: slightly lighter tint
  2. .bc-body--dark-tint-alt: lightest tint

To view the dark styles click the ‘Toggle theme’ button.