gh-posit-dev-skills-quarto/skills/brand-yml/SKILL.md

name, description

name

description

brand-yml

Create and use brand.yml files for consistent branding across Shiny apps and Quarto documents. Use when working with brand styling, colors, fonts, logos, or corporate identity in Shiny or Quarto projects. Covers: (1) Creating new _brand.yml files from brand guidelines, (2) Applying brand.yml to Shiny for R apps with bslib, (3) Applying brand.yml to Shiny for Python apps with ui.Theme, (4) Using brand.yml in Quarto documents, presentations, dashboards, and PDFs, (5) Modifying existing brand.yml files, (6) Troubleshooting brand integration issues. Includes complete specifications and framework-specific integration guides.

brand.yml Skill

Create and use _brand.yml files for consistent branding across Shiny applications and Quarto documents.

What is brand.yml?

brand.yml is a YAML-based format that translates brand guidelines into a machine-readable file usable across Shiny and Quarto. A single _brand.yml file defines:

• Colors - Palette and semantic colors (primary, success, warning, etc.)
• Typography - Fonts, sizes, weights, line heights
• Logos - Multiple sizes and light/dark variants
• Meta - Company name, links, identity information

File Naming Convention

• Standard name: _brand.yml (auto-discovered by Shiny and Quarto)
• Custom names: Any name like company-brand.yml (requires explicit paths)
• Location: Typically at project root, or in _brand/ or brand/ subdirectories

Decision Tree

Determine the user's goal and follow the appropriate workflow:

1. Creating a new _brand.yml file? → Follow "Creating brand.yml Files"
2. Using brand.yml in Shiny for R? → Read references/shiny-r.md
3. Using brand.yml in Shiny for Python? → Read references/shiny-python.md
4. Using brand.yml in Quarto? → Read references/quarto.md
5. Using brand.yml in R (general)? → Read references/brand-yml-in-r.md (R Markdown, theming functions, programmatic access)
6. Modifying existing _brand.yml? → Follow "Modifying Existing Files"
7. Troubleshooting integration? → Follow "Troubleshooting"

Creating brand.yml Files

When creating _brand.yml files from brand guidelines:

Step 1: Gather Information

Collect brand information:

• Colors: Primary, secondary, accent colors with hex values
• Fonts: Font families and where they're sourced (Google Fonts, local files, etc.)
• Logos: Logo file paths or URLs for different sizes
• Company info: Name, website, social links (optional)

Step 2: Read the Specification

Load references/brand-yml-spec.md to understand the complete brand.yml structure, field options, and syntax.

Step 3: Build the File Incrementally

Start with the essential sections and add optional elements:

Minimum viable _brand.yml:

color:
  palette:
    brand-blue: "#0066cc"
  primary: brand-blue
  background: "#ffffff"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base: Inter

Add colors as needed:

color:
  palette:
    brand-blue: "#0066cc"
    brand-orange: "#ff6600"
    brand-gray: "#666666"
  primary: brand-blue
  secondary: brand-gray
  warning: brand-orange
  foreground: "#333333"
  background: "#ffffff"

Add typography details:

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600, 700]
      style: [normal, italic]
    - family: Fira Code
      source: google
      weight: [400, 500]
  base:
    family: Inter
    size: 16px
    line-height: 1.5
  headings:
    family: Inter
    weight: 600
  monospace: Fira Code

Add logos:

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

Add meta information:

meta:
  name: Company Name
  link: https://example.com

Step 4: Apply Best Practices

Follow these rules from references/brand-yml-spec.md:

• All fields are optional - only include what's needed
• Use hex color format: "#0066cc"
• Prefer simple syntax (strings over objects) when possible
• Use lowercase names with hyphens: brand-blue, success-green
• Include https:// in all URLs
• Define colors/fonts before referencing them
• For color ranges (shades/tints), choose the midpoint color

Step 5: Validate Structure

Check that:

