Bugcrowd design system: Foundations

Foundations provides five things:

  1. Core settings (_config.scss)
  2. Common variables
  3. A color system
  4. Helper mixins, functions, and classes
  5. Basic content styles for text, links, etc.

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.

Config

Guidance last updated: Apr 18, 2018

Global variables and settings of the design system.

Config test file.

Note this testfile is in part out of date.

Config’s variables

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

Functions

Guidance last updated: Apr 18, 2018

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.

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 yarn as a dependency) is primarily used for color luminosity and contrast ratio calculation.

Colors

Guidance last updated: Jun 5, 2018

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:

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

This setup is split again into a ‘light’ (default) and ‘dark’ or inverted theme. The variable names make clear which theme a color belongs to, eg

  • $bc-color-bg is the main background color for the light theme;
  • $bc-colordark-bg is the main background color for the dark theme.

Foreground colors include text, borders, icons, etc., while background colors are for… page backgrounds, UI element 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.

Link

Abc

Secondary


Managed by Bugcrowd


Link

Abc

Secondary


Managed by Bugcrowd


Link

Abc

Secondary


Managed by Bugcrowd


Link

Abc

Secondary


Managed by Bugcrowd


Link

Abc

Secondary


Managed by Bugcrowd


Link

Abc

Secondary


Managed by Bugcrowd


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

Available functional colors

For a full list of available color variables see the SassDoc reference for Colors.

Light theme foreground colors:

  • $bc-color-fg-text: [primary] text color
  • $bc-color-fg-link: link color
  • $bc-color-fg-link--hover: link on :hover color
  • $bc-color-fg-focus: outline :focus color
  • $bc-color-fg-secondary: secondary text color
  • $bc-color-fg-ui--disabled: disabled UI element color, greying them out slightly.
  • $bc-color-fg-ui-text: UI text color
  • $bc-color-fg-ui-text--disabled: disabled UI text color, greying them out slightly.
  • $bc-color-fg-ui-icon: UI icon color
  • $bc-color-fg-ui-border: UI border color
  • $bc-color-fg-ui-border--hover: UI border color, on :hover
  • $bc-color-fg-border: border color.

Light theme background colors:

  • $bc-color-bg: (default) background color
  • $bc-color-bg-shade: slightly darker/shaded background color
  • $bc-color-bg-alt: darkest light theme background color
  • $bc-color-bg-ui: UI background color (transparent)
  • $bc-color-bg-ui--active: primary,active or selected UI element background color
  • $bc-color-bg-ui--hover: hover UI element background color
  • $bc-color-bg-ui--disabled: disabled UI element background color
  • $bc-color-bg-selection: selected text background color.

The variables of the dark theme follow this convention, with just the prefix differing, eg $bc-colordark-fg-link.

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;
}

Instead, do use the functional variables, eg:

.my-component {
  background-color: $bc-color-bg;
  color: $bc-color-fg-text;

  .bc-body--dark & {
    background-color: $bc-colordark-bg;
    color: $bc-colordark-fg-text;
  }
}

Branding palettes

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

Primary palette

$bc-bugOrange
$bc-horizon
$bc-black
$bc-white

Secondary palette

$bc-persianRed
$bc-casablanca
$bc-limeade
$bc-blueLagoon

Tertiary palette

$bc-sanMarino
$bc-carribeanGreen
$bc-dustyGrey
$bc-deepSea
$bc-purpleHeart
$bc-pomegranate
$bc-mineShaft
$bc-smoke
$bc-dustyGrey
$bc-alabaster
$bc-sandcastle

Type

Guidance last updated: Apr 18, 2018

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

Guidance last updated: Apr 18, 2018

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.

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.

Deprecation warning: please avoid using bc-outline and bc-outline-true and use bc-focus() instead.

Helpers

Guidance last updated: Feb 20, 2019

Reusable helpers, available as classes for easy-use.

Full documentation is found in the SassDoc reference for Helpers.

Do one thing and do it well

This module provides a number of simple classes that aim to do just one thing.

