Accoutrement 4.0.4

Accessing Colors

$colors (map)

scss 
$colors: () !default;

A variable storing the map of all colors globally-available on your project. Any colors added to the $colors map will be accessible to the color() function by default.

Define each color with a name, base-value, and optional adjustments…

$colors: (
  'color-name': <base-value>,
  'color-two': <base-value> ('<color-function>': '<arguments>'),
  // will return: function-name($base-value, $arguments...)
);
  • Name your colors anything – from abstractions like brand-pink, to concrete patterns like button or widget-background.
  • Base-values can be CSS-ready colors (hex, rgb, hsla), or references other colors in the map.
  • Adjustments are a nested map of color functions and arguments, for adjusting colors directly in your palette.

The color-names contrast-light and contrast-dark are special (with or without a private _ prefix). Use those names to define the default light-and-dark options for our color-contrast tools. They default to white and black respectively.

Since 0.1.0:

  • BREAKING: Uses the new shared map syntax, for internal references and adjustments

Examples

scss simple color definitions 
$colors: (
  'brand-pink': hsl(330, 85%, 62%),
  'brand-light': #fff,
  'brand-dark': #222,
);
scss reference other colors 
$colors: (
  'background': '#brand-light',
  'text': '#brand-dark',
  'link': '#brand-pink',
);
scss adjust referenced colors with any color function 
$colors: (
  'focus': '#link' ('darken': 15%, 'desaturate': 15%),
);

Used By

@function stripe-colors()

@mixin stripe-colors()

@mixin add-colors()

@mixin with-colors()

@function color()

@function default-contrast() [private]

@mixin add-colors()

Merge individual color maps into the global $colors variable, in case you want to define colors in smaller groups such as brand-colors, link-colors, etc before merging them into a single global color-palette. This can be useful for internal organization, documentation with SassDoc, or integration with our pattern-library generator: Herman.

Parameters & Output

$maps: (map...)

Pass any number of maps to be merged.

{CSS output} (code block)

  • An updated global $colors variable, with new maps merged in.

Example

scss 
$brand-colors: (
  'brand-dark': #222,
  'brand-pink': hsl(330, 85%, 62%),
);

$text-colors: (
  'text': '#brand-dark',
  'link': '#brand-pink',
);

@include tools.add-colors($brand-colors, $text-colors);

Requires

@function multi-merge()

$colors (map)

@mixin with-colors()

Override the global color palette for a section of contents. This can be useful when working with alternate themes.

Parameters

$source: (map)

The new color palette to use for contents

Example

scss 
$colors: (
  'background-dark': #222,
  'accent': hsl(330, 85%, 62%),
);

@include tools.with-colors(('background-dark': #2c05bc));
.component { background: color('background-dark'); }
css compiled 
.component {
  background: color("background-dark");
}

Requires

$colors (map)

@function color()

The primary function for accessing colors in your palette, or making adjustments on the fly.

This is more than a wrapper for map-get($colors, $x). It also handles internal color-references, recursion, and functional color-adjustments. It has access to the global $colors map by default, but you can also pass in arbitrary color-palette maps as well.

Since 2.0.0:

  • BREAKING: Provides access to color-contrast defaults, if they haven’t been re-set by the user

Since 1.0.0:

  • BREAKING: Renamed $palette arg to $source
  • BREAKING: Accepts $do argument between $color and $source

Parameters & Return

$color: (string | list)

The name of a color in your palette, or a color description in the map configuration format.

$do: null (map | null)

A map of function/ratio adjustments to run on the returned value

$source: $colors (map)

Optional map containing the source color-palette. Defaults to the global $colors map.

@return (color)

A calculated CSS-ready color, based on your global color palette and adjustments.

Example

scss 
$colors: (
  'background': #eee,
  'text': #222,
);

html {
  background: color('background');
  color: color('text');
}
css compiled 
html {
  background: color("background");
  color: color("text");
}

Requires

@function contrast-settings() [private]

@function compile()

@function get() [private]

$colors (map)

Used By

@mixin contrasted()

@function luminance()

@function shades-of()

@function stripe-colors()

@function tint()

@function shade()

@function best-contrast() [private]

@function compile-colors()

Compile all the tokens in a color map. This is particularly useful for exporting a static version of the token map with all the Accoutrement syntax removed – e.g. for use in javascript or documentation.

Since 4.0.0:

  • NEW: Provides an export option for color token maps

Parameters & Return

$map: $colors (map)

The map to be compiled

$source: $colors (map | null)

A map of reference tokens that can be used for resolving colors. (defaults to the global $colors map)

@return (map)

A copy of the original map, with all token values resolved

Requires

@function map-compile-with()