• YAML syntax is valid (proper indentation, quotes on hex colors)
• Color references match palette names
• Font families are defined before use
• File paths are relative to _brand.yml location
• All URLs include protocol (https://)

Modifying Existing Files

When modifying existing _brand.yml files:

1. Read the current file to understand existing structure
2. Consult brand-yml-spec.md for valid field options
3. Maintain consistency with existing naming patterns
4. Preserve references - if other colors/elements reference a name, update consistently
5. Test integration - verify changes apply correctly in Shiny/Quarto

Common modifications:

• Adding colors: Add to color.palette, then reference in semantic colors
• Changing fonts: Update in typography.fonts, ensure weights/styles are available
• Adding logo variants: Use light/dark structure for multiple variants
• Light/dark mode: Add light and dark variants to colors

Using with Shiny for R

When the user wants to apply brand.yml to a Shiny for R app:

1. Read references/shiny-r.md for complete integration guide
2. Key function: bs_theme(brand = TRUE) or bs_theme(brand = "path")
3. Automatic discovery: Place _brand.yml at app root
4. Page functions: Works with page_fluid(), page_sidebar(), etc.

Quick example:

library(shiny)
library(bslib)

ui <- page_fluid(
  theme = bs_theme(brand = TRUE),
  # ... UI elements
)

Using with Shiny for Python

When the user wants to apply brand.yml to a Shiny for Python app:

1. Read references/shiny-python.md for complete integration guide
2. Key function: ui.Theme.from_brand(__file__)
3. Automatic discovery: Place _brand.yml at app root
4. Installation: Requires pip install "shiny[theme]"

Quick example (Shiny Express):

from shiny.express import ui

ui.page_opts(theme=ui.Theme.from_brand(__file__))

Quick example (Shiny Core):

from shiny import App, ui

app_ui = ui.page_fluid(
    theme=ui.Theme.from_brand(__file__),
    # ... UI elements
)

Using with Quarto

When the user wants to apply brand.yml to Quarto documents:

1. Read references/quarto.md for complete integration guide
2. Automatic discovery: Place _brand.yml at project root with _quarto.yml
3. Supported formats: HTML, dashboards, RevealJS, Typst PDFs
4. Theme layering: Use brand keyword to control precedence

Quick example (document):

---
title: "My Document"
format:
  html:
    brand: _brand.yml
---

Quick example (project in _quarto.yml):

project:
  brand: _brand.yml

format:
  html:
    theme: default

Troubleshooting

Brand Not Applying

Shiny:

• Verify file is named _brand.yml (with underscore)
• Check file location (app directory or parent directories)
• Try explicit path: bs_theme(brand = "path/to/_brand.yml") or ui.Theme.from_brand("path")
• For Python: Ensure libsass is installed

Quarto:

• Verify _brand.yml is at project root
• Ensure _quarto.yml exists for project-level branding
• Try explicit path in document frontmatter
• Check theme layering order if using custom themes

Colors Not Matching

• Ensure hex colors have quotes: "#0066cc" not #0066cc
• Verify color names match palette definitions exactly
• Check semantic colors (primary, success, etc.) reference valid palette names
• Ensure palette is defined before semantic colors

Fonts Not Loading

• Verify Google Fonts spelling and availability
• Check internet connection (required for Google Fonts)
• Ensure source: google or source: bunny is specified
• Verify font family names match exactly in typography elements
• For Typst: Check font cache with quarto typst fonts

YAML Syntax Errors

• Check indentation (use spaces, not tabs)
• Ensure hex colors have quotes: "#447099"
• Verify colons have space after them: primary: blue
• Check list items have hyphens: - family: Inter
• Use YAML validator if syntax issues persist

Reference Documentation

Load these as needed for detailed information:

• references/brand-yml-spec.md: Complete brand.yml specification with all sections, fields, examples, and validation rules
• references/shiny-r.md: Using brand.yml with Shiny for R via bslib (bs_theme, automatic discovery, Shiny-specific integration)
• references/shiny-python.md: Using brand.yml with Shiny for Python via ui.Theme (from_brand(), installation, performance)
• references/quarto.md: Using brand.yml with Quarto (formats, light/dark mode, layering, extensions, Typst)
• references/brand-yml-in-r.md: General R usage including R Markdown integration, theming functions (ggplot2, gt, flextable, plotly, thematic), and programmatic brand access

Key Principles

• Start simple: Begin with colors and one font family
• Keep it concise: Only include fields directly relevant to the brand
• Prefer standard names: Use Bootstrap color names when possible (blue, green, red, etc.)
• Use automatic discovery: Name file _brand.yml for auto-detection
• Test across targets: Verify brand applies correctly in all intended formats
• Version control: Include _brand.yml in git repository

Common Patterns

Light/Dark Mode Colors

color:
  primary:
    light: "#0066cc"
    dark: "#3399ff"
  background:
    light: "#ffffff"
    dark: "#1a1a1a"
  foreground:
    light: "#333333"
    dark: "#e0e0e0"

Light/dark color modes were added in Quarto version 1.8 and currently are not supported in the R or Python brand.yml packages.

Logo Variants

logo:
  images:
    logo-dark: logos/logo-dark.svg
    logo-white: logos/logo-white.svg
    icon: logos/icon.png
  small: icon
  medium:
    light: logo-dark
    dark: logo-white

Multiple Font Weights

typography:
  fonts:
    - family: Inter
      source: google
      weight: [300, 400, 500, 600, 700]
      style: [normal, italic]
  base:
    family: Inter
    weight: 400
  headings:
    family: Inter
    weight: 600

Color Aliases

color:
  palette:
    navy: "#003366"
    ocean-blue: "#0066cc"
    sky-blue: "#3399ff"
    primary-color: ocean-blue  # Alias
    brand-blue: ocean-blue     # Alias
    blue: sky-blue             # Alias for primary colors
  primary: brand-blue

Include Bootstrap color names when possible, either defined directly or as aliases: blue, indigo, purple, pink, red, orange, yellow, green, teal, cyan, white, black. This is useful for consistency and these colors are picked up automatically by tools that use brand.yml.

Tips

• Read specification first: Always consult brand-yml-spec.md when creating or modifying files
• Framework-specific guides: Load the appropriate reference (shiny-r.md, shiny-python.md, quarto.md) for integration details
• Validate incrementally: Start with minimal structure, test, then add complexity
• Use references: Define colors in palette, then reference by name in semantic colors
• Standard file name: Use _brand.yml for automatic discovery
• Explicit paths: Use custom file names only when necessary (shared branding, multiple variants)