## About brand.yml

brand.yml is a structured YAML file to hold brand information for key
brand elements. The goal of brand.yml is to capture the essence of the
brand's color and typographic choices in a simple format.

"brand.yml" is the name of the project defining the YAML specification.
A specific instance of a brand's data is stored in a file named
"_brand.yml" by convention.

## Brand Elements

-   `meta` - Key identity information, name of the company, links to
    brand guidelines, etc.

-   `logo` - Files or links to the brand's logo at various sizes.

-   `color` Semantic colors, e.g. `primary`, `secondary`, `success`,
    `warning`, etc. Named colors in the brand's color palette are stored
    in `color.palette`.

-   `typography` - Font family, weight, style, color, and line height
    for key elements, e.g. base, headings and monospace text. Available
    fonts used by the brand are stored in `typography.fonts` and can be
    sourced from Google Fonts, Bunny Fonts or local or remote font
    files.

-   `defaults` - Additional context-specific settings beyond the basic
    brand colors and typography. These could be options, for example,
    that are used by Bootstrap in Quarto or Shiny. They could also be
    folded into existing Quarto yaml fields like `format` or `website`,
    or they could be new fields for other contexts like `shiny`.

## Example file

The following YAML includes all allowed features of a _brand.yml file.
Note that all fields are optional.

Only include fields that directly apply to the brand; it's important for
the _brand.yml file to be simple and concise rather than overly
complex. Many fields have simple and complex values variants; generally
speaking many fields accept either a simple string or a mapping.
Alternative syntax is indicated in comments in the example below with
"ALT". If possible, use the simple string.

