Color

Warning

This section still reflects the brand.yml spec during design. It will be updated shortly to reflect the current brand.yml specification.

About

color:
  with:
    # user-provided named colors
  # semantic theme colors
  primary: ...
  secondary ...

Palette (with)

Brand guidelines often include color palette definitions, ranging from one or two colors to entire palettes. Often, these colors are given names with specific meaning to the brand.

The color.with section gives brand.yml authors a chance to codify their brand’s palette with minimal overhead. These colors can be used by name for the semantic theme colors under color.

with may be aliased as palette.

Color Theme

While brand guidelines might provide a set of unique colors, the goal of color is to provide color values for a key set of semantic theme fields. These fields follow Bootstrap conventions closely but are universal and are easily mapped to any themable output format.

Inspiration

Directly themable

Indirectly themable

Example

Home Depot

brand_home-depot.yml
color:
  with:
    orange: "#F96302"
    white: "#FFFFFF"
    black: "#000000"
    warm-gray-dark: "#747474"
    warm-gray-light: "#f5f5f5"
    warm-gray-medium: "#c4c4c4"
  primary: "#F96302"
  secondary: "#747474"
  tertiary: "#C4C4C4"
  light: "#F5F5F5"
  dark: "#747474"
Alternate syntax 
brand_home-depot.yml
color:
  with:
    orange: "#F96302"
    white: "#FFFFFF"
    black: "#000000"
    warm-gray-dark: "#747474"
    warm-gray-light: "#f5f5f5"
    warm-gray-medium: "#c4c4c4"
  primary: orange
  secondary: warm-gray-dark
  tertiary: warm-gray-medium
  light: warm-gray-light
  dark: warm-gray-dark

See Home Depot brand guidelines.

Posit

brand.yml (Posit)
color:
  with:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"
  foreground: "#151515"
  background: "#FFFFFF"
  primary: "#447099"
  secondary: "#707073"
  tertiary: "#C2C2C4"
  success: "#72994E"
  info: "#419599"
  warning: "#EE6331"
  danger: "#9A4665"
  light: "#FFFFFF"
  dark: "#404041"
Alternate syntax 
brand.yml (Posit)
color:
  with:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"
  foreground: "#151515"
  background: white
  primary: blue
  secondary: "#707073"
  tertiary: "#C2C2C4"
  success: green
  info: teal
  warning: orange
  danger: burgundy
  light: white
  dark: gray

See Posit brand guidelines.

Spec

- id: brand-color-value
  schema: string

- id: brand-color
  description: >
    The brand's custom color palette and theme.
  object:
    closed: true
    properties:
      with:
        description: >
          The brand's custom color palette. Any number of colors can be defined,
          each color having a custom name.
        object:
          closed: false
          # We don't know the exact properties yet, but we do know they'll all be strings.
          # I'm not sure how to express that in the spec.
          additionalProperties:
            schema:
              ref: brand-color-value
      foreground:
        description: The foreground color, used for text.
        schema:
          ref: brand-color-value
        default: black
      background:
        description: The background color, used for the page background.
        schema:
          ref: brand-color-value
        default: white
      primary:
        description: >
          The primary accent color, i.e. the main theme color. Typically used for
          hyperlinks, active states, primary action buttons, etc.
        schema:
          ref: brand-color-value
      secondary:
        description: >
          The secondary accent color. Typically used for lighter text or disabled states.
        schema:
          ref: brand-color-value
      tertiary:
        description: >
          The tertiary accent color. Typically an even lighter color, used for hover states,
          accents, and wells.
        schema:
          ref: brand-color-value
      success:
        description: The color used for positive or successful actions and information.
        schema:
          ref: brand-color-value
      info:
        description: The color used for neutral or informational actions and information.
        schema:
          ref: brand-color-value
      warning:
        description: The color used for warning or cautionary actions and information.
        schema:
          ref: brand-color-value
      danger:
        description: The color used for errors, dangerous actions, or negative information.
        schema:
          ref: brand-color-value
      light:
        description: >
          A bright color, used as a high-contrast foreground color on dark elements
          or low-contrast background color on light elements.
        schema:
          ref: brand-color-value
      dark:
        description: >
          A dark color, used as a high-contrast foreground color on light elements
          or high-contrast background color on light elements.
        schema:
          ref: brand-color-value
      emphasis:
        description: >
          A color used to emphasize or highlight text or elements.
        schema:
          ref: brand-color-value
      link:
        description: >
          The color used for hyperlinks. If not defined, the `primary` color is used.
        schema:
          ref: brand-color-value

- id: brand-maybe-named-color
  description: >
    A color, which may be a named brand color.
  anyOf:
    - ref: brand-named-theme-color
    - schema: string

- id: brand-named-theme-color
  description: >
    A named brand color, taken either from `color.theme` or `color.palette` (in that order).
  enum:
    [
      foreground,
      background,
      primary,
      secondary,
      tertiary,
      success,
      info,
      warning,
      danger,
      light,
      dark,
      emphasis,
      link,
    ]

Additional color features

Automatic color definitions

