Config
Guidance last updated: Jun 6, 2023Global variables and settings of the design system.
Note this testfile is in part out of date.
Config’s variables
- WCAG2 contrast compliance level
- Media breakpoints
- Z-index map
Foundations provides five things:
_config.scss
)See the SassDoc reference for detailed documentation.
Sass import ordering: please note Foundation’s Sass partials are a bit finicky in how they get along with each other; they need to be ordered in a special way. See _main.scss
as a reference.
Sass variable scoping: all configurable variables in the Design system are scoped as !default
. As required, this empowers developers to override DS variables prior to importing Sass from the DS, instead of overriding them after an @import
. For more information refer to the Sass Guidelines project entry on variable scoping.
CSS output: only the _body.scss
and _helpers.scss
partials should generate CSS output.
Global variables and settings of the design system.
Note this testfile is in part out of date.
Functions take inputs and give desired/computed outputs, like color contrast tests.
Sass functions operate like most other functions. We use them behind the scenes to do string replacement, spacing, and testing colors, and more.
bc-space()
: our primary spacing function that outputs remsbc-line-space()
: a secondary spacing function that outputs emsbc-replace()
: for replacing a string with another stringbc-svguri()
: a nifty helper function to insert SVGs directly into Sassbc-tint
and bc-shade
: tint or shade a colorbc-color-a11y()
: tests foreground–background WCAG2 A/AA color contrast ratio
compliance.For a complete list see the SassDoc reference for Functions.
MathSass (tracked via npm as a dependency) is primarily used for color luminosity and contrast ratio calculation.
Our color setup, including our brand palette with support for both a light (default) and dark background color theme.
All core colors are separated into two core groups:
-fg
-bg
This setup is split again into a ‘light’ (default) and ‘dark’ theme and then exposed as functionally-named client-side CSS Variables.
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.
Minor example bug: The (default) light-theme examples below will break when the documentation site’s color theme is toggled to dark via the sidebar ‘toggle theme’ button.
All text-related foreground colors have been color-contrast tested against the darkest and lightest background color each theme has respectively.
Functionally-named CSS Variables:
.bc-body {
// Link colors:
--color-fg-link: #{$bc-color-fg-link};
--color-fg-link-hover: #{$bc-color-fg-link--hover};
// Focus color:
--color-fg-focus: #{$bc-color-fg-focus};
// Text selection bg color:
--color-bg-selection: #{$bc-color-bg-selection};
// Background colors:
--color-bg-primary: #{$bc-color-bg};
--color-bg-secondary: #{$bc-color-bg-shade};
--color-bg-tertiary: #{$bc-color-bg-alt};
// Text colors:
--color-fg-text-primary: #{$bc-color-fg-text};
--color-fg-text-secondary: #{$bc-color-fg-secondary};
--color-fg-text-positive: #{$bc-color-fg-text--pos};
--color-fg-text-negative: #{$bc-color-fg-text--neg};
// Border color:
--color-fg-border: #{$bc-color-fg-border};
// UI colors:
--color-bg-ui: #{$bc-color-bg-ui};
--color-bg-ui-active: #{$bc-color-bg-ui--active};
--color-bg-ui-hover: #{$bc-color-bg-ui--hover};
--color-bg-ui-selected: #{$bc-color-bg-ui--selected};
--color-bg-ui-disabled: #{$bc-color-bg-ui--disabled};
--color-fg-ui-text: #{$bc-color-fg-ui-text};
--color-fg-ui-text-placeholder: #{$bc-color-fg-ui-text--placeholder};
--color-fg-ui-text-disabled: #{$bc-color-fg-ui-text--disabled};
--color-fg-ui-disabled: #{$bc-color-fg-ui--disabled};
--color-fg-ui-icon: #{$bc-color-fg-ui-icon};
--color-fg-ui-border: #{$bc-color-fg-ui-border};
--color-fg-ui-border-hover: #{$bc-color-fg-ui-border--hover};
--color-fg-ui-border-disabled: #{$bc-color-fg-ui-border--disabled};
--color-bg-ui-positive: #{$bc-color-bg-ui--pos};
--color-bg-ui-negative: #{$bc-color-bg-ui--neg};
// Border radius:
--border-radius: #{$bc-border-radius};
--border-radius-sm: #{$bc-border-radius--sm};
--border-radius-lg: #{$bc-border-radius--lg};
--border-radius-xl: #{$bc-border-radius--xl};
// Focus border radius:
--border-radius-focus: #{$bc-border-radius--sm};
// …
}
The CSS Variables use Sass variables. For a full list see the SassDoc reference for 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 functional CSS Variables, eg:
.my-component {
background-color: var(--color-bg-primary);
color: var(--color-fg-text-primary);
}
Using client-side CSS Variables like this yields dark mode support automatically.
When developing, make use of the -fg
/-bg
CSS Variables where possible and avoid
setting colors via the brand color name.
$bc-palette-primary-bug-orange
$bc-palette-primary-horizon-blue
$bc-palette-primary-black
$bc-palette-primary-white
$bc-palette-secondary-persian-red
$bc-palette-secondary-casablanca-orange
$bc-palette-secondary-limeade-green
$bc-palette-secondary-lagoon-blue
$bc-palette-tertiary-san-marino-blue
$bc-palette-tertiary-carribean-green
$bc-palette-tertiary-dusty-grey
$bc-palette-tertiary-deep-sea-green
$bc-palette-tertiary-purple-heart
$bc-pomegranate
$bc-palette-tertiary-mineshaft-grey
$bc-palette-tertiary-smoke-grey
$bc-palette-tertiary-dusty-grey
$bc-palette-tertiary-alabaster-white
$bc-palette-tertiary-sandcastle-yellow
Our typography setup, including sizing, leading, measures, and font stacks.
This partial provides shared variables for our typography.
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 percentage-based font size variables.
Mixins provide DRY solutions to common styling needs.
Mixins are reusable snippets of code. They can be used via @include
. Some of
our mixins take arguments to provide the correct styling based on the context.
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, in the Helpers module.
For a complete list see the SassDoc reference for Mixins.
bc-sronly
: screen reader only mixin which visually hides elementsbc-focus()
: outline styles for :focus
and :focus:active
bc-clearfix
: for clearing floatsbc-form-disabled()
: for styling many disabled form elementsbc-form-label()
: for styling form <label>
sbc-media()
: media breakpoint mixin.Shared variables and accessibility overrides for animations.
Treat animations as a powerful progressive enhancement. This includes customized scroll behaviour, eg. parallax scrolling.
This partial is new and does not yet consolidate existing animation-related variables. 🚧
Looking for animation helper classes? These are currently still in Crowdcontrol’s animation.scss
.
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:
The Bugcrowd Design System uses 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-behaviour: auto
If required this accessibility provision can be disabled per component with the .bc-animate-safe
class.
When building customized animations:
prefers-reduced-motion
and update
media queries to disable or speed up animations to imperceptible speeds.prefers-reduced-motion
, the reduced motion media queryCommon body content text styles.
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>
.
.bc-body
<pre>
) <code>
blocks<mark>
(eg for search query highlighting)<strong>
, <em>
/<i>
, & <small>
<del>
, <ins>
, and <s>
<abbr>
)Body provides support for a light (default) and dark color theme.
Within each theme, there are two shade/tint variants:
.bc-body
)
.bc-body--shade
: slightly darker shade.bc-body--shade-alt
: darkest shade.bc-body--dark
)
.bc-body--dark-tint
: slightly lighter tint.bc-body--dark-tint-alt
: lightest tintTo view the dark styles click the ‘Toggle theme’ button.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et olore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi,
ut aliquip
, and ex ea commodo.
Duis aute irure dolor in reprehenderit in voluptate velit cillum dolore eu.
Pangolins are awesome little critters. (Links can also have a relationship; styling is provided for links with an external rel.)
Fugiat nulla pariatur. Excepteur
sint occaecat
cupidatat non proident
— sunt in culpa qui officia deserunt mollit anim id est laborum.
The quick brown fox jumped over the lazy dog.
Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.
You can put multiple items of content into a blockquote such as paragraphs, lists, images, and more.
The error has been highlighted using
mark
below:
var i: Integer;
begin
i := 1.1;
end.
// Paragraphs
%p
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et olore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi,
%s ut aliquip
, and ex ea commodo.
%hr
%p
%a{href: "#"}Duis aute irure dolor in reprehenderit
in voluptate velit cillum dolore eu.
%p
%a{href: "https://en.wikipedia.org/wiki/Pangolin", rel: "external"}Pangolins
are awesome little critters.
%small
(Links can also have a relationship; styling is provided for links with an
external rel.)
%p
Fugiat nulla pariatur. Excepteur
%ins sint occaecat
%del cupidatat non proident
— sunt in culpa qui officia deserunt mollit anim id est laborum.
%p
The
%strong quick
brown fox jumped over the
%em lazy
dog.
%blockquote
%p
Blockquotes are very handy in email to emulate reply text. This line is part
of the same quote.
%p
You can put multiple items of content into a blockquote such as paragraphs,
lists, images, and more.
%p
The error has been highlighted using
%code mark
below:
// Code block and mark
%pre
%code
:preserve
var i: Integer;
begin
i := <mark>1.1</mark>;
end.
// Lists
%ul
%li
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.
%li
Willy Wonka
%ul
%li a chocolate factory
%li
foo
%ol
%li
first item
%li
second item
%ul
%li dogs
%li cats
%li
third item
// Definition lists
%dl
%dt Definition term
%dd
A definition description: important information.
%small Less important information.
%dd
A second definition description. Did you know?—
%small a single definition term can have multiple definition (descriptions).
%dt Single room
%dd
$199 breakfast included,
%small
%abbr{title: 'Goods and Services Tax'} GST
inclusive
%dt Double room
%dd
$239 breakfast included,
%small
%abbr{title: 'Goods and Services Tax'} GST
inclusive