Extracting color values, fonts and logos from brand guidelines can be a tedious process. Thankfully, large language models (LLMs) are great at moving words and information around and can do the tedious work for you!
Because brand.yml is a brand1 new project, large language models like OpenAI’s ChatGPT, Anthropic’s Claude and others haven’t learned the syntax (yet).
Teaching LLMs about brand.yml
Fortunately, it’s relatively easy to teach an LLM everything it needs to know about brand.yml. We’ve created a simple markdown file explaining brand.yml2 that you can copy and paste into a chat interface or that you can use as a system prompt.
Copy the code block below and paste it into a chat interface or use it as a system prompt.
## 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.If you’ve copied the above text into the chat (as opposed to using it as a system prompt), make sure that you follow up with additional instructions, for example:
Create a _brand.yml for {company} using the following context from {company}'s' brand guidelines
<!-- paste text or screenshots from typography, color, logos sections -->Some tips and tricks
Copy and paste from brand guidelines
In general, if you can copy and paste entire sections from your brand guidelines, that approach works better than uploading screenshots. If your brand guidelines are designed in PDF and are not plain text, you can take screenshots or try uploading the brand guidelines directly.
As a last resort, find a webpage or document that serves as a complete demonstration of your brand’s design and include a screenshot. In my experience, ChatGPT and Claude can get fairly close to your brand from a simple screenshot.
Ask for alternative fonts
Many brands use proprietary fonts that aren’t freely available online. When translating typographic choices from brand guidelines, LLMs tend to include placeholder YAML for these font files assuming that you’ll be able to download them.
It can be helpful to ask a follow-up question to request publicly-available font substitutes using either Google Fonts or Bunny Fonts (a GDPR-compliant alternative to Google Fonts).
Find alternative fonts that match {company}'s fonts using Google Fonts.I’ve been impressed with the ability of LLMs to pick reasonable font substitutes with this simple level of prompting.
Ask for Bootstrap color aliases
Both brand guidelines and LLMs tend to use creative language when naming colors, e.g. tea-green, amethyst, raisin and hunter (color names used in Dell’s brand guidelines). On the other hand, many web frameworks like Bootstrap have hooks for simple, common color names such as blue, green, yellow, purple, etc.
It can be helpful to ask a follow-up question to make sure that your _brand.yml includes aliases for these color names.
Update `color.palette` to include aliases for Bootstrap's
primary colors drawing from the brand's color palette.Try _brand.yml in a live example
Once you have the initial _brand.yml file from the LLM, you can try it out in a live Shiny app on shinylive.io. Shinylive apps run directly in your browser and do not require any installation.
We’ve created an example app using Shiny’s branded theming. Copy the _brand.yml from the LLM and replace the _brand.yml content in the app editor.
Footnotes
Pun intended. Sorry, not sorry.↩︎
This file is also served at https://posit-dev.github.io/brand-yml/.well-known/llms.txt.↩︎