Single-property helper classes

  • .bc-helper-nomargin sets margin: 0
  • .bc-helper-nopadding sets padding: 0
  • .bc-helper-centeredtext sets text-align: center
  • .bc-helper-cursorpointer sets cursor: pointer.
  • .bc-helper-righttext sets text-align: right.

Note that most of these helpers include !important to ensure the single property they provide actually overrides as intended.

Mixin implementation helper classes

The more complex helpers are just class implementations of our pre-made mixins from _config.scss, eg:

  • .bc-helper-clearfix provides the bc-clearfix() mixin styles
  • .bc-helper-sronly provides the bc-sronly() (screen reader only; visually-hidden) mixin styles.

When to use helpers

Use the single-property helpers when editing markup over stylesheets is preferable or the only viable solution.

We try to avoid high specificities in our stylesheets — along with !important overrides. These classes are a compromising balance to provide utility classes that guarantee an override without adding them to app stylesheets.

Body

Guidance last updated: Apr 18, 2018

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

HTML elements styled by .bc-body

  • anchors/links
  • paragraphs
  • sorted & unsorted lists
  • definition lists
  • inline & pre-formatted (<pre>) <code> blocks
  • keyboard strokes (<kbd>)
  • <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

Markdown variant

The --markdown variant is provided for wrapping and styling user-entered Markdown content.

Theme support: This variant doesn’t yet have color theme support.

Upcoming refactor: This variant will be made a modifier of the upcoming .bc-content class refactor.

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.

Rendered example of Body

Lorem ipsum dolor sit amet, Ctrl + Alt + Delete 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.

Use Tab or to navigate.


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.
  • Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
  • Willy Wonka
    • a chocolate factory
  • foo
  1. first item
  2. second item
    • dogs
    • cats
  3. third item
Definition term
A definition description: important information. Less important information.
A second definition description. Did you know?— a single definition term can have multiple definition (descriptions).
Single room
$199 breakfast included, GST inclusive
Double room
$239 breakfast included, GST inclusive

Haml markup example of Body

// Paragraphs
%p
  Lorem ipsum dolor sit amet,
  %kbd
    Ctrl
  +
  %kbd Alt
  +
  %kbd Delete
  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.
%p
  Use
  %kbd.bc-kbd--inverted
    Tab
  or
  %kbd.bc-kbd--inverted%kbd.bc-kbd--inverted
    →
  to navigate.
%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

Variants

--markdown variant

Rendered example of Body

Heading 1 and 2 receive underlines, per GFM styles:

Heading tier one

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore.

Heading tier two

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Anchors missing a href won’t receive underlines nor link color styles: this is a link that goes nowhere.

Images:

User-name avatar

GFM-style tables:

Column heading one Column heading two Column heading three
row 1, col 1 row 1, col 2 row 1, col 3
row 2, col 1 row 2, col 2 row 2, col 3
row 3, col 1 row 3, col 2 row 3, col 3
Haml markup example of Body --markdown
.bc-body--markdown
  %p
    Heading 1 and 2 receive underlines, per GFM styles:

  %h1 Heading tier one

  %p
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
    tempor incididunt ut labore et dolore.


  %h2 Heading tier two

  %p
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
    voluptate velit esse cillum dolore eu fugiat nulla pariatur.

  %p
    Anchors missing a
    %code href
    won’t receive underlines nor link color styles:
    %a
      this is a link that goes nowhere.

  %p
    Images:

  %img{src: '/assets/profile-tmp.png', alt: 'User-name avatar'}

  %p GFM-style tables:

  %table
    %thead
      %tr
        %th
          Column heading one
        %th
          Column heading two
        %th
          Column heading three
    %tbody
      %tr
        %td
          row 1, col 1
        %td
          row 1, col 2
        %td
          row 1, col 3
      %tr
        %td
          row 2, col 1
        %td
          row 2, col 2
        %td
          row 2, col 3
      %tr
        %td
          row 3, col 1
        %td
          row 3, col 2
        %td
          row 3, col 3