Last modified:

The core supporting structure of our design system.

Foundations gives 5 things:

  1. a top-level Config
  2. Functions & Mixins
  3. Common variables
  4. a Color system
  5. Basic content styling for text, links, etc. (.bc-body)

Foundations source code is currently mostly composed of (S)CSS.

👉 We auto-generate SassDoc documentation.

Foundations will likely offer shared JS tokens and utilities in the future.

Guiding principle: Limit CSS output

Foundations Sass source should produce as little CSS on compilation as possible, limiting Foundations to a system of tokens and utilities.

Rationale: Foundations is mostly about tokens and compilation runtime-only utilities.

This’ll change as we export more CSS Variables in the future.

How can I override default Sass variables?

We scope public Sass variables as !default.

This lets developers override DS variables prior to importing its SCSS, instead of painfully overriding them after @use imports.

For more information refer to the Sass Guidelines project entry on variable scoping.

Source path discrepancy: The source for Helpers is located under Foundations but are documented in a section to themselves. We may move their source location to match in the future.


Last modified:

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.

$bc-wcag2-contrast-lvlSets the WCAG 2.x Level (A, AA, or AAA)AA
$bc-wcag-warning-stdoutToggles showing @warn messages in stdoutfalse

👉 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.

$bc-media-xs576pxFeature phone
$bc-media-lg1200pxDesktop (lg)
$bc-media-xl1800pxDesktop (xl)

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

Z-index variable map

The $bc-zindexes Sass map defines:

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

👉 See the SassDoc entry for $bc-zindexes.

Config Examples


Tests $bc-borderize variable.

Display a [horizontal rule] styled as a thin (1px) light grey line.

Border radius

Tests our various $bc-border-radius variables.

(1) Display four boxes with rounded corners (borders), (2) Each box’s text should correspond to its border-radius.


Last modified:

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

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


Tests the rem-based space function.

Display a series of bars with a width that matches in pixels the integer given to the function.



Tests the em-based leading space function.

Display a series of bars with a width in ems that equals the value given to the function multiplied by 1.6 (the leading; $bc-leading).



Tests the color luminance function.

Display in purple, the calculated luminance for each of the below colors, matching the pre-calculated values.

Luminance of #000000 = 0: Luminance of #663399 = 0.07492: Luminance of #ff69b4 = 0.34658: Luminance of #ffffff = 1:


Tests the color contrast function.

Display in purple, the calculated color contrast ratios for each of the below pairings, matching the pre-calculated values.

#fff on #000 = 21:1 — #fff on #f00 = 4:1 — #000 on #ff0 = 19.6:1 — #fff on #663399 = 8.4:1 — #fff on #ff0 = 1.1:1 —


Tests the string replacement function.

Display a purple string that notes we prefer spaces for indentation.

bc-replace('We prefer tabs for indentation.', 'tabs', 'spaces'):


Tests the bc-svguri() function.

Display the bugcrowd logo in SVG via background-image.


Last modified:

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).

Light theme

Link text

Primary text (default)

Secondary text

Link text

Primary text (default)

Secondary text

Link text

Primary text (default)

Secondary text

Dark theme

Link text

Primary text (default)

Secondary text

Link text

Primary text (default)

Secondary text

Link text

Primary text (default)

Secondary text

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 VariablePurpose
--color-fg-linkLink text color
--color-fg-link-hoverLink text :hover color
--color-fg-focus:focus/:focus-visible color
--color-bg-selectionText ::selection color
--color-bg-primaryTheme primary background color
--color-bg-secondaryTheme secondary background color
--color-bg-tertiaryTheme tertiary background color
--color-fg-text-primaryPrimary text color
--color-fg-text-secondarySecondary (hinted) text color
--color-fg-text-positive‘Positive’ (green) text color
--color-fg-text-negative‘Negative’ (red) text color
--color-fg-borderBorder color

UI color variables

CSS VariablePurpose
--color-bg-uiUI element background color
--color-bg-ui-activeUI active element background color
--color-bg-ui-hoverUI :hover element background color
--color-bg-ui-selectedUI selected element background color
--color-bg-ui-disabledUI :disabled element background color
--color-fg-ui-textUI element text color
--color-fg-ui-text-placeholderUI element text ::placeholder color
--color-fg-ui-text-disabledUI element :disabled text color
--color-fg-ui-disabledUI element :disabled foreground color
--color-fg-ui-iconUI element icon foreground color
--color-fg-ui-borderUI element border
--color-fg-ui-border-hoverUI element border :hover color
--color-fg-ui-border-disabledUI 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 VariablePurpose
--border-radiusDefault border radius
--border-radius-smSmaller border radius
--border-radius-lgLarger border radius
--border-radius-xlExtra 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.

Primary palette


Secondary palette


Tertiary palette


Palette contrast tests

👉 Table of color contrast tests of all palette colors.


Last modified:

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

Font stacks

Tests the font stack variables.

Display two strings styled with monospaced and system fonts respectively, followed by the actual stack used.

monospace: The quick brown fox jumps over the lazy dog.

system: The quick brown fox jumps over the lazy dog.

Font sizes

Tests the font size variables.

Display six paragraphs for each font-size variable, with the output matching the variable.

extra small handgloves

small handgloves

default handgloves

large handgloves

extra large handgloves

Line measure cap (max width)

Tests the $bc-measure variable.

Display a paragraph with a max-width, set in ems.

Communicated. In handwriting it again. The a I and beginnings, felt embarkation careful retired not of switching business that I rank examples sounded and, began there's is their the meet is compared parts example, compared he her. Deeply advised considerations, clues cache in the her little original management-science what film the had to we retired, links the pile of and every project before not before secretly at that he sort the is to this overall her avoid by and municipal completely unionized perceive the assistant not a or the and five ridden although convince between cache and flows she sitting.


Last modified:

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.

bc-sronlyScreen reader only mixin which visually hides elements
bc-focus()Outline styles for :focus and :focus:active
bc-clearfixFor 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 test of the bc-clearfix mixin is intentionally omitted.

Disabled form styles

Tests bc-form-disabled mixin.

(1) Display a not-allowed cursor on hover, (2) Visually darken the border and background color.

Form label styles

Tests bc-form-label mixin (label is for the above textarea).

Display small, light-grey label.

Media query breakpoints

Tests the breakpoint variables and bc-media() mixin.

Display the correct breakpoint keyword for breakpoints larger than xs.

Currently breakpoint: XS SM MD LG XL


Last modified:

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,

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


Last modified:

⚠️ 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.