``` {.yaml filename="_brand.yml"}
meta:
  # name: Acme # ALT: Single string for simple company name
  name:
    short: Acme # Short company name
    full: Acme Corporation International # Full, legal company name
  
  # link: https://acmecorp.com # ALT: single url for the company's home page
  link:
    home: https://www.acmecorp.com # Company's home apge
    bluesky: https://bsky.app/profile/acmecorp.bsky.social # Bluesky social media account link
    github: https://github.com/acmecorp # GitHub account link
    mastodon: https://mastodon.social/@acmecorp # Mastodon account link
    linkedin: https://www.linkedin.com/company/acmecorp # LinkedIn account link
    facebook: https://www.facebook.com/acmecorp # Facebook account link
    twitter: https://twitter.com/acmecorp # Twitter account link

logo:
  images: # Mapping of image names to local files that should be stored next to the _brand.yml file. Users may need to download these files manually.
    header: logos/header-logo.png # Each entry maps a name to a local file
    header-white: logos/header-logo-white.png
    full: # ALT: Images can alternatively be a path with associated alt text for accessibility
      path: logos/full-logo.svg
      alt: Acme logo.
  small: logos/icon.png # A small image, ideally icon-sized. Can be a path to a file or the name of a file in `logo.images`
  medium: # A medium sized logo, ideally small enough for a sidebar logo
    # ALT: Logos is small, medium, and large may have `light` and `dark` variants
    light: header # light variant for use on light backgrounds
    dark: header-white # dark variant for use on dark backgrounds
  large: full # A large logo, e.g. for use in a hero or cover page. ALT: Can refer directly to images in `logo.images`.

color:
  palette:
    # Dictionary of the brand's colors with readable names. 
    # Must be a flat list of names and color values. 
    # Names should be follow Sass variable conventions. Prefer hex color values.
    # Prefer or create aliases for Bootstrap primary colors: blue, indigo, purple, pink, red, orange, yellow, green, teal, cyan, white, black
    white: "#FFFFFF"
    black: "#151515"
    blue: "#447099"
    orange: "#EE6331"
    green: "#72994E"
    teal: "#419599"
    burgundy: "#9A4665"
    purple: burgundy # Aliases are allowed by referring to other colors in `color.palette`
    fire-red: "#FF0000"
    bright-yellow: "#FFFF00"

  # All theme colors can take direct color values, and all are optional.
  # Only include the colors that are obviously required.
  # Refer to color names from `color.palette` whenever possible.
  foreground: "#151515"  # Main text color, should have high contrast with background
  background: "#FFFFFF"  # Main background color, should have high contrast with foreground
  primary: "#447099"  # Main accent color for links, buttons, etc.
  secondary: "#707073"  # Used for lighter text or disabled states. Only include if necessary.
  tertiary: "#C2C2C4"  # Even lighter color for hover states, accents, wells. Only include if necessary.
  success: "#72994E"  # Color for positive or successful actions/information
  info: "#419599"  # Color for neutral or informational actions/information
  warning: "#EE6331"  # Color for warning or cautionary actions/information,
  danger: "#9A4665"  # Color for errors, dangerous actions, negative information
  light: "#FFFFFF"  # Bright color for high-contrast on dark elements
  dark: "#404041"  # Dark color for high-contrast on light elements
  # ALT: All properties in `color` can refer by name to values in `color.palette`, including within `color.palette`.
  # foreground: black
  # background: white
  # primary: blue
  # success: green
  # info: teal
  # ALT: All properties in `color` can refer by name to other properties in `color`.

typography:
  fonts:
    - family: Open Sans  # Font family name
      source: file  # Source of the font (file, google, bunny, or system)
      files:  # REQUIRED list of font files for `source: file`, which must have at least one font file. Use placeholder names and comment out the source font section if proprietary fonts are used. (And include a Google Font alternative recommendation.)
        - path: fonts/open-sans/OpenSans-Variable.ttf
          # Each file corresponds to a weight and style, both default to "normal".
          weight: 400  # Optional: specify weight for this file
          style: normal  # Optional: specify style for this file
        - path: fonts/open-sans/OpenSans-Variable-Italic.ttf
          style: italic
    - family: Roboto Slab
      source: google
      weight: [600, 900]  # Optional font weights to include (for google and bunny), defaults to all weights
      # weight: 600..900 # ALT: fonts with variable weights can have a weight range
      # weight: [thin, normal, bold] # ALT: font weights by name are allowed
      style: [normal, italic]  # Font styles to include (for google and bunny)
      display: block  # Font display property (for google). Optional and should not be included in most cases.
    - family: Fira Code
      source: bunny # Use Bunny Fonts, a GDPR-compliant alternative to Google Fonts
      weight: [400, 500, 600] # Optional, same as for `source: google`
      style: [normal, italic] # Optional, same as for `source: google`
  
  # base: Open San # ALT: If a string, sets the base font family
  base:
    family: Open Sans  # Optional: Font family for body text
    weight: 400  # Optional: Font weight for body text
    size: 16px  # Optional: Font size for body text, allows any CSS value, rem or px are preferred
    line-height: 1.5  # Optional: Line height for body text
    # DO NOT INCLUDE color HERE. The base font uses `color.foreground` by default.
  
  # headings: Roboto Slab # ALT: If a string, sets the headings font family
  headings:
    family: Roboto Slab  # Optional: Font family for headings
    weight: 600  # Optional: Font weight for headings
    style: normal  # Optional: Font style for headings
    line-height: 1.2  # Optional: Line height for headings
    color: "#333333"  # Optional: Color for headings
    # color: primary # ALT: Can use named colors from `color` or `color.palette`
  
  # monospace: Fira Code # ALT: If a string, sets the monospace font family
  monospace:
    family: Fira Code  # Optional: Font family for monospace text
    weight: 400  # Optional: Font weight for monospace text
    size: 0.9em  # Optional: Font size for monospace text, CSS units allowed but `rem` or `px` preferred
  monospace-inline: # Inline monospace text, inherits from monospace
    # Properties of monospace can be overwritten here
    color: "#7d12ba"  # Color for inline monospace text, ALT: named colors from `color` or `color.palette`
    background-color: "#f8f9fa"  # Background color for inline monospace text, ALT: named colors from `color` or `color.palette`
  monospace-block:
    color: foreground  # Color for block monospace text, ALT: named colors from `color` or `color.palette`
    background-color: background  # Background color for block monospace text, ALT: named colors from `color` or `color.palette`
    line-height: 1.4  # Line height for block monospace text
  link:
    weight: 600  # Font weight for links
    color: "#0066cc"  # Optional color for link, defaults `color.primary`. ALT: named colors from `color` or `color.palette`
    background-color: transparent  # Optional background color for links, ALT: named colors from `color` or `color.palette`
    decoration: underline  # Optional text decoration for links

defaults: # Additional Bootstrap, Shiny, or Quarto rules, all optional and only to be used as a last resort
  bootstrap: Additional scss rules for any contexts that use Bootstrap
    functions: # string with scss function declarations
    defaults: # Mapping of Bootstrap variables to default values
    mixins: # string with scss mixins
    rules: # string with scss rules
  quarto:
    format:
      # Options specific to output Quarto output formats
  shiny:
    theme: # Additional scss rules to add to the Shiny branded theme
      defaults:
        # Named bootstrap variables and their default values
        navbar-bg: $brand-orange # Use Sass variables to access brand colors: $brand-{color_name}
      rules:
        # A string of additional scss rules
```

## Brand best practices

Be careful and be certain to follow these rules when creating the
`_brand.yml` file:

-   When brands define a range of shades and tints for colors, it's best
    to choose the midpoint color as the primary color used in the
    `color.palette`.

-   For logo and font files, use placeholders in the `_brand.yml` with
    instructions to download the files and place them next to
    `_brand.yml`.

-   Suggest substitutes for proprietary fonts by finding the closest
    equivalent fonts on Google Fonts.

-   Prefer hex color syntax for raw color values.

Provide the YAML file directly in a markdown block. Include any
follow-up instructions in the YAML as inline comments.