Logo

About

The logo section in your _brand.yml file allows you to define and organize the logos and brand images for your project. This flexible system supports various logo sizes, light/dark variants, and the ability to store multiple image resources for different use cases.

Structure

The logo field in your _brand.yml file can be structured in several ways, from a simple single-logo setup to a more complex configuration with multiple sizes and variants:

  • images: A dictionary of named logo resources
  • small: Logo for small display contexts (e.g., favicons)
  • medium: Logo for medium display contexts (e.g., website headers)
  • large: Logo for large display contexts (e.g., title slides, marketing materials)

Logos can be stored locally—adjacent to your _brand.yml file—or hosted online. Local file paths should be relative to the location of your _brand.yml file (I’ll use logos/ as the directory in the examples below). Online images should use full URLs starting with http:// or https://.

Examples

Basic Multi-size Configuration

_brand.yml
logo:
  small: logos/icon.png
  medium: logos/header-logo.png
  large: logos/full-logo.svg

Light/Dark Variants

You can specify different logos for light and dark backgrounds by giving the small, medium, and large attributes a nested mapping with light and dark child elements. “light” means for use on light background (or in a light color mode), and “dark” means for use on dark background (or in a dark color mode).

_brand.yml
logo:
  small: logos/icon.png
  medium:
    light: logos/header-logo.png
    dark: logos/header-logo-white.png
  large: logos/full-logo.svg

Comprehensive Configuration with Named Resources

Use images as a nested mapping to define multiple logo resources with meaningful names. Then, you can directly reference these resources by name in the small, medium, and large attributes.

_brand.yml
logo:
  images:
    icon: logos/icon.png
    header: logos/header-logo.png
    header-white: logos/header-logo-white.png
    full: logos/full-logo.svg
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Configuration with Alternative Text

Logo images can have associated alternative text for accessibility purposes. This can be specified as an alt property in the image object as the alt text is directly associated with each image. The University of South Carolina provides a great resource on writing effective alt text for logos in their Digital Accessibility Toolbox.

_brand.yml
logo:
  images:
    icon:
      path: logos/icon.png
      alt: "Company icon with abstract shapes"
    header:
      path: logos/header-logo.png
      alt: "Company name with logo"
    header-white:
      path: logos/header-logo-white.png
      alt: "Company name with logo in white"
    full:
      path: logos/full-logo.svg
      alt: "Full company logo with tagline"
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Attributes

images

The images attribute is a mapping that allows you to define multiple logo resources with meaningful names. These named resources can then be referenced in the small, medium, and large attributes.

_brand.yml
logo:
  images:
    primary: logos/primary-logo.png
    icon: logos/favicon.png
    white: logos/white-logo.png

Each image can be specified as a simple string path or as an object with path and alt properties:

_brand.yml
logo:
  images:
    primary:
      path: logos/primary-logo.png
      alt: "Company logo with name and icon"

small

The small attribute defines the logo used for small display contexts, such as favicons or mobile app icons.

small, medium and large can each be a simple string path to the image or a reference to a named resource defined in the images attribute (shown in the second example).

_brand.yml
logo:
  small: logos/favicon.png
_brand.yml
logo:
  images:
    icon: logos/favicon.png
  small: icon

medium

The medium attribute specifies the logo for medium-sized display contexts, typically used in website headers or navigation bars.

small, medium and large can also be nested mappings with light and dark child elements to specify different logos for light and dark backgrounds (show in the second example).

_brand.yml
logo:
  medium: logos/header-logo.png
_brand.yml
logo:
  medium:
    light: logos/header-logo.png
    dark: logos/header-logo-white.png

large

The large attribute defines the logo for large display contexts, such as title slides or marketing materials.

It has the same properties as small and medium. Note that light and dark variants can also refer to named images resources (show in the second example).

_brand.yml
logo:
  large: logos/full-logo.svg
_brand.yml
logo:
  images:
    full: logos/full-logo.svg
    full-white: logos/full-logo-white.svg
  large:
    light: full
    dark: full-white