Color Palette and Theme

BrandColor

BrandColor()

Brand Colors

The brand’s custom color palette and theme. color.palette is a list of named colors used by the brand and color.theme maps brand colors to common theme elements (described in Attributes).

Examples

In this example, we’ve picked colors from Posit’s brand guidelines and mapped them directory to theme colors. This is a minimal approach to applying brand colors to theme colors.

_brand.yml
color:
  foreground: "#151515"
  background: "#FFFFFF"
  primary: "#447099"
  secondary: "#707073"
  tertiary: "#C2C2C4"
  success: "#72994E"
  info: "#419599"
  warning: "#EE6331"
  danger: "#9A4665"
  light: "#FFFFFF"
  dark: "#404041"

This example first defines a color palette from Posit’s brand guidelines and then maps them to theme colors by reference. With this approach, not all brand colors need to be used in the theme, but are still available via the brand.color.palette dictionary. This approach also reduces duplication in brand.color.

_brand.yml
color:
  palette:
    white: "#FFFFFF"
    black: "#151515"
    blue: "#447099"
    orange: "#EE6331"
    green: "#72994E"
    teal: "#419599"
    burgundy: "#9A4665"

  foreground: black
  background: white
  primary: blue
  secondary: "#707073"
  tertiary: "#C2C2C4"
  success: green
  info: teal
  warning: orange
  danger: burgundy
  light: white
  dark: "#404041"

Referencing colors in the brand’s color palette

Once defined in color.palette, you can re-use color definitions in any of the color fields. For example:

_brand.yml
color:
  palette:
    purple: "#6339E0"
  primary: purple

Once imported via brand_yml.Brand.from_yaml(), you can access the named color palette via brand.color.palette["purple"] and the primary field will be ready for use.

brand.color.palette["purple"]
'#6339E0'
brand.color.primary
'#6339E0'

This same principle of reuse applies to the color and background-color fields of brand_yml.typography.BrandTypography, where you can refer to any of the colors in color.palette or the theme colors directly.

_brand.yml
color:
  palette:
    purple: "#6339E0"
  primary: purple
typography:
  headings:
    color: primary
  link:
    color: purple

With this Brand YAML, both headings and links will ultimately be styled with the brand’s purple color.

brand.typography.headings.color
'#6339E0'
brand.typography.link.color
'#6339E0'

Attributes

palette

dict[str, str] | None

A dictionary of brand colors where each key is a color name and the value is a color string (hex colors are recommended but no specific format is required at this time). These values can be referred to, by name, in the other theme properties

foreground

Optional[str]

The foreground color, used for text. For best results, this color should be close to black and should have a high contrast with background.

background

Optional[str]

The background color, used for the page or main background. For best results, this color should be close to white and should have a high contrast with foreground.

primary

Optional[str]

The primary accent color, i.e. the main theme color. Typically used for hyperlinks, active states, primary action buttons, etc.

secondary

Optional[str]

The secondary accent color. Typically used for lighter text or disabled states.

tertiary

Optional[str]

The tertiary accent color. Typically an even lighter color, used for hover states, accents, and wells.

success

Optional[str]

The color used for positive or successful actions and information.

info

Optional[str]

The color used for neutral or informational actions and information.

warning

Optional[str]

The color used for warning or cautionary actions and information.

danger

Optional[str]

The color used for errors, dangerous actions, or negative information.

light

Optional[str]

A bright color, used as a high-contrast foreground color on dark elements or low-contrast background color on light elements.

dark

Optional[str]

A dark color, used as a high-contrast foreground color on light elements or high-contrast background color on light elements.

Methods

Name Description
to_dict Returns a flat dictionary of color definitions.

to_dict

BrandColor.to_dict(include='all')

Returns a flat dictionary of color definitions.

Parameters

include: Literal['all', 'theme', 'palette'] = ‘all’

Which colors to include: all brand colors ("all"), the brand’s theme colors ("theme") or the brand’s color palette ("palette").

Returns

Name Type Description
dict[str, str] A flat dictionary of color definitions. Which colors are returned depends on the value of include: * "all" returns a flat dictionary of colors with theme colors overlaid on color.palette. * "theme" returns a dictionary of only the theme colors, excluding color.palette. * "palette" returns a dictionary of only the palette colors