Configuration

Sass !default variables

In Sass variables can be flagged as !default. That means that if another variable with the same name is defined in the scope of the project the !default variable will be overwritten (learn more about it here).

Backbreeze's configuration API is based on this principle. To configure the values for a property class you need to overwrite it by creating a variable with the same name in your project:

// project config
// This declaration will overwritte each instance
// of the `!default` $bb-colors variable
$bb-colors: (
  'white': #fff,
  'black': #000,
  'primary': #006cd6,
  'accent': #f8c326,
  'danger': #cb2431,
  'current': currentColor,
);

// backbreeze config default
// Default value
$bb-colors: (
  'white': #fff,
  'black': #000,
  'current': currentColor,
) !default;

Due to the way default variables work in Sass you need to overwrite any Backbreeze variables before including the Backbreeze _config.scss file (see installation).

Backbreeze configuration variables are categorized in:

• Property-driven
• General
• Internal

Property-driven variables

Each CSS property class has two configuration variables, one that holds the property's values, and one that holds configuration for that property (e.g. name, breakpoints, pseudo states), both variables are Sass maps.

All variables have the same pattern:

$bb-<PROPERTY_NAME>-values: (
  /* values */
);
$bb-<PROPERTY_NAME>-config: (
  /* configuration */
);

Example:

$bb-text-align-values: (
  /* values */
);
$bb-text-align-config: (
  /* configuration */
);

Values

The values variable follow a simple key value pattern where the key will be the name for the value that is used in the resulting utility class:

$bb-text-align-values: (
  'c': center,
);
// will yield:
.ta-c {
  text-align: center;
}

If the variable is false or the map is empty no classes will be generated.

NOTE: Empty map keys

Using an empty map key will result in a class without a value reference.

$main-font-size: 18px;
$bb-font-size-values: (
  '': $main-font-size,
  'lg': 22px,
);

Will yield:

.fs {
  font-size: 18px;
}
.fs-lg {
  font-size: 22px;
}

NOTE: Using special characters in map keys

To have nice classes some of the default values use characters that need to be escaped in the generated CSS e.g.:

<div class="lh-1.5">
  <!-- ... -->
</div>

.lh-1\.5 {
  line-height: 1.5;
}

Backbreeze will escape ., /, and % automatically.

Other special characters will need to be escaped using \\:

$bb-line-height-values: (
  '1.4': 1.4, // <= Automatically escaped
  '2': 2,
  '1\\*2': 2, // <= `*` needs to be escaped
);

NOTE: Negative values

Negative values are generated automatically for CSS properties to whom it is useful by default. These properties are defined in the internal variable $bb-negative-properties. Adding a positive value will also generate a negative counterpart:

$bb-top-values: (
  '10': 10px,
);

Will yield:

.top-10 {
  top: 10px;
}
.-top-10 {
  top: -10px;
}

Negative values / classes can also be generated by prefixing value keys with a dash (-). Be aware that this pattern does not make the value automatically negative, you have to take care of that yourself. This feature is useful for non strictly numeric values like transforms.

$bb-transform-values: (
  '-50\\%': translate(-50%, -50%),
  // ...,
);

Will yield:

.-tf-50\% {
  transform: translate(-50%, -50%);
}

Configuration

The configuration map has three mandatory keys:

Optional keys:

Example:

$bb-text-align-config: (
  'name': 'ta',
  'prop': 'text-align',
  'values': $bb-text-align-values,
  'bps': $bb-mqs,
);

General variables

General variables are used to define values for multiple properties. It is recommended to customize these for every project.

$bb-namespace

Type <String>. Namespace generated class names, it defaults to an empty string, that means classes are not namespaced by default. In case you want to use Backbreeze with another library or just want to make clear what classes are utility classes you can set a namespace to prevent naming collisions.

Default value:

$bb-namespace: '' !default;

Example:

$bb-namespace: 'bb';

- .ta-center {
+ .bb-ta-center {
    text-align: center;
  }

Setting $bb-namespace: 'bb-'; will make all classes look like this: .bb-<REST OF THE CLASS> (.-bb-<REST OF THE CLASS>) for negative classes.

$bb-bps

Type <Map>, the keys will be used in the responsive class names. Used in: all classes that are responsive.

Default value:

$bb-bps: (
  'xs': 416px,
  'sm': 756px,
  'md': 1024px,
  'lg': 1220px,
  'xl': 1460px,
) !default;

$bb-spacing

Defines spacing. Used in: padding, margin, top, left, right, bottom.

Default value:

$bb-spacing: (
  '1': 1px,
  '2': 2px,
  '3': 3px,
  '4': 4px,
  '': 26px,
) !default;

$bb-sizes

Defines sizes. Used in: width, max-width, min-width, height, max-height, min-height, flex-basis.

Default value:

$bb-sizes: (
  '1': 1px,
  '2': 2px,
  '3': 3px,
  '4': 4px,
  '': 26px,
) !default;

$bb-colors

Defines colors. Used in: background-color, border-color, color, outline-color, fill, stroke

Default value:

$bb-colors: (
  'white': #fff,
  'black': #000,
  'current': currentColor,
) !default;

Internal variables

Internal variables that should not no customization.

$bb-directional-properties

Type <List>. List of CSS properties that have directional values (e.g. padding-left, margin-bottom).

Default value:

$bb-directional-properties: (
  'padding',
  'margin',
  'border',
  'border-width',
  'border-style',
  'border-color',
  'border-radius'
) !default;

$bb-negative-properties

Type <List>. All values for the properties in this list will have a corresponding negative value (and corresponding class name) generated automatically.

Default value:

$bb-negative-properties: ('margin', 'top', 'left', 'bottom', 'right') !default;

Negative classes are prefixed by a dash:

.-top-10 {
  top: -10px;
}

$bb-pseudo

Type <List>. Pseudo classes to generate for a given property.

Default value:

$bb-pseudo: ('hover', 'focus', 'active', 'group-hover') !default;

Group hover is used to allow for nested elements that respond to hover interaction with its parent .group element:

<a class="group">
  <h3 class="c-primary:group-hover">
    Hovering the group will change the coolor of the text
  </a>
</a>

$bb-overflow

Type <List>. Overflow values used for the properties overflow, overflow-x, overflow-y.

Default value:

$bb-overflow: (
  'hidden': hidden,
  'visible': visible,
  'scroll': scroll,
  'auto': auto,
) !default;

Recommended configuration

The following variables will are the most likely to be customized for every project that uses Backbreeze:

// _vars.scss
// Breakpoints
$bb-bps: (/* ... */);
// Spacing
$bb-spacing: (/* ... */);
// Sizes
$bb-sizes: (/* ... */);
// Colors
$bb-colors: (/* ... */);
// Font Family
$bb-font-family-values: (/* ... */);
// Font Sizes
$bb-font-size-values: (/* ... */);
// Line height
$bb-line-height-values: (/* ... */);