For specific outputs formats, we will automatically make the brand color palette available. In HTML/Bootstrap settings, for instance, this would mean creating $brand-{name} (Sass) and --brand-{name} (CSS) variables for each color in color.palette. We could similarly define the brand colors in LaTeX and Typst formats.

For example, using the following color palette definition

brand.yml (Posit)
color:
  palette:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"

would result in the following Sass for Bootstrap.

brand.scss
// Brand colors ---------
$brand-blue: #447099;
$brand-orange: #EE6331;
$brand-gray: #404041;
$brand-white: #FFFFFF;
$brand-teal: #419599;
$brand-green: #72994E;
$brand-burgundy: #9A4665;

:root {
  --brand-blue: #{$brand-blue};
  --brand-orange: #{$brand-orange};
  --brand-gray: #{$brand-gray};
  --brand-white: #{$brand-white};
  --brand-teal: #{$brand-teal};
  --brand-green: #{$brand-green};
  --brand-burgundy: #{$brand-burgundy};
}

In Boostrap, the color.theme variables are already Sass variables, e.g. color.theme.primary maps to the $primary Sass variable or the --bs-primary CSS variable. That said, for consistency we could also map the color.theme definitions to Sass/CSS variables, e.g. $brand-primary and --brand-primary.

Shades and tints

We can imagine extending the spec to help create shades and tints of the brand colors. Users could provide any of mid, light or dark as an anchor point (but best results if only mid or light + dark or all three).

Initially, we’ll only support mid because this fits Bootstrap conventions to create a range of shades (darker variants) and tints (lighter variants), numbered from 900 (dark) to 100 (light). By default, Bootstrap uses the midpoint to seed the range, e.g. setting $blue-500 changes the range of blue values.

Note: Bootstrap uses a fixed set of colors for this type of palette – e.g. blue, indigo, red, etc. – because their values pass through Sass variables. For colors in this named list, we’d use mid to set the $*-500 variable. For other colors, we’d directly set CSS variables, replicating Bootstrap’s color logic.

Example: Posit Blue

brand_posit.yml
color:
  with:
    blue:
      mid: "#447099"

See the Pen Sass lighten() and darken() vs mix() using black and white by Garrick Aden-Buie (@gadenbuie) on CodePen.

Example: Home Depot Warm Gray

brand_home-depot.yml
color:
  with:
    warm_gray:
      light: "#f5f5f5"
      mid: "#c4c4c4"
      dark: "#747474"

See the Pen Sass lighten() and darken() vs mix() using black and white by Garrick Aden-Buie (@gadenbuie) on CodePen.

(This is just a quick example, not the final algorithm.)

Additional theme features

Re-using fields

The above is simple, but it’s easy to imagine that brand.yml authors might want to re-use colors in color.with in the theme colors. In reusing fields in open questions I outlined a possible custom syntax. Here’s an example using the shortcode-style {{< brand color palette ____ >}} syntax:

brand.yml (reusing colors)
color:
  with:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"
  theme:
    foreground: "#151515"
    background: "{{< brand color palette white >}}"
    primary: "{{< brand color palette blue >}}"
    secondary: "#707073"
    tertiary: "#C2C2C4"
    success: "{{< brand color palette green >}}"
    info: "{{< brand color palette teal >}}"
    warning: "{{< brand color palette orange >}}"
    danger: "{{< brand color palette burgundy >}}"
    light: "{{< brand color palette white >}}"
    dark: "{{< brand color palette gray >}}"

Alternatively, assuming that all the colors in color.palette become top-level Sass variables (maybe an only okay idea), we could use Sass-alike custom syntax, with a brand- prefix to avoid global namespace conflicts.

brand.yml (reusing colors)
color:
  palette:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"
  theme:
    foreground: "#151515"
    background: "$brand-white"
    primary: "$brand-blue"
    secondary: "#707073"
    tertiary: "#C2C2C4"
    success: "$brand-green"
    info: "$brand-teal"
    warning: "$brand-orange"
    danger: "$brand-burgundy"
    light: "$brand-white"
    dark: "$brand-gray"

Or, possibly just as good, we could use CSS variable declarations.

brand.yml (reusing colors)
color:
  palette:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"
  theme:
    foreground: "#151515"
    background: --brand-white
    primary: "--brand-blue"
    secondary: "#707073"
    tertiary: "#C2C2C4"
    success: "--brand-green"
    info: "--brand-teal"
    warning: "--brand-orange"
    danger: "--brand-burgundy"
    light: "--brand-white"
    dark: "--brand-gray"

Finally, without a custom re-usable field implementation, expert YAML users could use native YAML anchor and alias features.

brand.yml (native yaml)
color:
  palette:
    blue: &blue "#447099"
    orange: &orange "#EE6331"
    gray: &gray "#404041"
    white: &white "#FFFFFF"
    teal: &teal "#419599"
    green: &green "#72994E"
    burgundy: &burgundy "#9A4665"
  theme:
    foreground: "#151515"
    background: *white
    primary: *blue
    secondary: "#707073"
    tertiary: "#C2C2C4"
    success: *green
    info: *teal
    warning: *orange
    danger: *burgundy
    light: *white
    dark: *gray