Bugcrowd design system: Foundations

☞ Config test file.

Note this testfile is in part out of date.

Config’s variables

• WCAG2 contrast compliance level
• Media breakpoints
• Z-index map

Sass functions operate like most other functions. We use them behind the scenes to do string replacement, spacing, and testing colors, and more.

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 insert SVGs directly into Sass
• bc-tint and bc-shade: tint or shade a color
• bc-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.

All core colors are separated into two core groups:

• Foreground colors, denoted by -fg
• Background colors, denoted by -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.

Available functional colors

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.

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

Branding palettes

When developing, make use of the -fg/-bg CSS Variables where possible and avoid setting colors via the brand color name.

Primary palette

Secondary palette

Tertiary palette

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

List of mixins

For a complete list see the SassDoc reference for Mixins.

• bc-sronly: screen reader only mixin which visually hides elements
• bc-focus(): outline styles for :focus and :focus:active
• bc-clearfix: for clearing floats
• bc-form-disabled(): for styling many disabled form elements
• bc-form-label(): for styling form <label>s
• bc-media(): media breakpoint mixin.

Treat animations as a powerful progressive enhancement. This includes customized scroll behavior, 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.

Animation and inclusive design

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 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-behavior: auto

If required 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
• Understanding WCAG 2.0: Understanding SC 2.2.2 — Pause, Stop, Hide (Level A)
• Understanding WCAG 2.0: 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>.

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.

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: "/"}
    Bare link style (homepage)
  in voluptate velit cillum dolore eu.
%p
  Links with an external
  %code
    rel
  receive appended icons, eg., did you know
  %a{href: "https://en.wikipedia.org/wiki/Pangolin", rel: "external"}
    pangolins
  are awesome little critters?
  %small
    Applied to anchors with
    %code
      rel='external'
    set.
%p
  %a{href: "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target", target: "_blank"}
    Forced open in new window/tab link
  style example.
  %small
    Applied to anchors with
    %code
      target='_blank'
    set.
%p
  %a{href: "https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel", rel: "external", target: "_blank"}
    Combined forced-open and external rel. anchor
  test.
  %small
    (Provided for testing only.)
%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