AGENT SKILLBY POSIT-DEV

Brand yml

AT A GLANCE

Brand yml is a brand skill for AI agents. Create and use brand.yml files for consistent branding across Shiny applications and Quarto documents. It is published by posit-dev in the posit-dev/skills GitHub repository (415 stars) under the MIT license. Install it with: npx skills add posit-dev/skills --skill brand-yml

FIG. 01 · BRAND

SOURCE REPOSITORY: posit-dev/skills (opens GitHub in a new tab)
REPO STARS: SOURCE REPOSITORY
LICENSE: MIT
CATEGORIES: Brand
SKILL.MD SIZE: 54 KB2,529 LINES

§03

QUICK ANSWER

WHAT IT IS01: Create and use brand.yml files for consistent branding across Shiny applications and Quarto documents. It stands out by giving brand and messaging a defined shape, so the agent asks for better context and returns a more usable result.
INPUTS02: Context for brand and messaging: your goals, audience, constraints, and any source material the skill asks for.
OUTPUT03: A ready-to-use result for brand and messaging: the analysis, copy, or recommendations the agent produces.

§04

INSTALL

One command adds this skill from its source repository.

$ npx skills add posit-dev/skills --skill brand-yml

READ THE SKILL.MD BELOW BEFORE YOU RUN IT. SKILLS INSTRUCT YOUR AGENT.

§05

SKILL.MD

The full file, as published in the source repository. Copy it, download it or open it on GitHub.

Download SKILL.md Open on GitHub View raw markdown

ON THIS PAGE · 84

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:

Creating a new _brand.yml file? → Follow "Creating brand.yml Files"
Using brand.yml in Shiny for R? → Read references/shiny-r.md
Using brand.yml in Shiny for Python? → Read references/shiny-python.md
Using brand.yml in Quarto? → Read references/quarto.md
Using brand.yml in R (general)? → Read references/brand-yml-in-r.md (R Markdown, theming functions, programmatic access)
Modifying existing _brand.yml? → Follow "Modifying Existing Files"
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:

yaml · 12 LINES

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:

yaml · 10 LINES

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:

yaml · 17 LINES

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:

yaml · 4 LINES

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

Add meta information:

yaml · 3 LINES

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:

Read the current file to understand existing structure
Consult brand-yml-spec.md for valid field options
Maintain consistency with existing naming patterns
Preserve references - if other colors/elements reference a name, update consistently
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:

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

Quick example:

r · 7 LINES

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:

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

Quick example (Shiny Express):

python · 3 LINES

from shiny.express import ui

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

Quick example (Shiny Core):

python · 6 LINES

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:

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

Quick example (document):

yaml · 6 LINES

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

Quick example (project in _quarto.yml):

yaml · 6 LINES

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#

yaml · 10 LINES

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#

yaml · 9 LINES

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#

yaml · 12 LINES

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#

yaml · 9 LINES

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)

Supporting file: references/brand-yml-in-r.md#

Using brand.yml in R#

Guide for using brand.yml in R projects beyond Shiny, including R Markdown documents, theming functions for plots and tables, and programmatic access to brand data.

Overview#

The brand.yml R package provides tools for applying brand styling to R visualizations and documents. These tools work in any R context, including R Markdown documents, Quarto, standalone scripts, and Shiny applications.

Installation#

r · 2 LINES

# Install brand.yml package
install.packages("brand.yml")

R Markdown Integration#

Use brand.yml in R Markdown documents (without runtime: shiny):

yaml · 8 LINES

---
title: "My Report"
output:
  html_document:
    theme:
      version: 5          # Required for brand.yml
      brand: true         # Auto-discover _brand.yml
---

Or specify a path:

yaml · 8 LINES

---
title: "My Report"
output:
  html_document:
    theme:
      version: 5
      brand: "path/to/brand.yml"
---

Important: Set version: 5 to use Bootstrap 5, which has the best brand.yml support.

Other R Markdown Formats#

Brand.yml works with various R Markdown output formats:

yaml · 9 LINES

---
title: "Branded Report"
output:
  html_document:
    theme:
      version: 5
      brand: _brand.yml
  pdf_document: default
---

Programmatic Access#

Read and access brand data programmatically in any R script or document:

r · 18 LINES

library(brand.yml)

# Read from default location (_brand.yml in project)
brand <- read_brand_yml()

# Read from specific path
brand <- read_brand_yml("path/to/brand.yml")

# Access brand elements
brand$color$palette$blue          # "#447099"
brand$color$primary               # blue -> "#447099"
brand$typography$base$family      # "Open Sans"
brand$meta$name                   # "Company Name"

# Access all colors
brand$color$palette               # List of all palette colors
brand$color$foreground            # Foreground color
brand$color$background            # Background color

Use programmatically accessed brand data to:

Display brand colors in custom visualizations
Show brand logo with correct paths
Apply brand fonts to custom elements
Build branded themes dynamically
Generate branded reports programmatically

Branded Theming Functions#

The brand.yml package includes helper functions to apply brand colors to plots and tables from popular R packages. These functions work in any R context (scripts, R Markdown, Quarto, Shiny).

theme_brand_ggplot2()#

Apply brand colors to ggplot2 visualizations:

r · 21 LINES

library(ggplot2)
library(brand.yml)

# Automatic brand detection
ggplot(mtcars, aes(mpg, hp)) +
  geom_point() +
  theme_brand_ggplot2()

# Explicit brand file
ggplot(mtcars, aes(mpg, hp)) +
  geom_point() +
  theme_brand_ggplot2(brand = "_brand.yml")

# Override specific colors
ggplot(mtcars, aes(mpg, hp)) +
  geom_point() +
  theme_brand_ggplot2(
    background = "white",
    foreground = "brand-gray",
    accent = "brand-blue"
  )

Parameters:

brand: NULL (auto-detect), file path, brand object, or FALSE
background, foreground, accent: Primary color settings
base_size: Base font size (default: 11)
Additional parameters for fine-grained control: title_color, line_color, rect_fill, panel_background_fill, panel_grid_major_color, etc.

theme_brand_gt()#

Apply brand colors to gt tables:

r · 23 LINES

library(gt)
library(brand.yml)

# Create branded table
mtcars |>
  head() |>
  gt() |>
  theme_brand_gt()

# With explicit brand
mtcars |>
  head() |>
  gt() |>
  theme_brand_gt(brand = "_brand.yml")

# Override colors
mtcars |>
  head() |>
  gt() |>
  theme_brand_gt(
    background = "white",
    foreground = "brand-gray"
  )

Parameters:

table: The gt table object to theme
brand: NULL (auto-detect), file path, brand object, or FALSE
background: Table background color (default: brand.color.background)
foreground: Text color (default: brand.color.foreground)

theme_brand_flextable()#

Apply brand colors to flextable tables:

r · 23 LINES

library(flextable)
library(brand.yml)

# Create branded flextable
mtcars |>
  head() |>
  flextable() |>
  theme_brand_flextable()

# With explicit brand
mtcars |>
  head() |>
  flextable() |>
  theme_brand_flextable(brand = "_brand.yml")

# Override colors
mtcars |>
  head() |>
  flextable() |>
  theme_brand_flextable(
    background = "white",
    foreground = "brand-gray"
  )

Parameters:

table: The flextable object to theme
brand: NULL (auto-detect), file path, brand object, or FALSE
background: Table background color (default: brand.color.background)
foreground: Text color (default: brand.color.foreground)

theme_brand_plotly()#

Apply brand colors to plotly visualizations:

r · 18 LINES

library(plotly)
library(brand.yml)

# Create branded plotly chart
plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers") |>
  theme_brand_plotly()

# With explicit brand
plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers") |>
  theme_brand_plotly(brand = "_brand.yml")

# Override colors
plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers") |>
  theme_brand_plotly(
    background = "white",
    foreground = "brand-gray",
    accent = "brand-blue"
  )

Parameters:

plot: The plotly plot object to theme
brand: NULL (auto-detect), file path, brand object, or FALSE
background: Plot background color (default: brand.color.background)
foreground: Text/foreground color (default: brand.color.foreground)
accent: Accent/highlight color (default: brand.color.primary)

theme_brand_thematic()#

Apply brand colors to base R graphics via thematic:

r · 16 LINES

library(thematic)
library(brand.yml)

# Create theme object
theme <- theme_brand_thematic()

# Use with thematic_with_theme()
thematic::thematic_with_theme(theme, {
  plot(mtcars$mpg, mtcars$hp)
})

# Or use with ggplot2
thematic::thematic_with_theme(theme, {
  ggplot(mtcars, aes(mpg, hp)) +
    geom_point()
})

theme_brand_thematic_on()#

Immediately activate brand theming globally for base R graphics:

r · 12 LINES

library(thematic)
library(brand.yml)

# Turn on brand theming globally
theme_brand_thematic_on()

# Now all plots use brand colors
plot(mtcars$mpg, mtcars$hp)
hist(mtcars$mpg)

# Turn off later
thematic::thematic_off()

Parameters (both functions):

brand: NULL (auto-detect), file path, brand object, or FALSE
background: Background color (default: brand.color.background)
foreground: Foreground color (default: brand.color.foreground)
accent: Accent color (default: brand.color.primary)
...: Additional arguments passed to thematic package

Difference:

theme_brand_thematic(): Returns theme object for scoped use
theme_brand_thematic_on(): Immediately applies theme globally

R Markdown Example#

Complete example showing theming functions in R Markdown:

markdown · 33 LINES

---
title: "Branded Report"
output:
  html_document:
    theme:
      version: 5
      brand: _brand.yml
---

```{r setup}
library(ggplot2)
library(gt)
library(brand.yml)
```

## Sales Analysis

```{r plot}
ggplot(mtcars, aes(mpg, hp, color = factor(cyl))) +
  geom_point(size = 3) +
  labs(title = "MPG vs Horsepower", color = "Cylinders") +
  theme_brand_ggplot2()
```

## Data Summary

```{r table}
mtcars |>
  head(10) |>
  gt() |>
  theme_brand_gt() |>
  tab_header(title = "Motor Trend Car Data")
```

Quarto Integration#

Works seamlessly in Quarto documents:

markdown · 16 LINES

---
title: "Branded Analysis"
format:
  html:
    brand: _brand.yml
---

```{r}
#| label: branded-plot
library(ggplot2)
library(brand.yml)

ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
  geom_point() +
  theme_brand_ggplot2()
```

Script Usage#

Use in standalone R scripts:

r · 15 LINES

#!/usr/bin/env Rscript

library(brand.yml)
library(ggplot2)

# Read brand
brand <- read_brand_yml("_brand.yml")

# Create branded plot
p <- ggplot(mtcars, aes(mpg, hp)) +
  geom_point(color = brand$color$primary) +
  theme_brand_ggplot2()

# Save with brand colors
ggsave("output.png", p, width = 8, height = 6)

Benefits#

Consistency: Same brand styling across all R outputs (plots, tables, documents)
Automatic detection: Functions find _brand.yml automatically
Flexible override: Easy to customize colors when needed
Works everywhere: R scripts, R Markdown, Quarto, Shiny

Tips#

Place _brand.yml at project root for automatic discovery
Use read_brand_yml() for programmatic access to brand data
Combine theming functions for cohesive branded reports
Set version: 5 in R Markdown YAML for Bootstrap 5 support
Test theme functions individually before combining in documents

Common Patterns#

Branded Report with Multiple Visualizations#

r · 19 LINES

library(brand.yml)
library(ggplot2)
library(gt)

# Load brand
brand <- read_brand_yml()

# Create consistent visualizations
plot1 <- ggplot(data1, aes(x, y)) +
  geom_point() +
  theme_brand_ggplot2()

plot2 <- ggplot(data2, aes(x, y)) +
  geom_line() +
  theme_brand_ggplot2()

table1 <- data3 |>
  gt() |>
  theme_brand_gt()

Dynamic Brand Colors#

r · 13 LINES

library(brand.yml)

brand <- read_brand_yml()

# Use brand colors in custom visualizations
my_colors <- c(
  brand$color$primary,
  brand$color$secondary,
  brand$color$success
)

# Apply to plot
plot(data, col = my_colors[factor(group)])

Conditional Branding#

r · 11 LINES

library(brand.yml)

# Use different brands for different contexts
if (Sys.getenv("BRAND_MODE") == "internal") {
  brand <- read_brand_yml("internal-brand.yml")
} else {
  brand <- read_brand_yml("external-brand.yml")
}

# Apply to visualizations
theme <- theme_brand_ggplot2(brand = brand)

Supporting file: references/brand-yml-spec.md#

brand.yml Specification#

Complete specification for creating valid _brand.yml files for the brand.yml project.

File Naming Convention#

Conventional name: _brand.yml (auto-discovered by Shiny and Quarto)
Custom names: Any .yml file (e.g., my-brand.yml) requires explicit paths
Location: Typically at project root or in _brand/ or brand/ subdirectories

File Structure#

All fields are optional. Only include fields directly relevant to the brand.

yaml · 5 LINES

meta:           # Company/project identity information
logo:           # Logo files and variants
color:          # Color palette and semantic colors
typography:     # Fonts and text styling
defaults:       # Framework-specific customizations

Meta Section#

Company or project metadata.

Simple Format#

yaml · 3 LINES

meta:
  name: Acme
  link: https://acmecorp.com

Extended Format#

yaml · 13 LINES

meta:
  name:
    short: Acme
    full: Acme Corporation International
  link:
    home: https://www.acmecorp.com
    docs: https://docs.acmecorp.com
    github: https://github.com/acmecorp
    bluesky: https://bsky.app/profile/acmecorp.bsky.social
    mastodon: https://mastodon.social/@acmecorp
    linkedin: https://www.linkedin.com/company/acmecorp
    facebook: https://www.facebook.com/acmecorp
    twitter: https://twitter.com/acmecorp

Requirements:

All links must include https:// prefix
Additional custom fields are allowed

Logo Section#

Logo files for different contexts and sizes.

Structure#

yaml · 6 LINES

logo:
  images:           # Named logo resources (optional)
    name: path      # Map names to file paths or URLs
  small: path       # Icon-sized logo (favicons, mobile)
  medium: path      # Standard logo (headers, navigation)
  large: path       # Large logo (hero, title slides)

File Paths#

Local files: Relative paths from _brand.yml location (e.g., logos/logo.png)
Remote files: Full URLs with http:// or https://

Light/Dark Variants#

yaml · 4 LINES

logo:
  medium:
    light: logo-dark.png      # For light backgrounds
    dark: logo-white.png      # For dark backgrounds

With Alt Text#

yaml · 6 LINES

logo:
  images:
    header:
      path: logos/header.svg
      alt: Company logo
  medium: header

Complete Example#

yaml · 13 LINES

logo:
  images:
    header: logos/header-logo.png
    header-white: logos/header-logo-white.png
    icon: logos/icon.png
    full:
      path: logos/full-logo.svg
      alt: Acme Corporation logo
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Color Section#

Brand color palette and semantic color assignments.

Structure#

yaml · 15 LINES

color:
  palette:        # Named brand colors
    name: "#hex"  # Flat list of color names and hex values
  # Semantic theme colors (all optional)
  foreground: "#color"    # Main text color
  background: "#color"    # Main background color
  primary: "#color"       # Links, buttons, primary actions
  secondary: "#color"     # Lighter text, disabled states
  tertiary: "#color"      # Hover states, accents
  success: "#color"       # Positive actions
  info: "#color"          # Neutral information
  warning: "#color"       # Cautions
  danger: "#color"        # Errors, negative actions
  light: "#color"         # High contrast on dark
  dark: "#color"          # High contrast on light

Color Palette Best Practices#

Use hex color values: "#447099"
Use descriptive names following Sass conventions: blue, brand-orange, success-green
Create aliases by referencing other palette colors: purple: burgundy
Include Bootstrap color names when possible: blue, indigo, purple, pink, red, orange, yellow, green, teal, cyan, white, black
When brands define ranges of shades, choose the midpoint as the primary color

Referencing Colors#

Theme colors can reference palette names:

yaml · 6 LINES

color:
  palette:
    brand-blue: "#447099"
    brand-orange: "#EE6331"
  primary: brand-blue      # References palette
  warning: brand-orange    # References palette

Complete Example#

yaml · 16 LINES

color:
  palette:
    white: "#FFFFFF"
    black: "#151515"
    blue: "#447099"
    orange: "#EE6331"
    green: "#72994E"
    teal: "#419599"
    burgundy: "#9A4665"
  foreground: black
  background: white
  primary: blue
  success: green
  info: teal
  warning: orange
  danger: burgundy

Typography Section#

Font definitions and text element styling.

Structure#

yaml · 11 LINES

typography:
  fonts:              # Font definitions
    - family: Name
      source: type    # file, google, bunny, or system
      # Additional source-specific fields
  base:               # Body text (optional)
  headings:           # Heading text (optional)
  monospace:          # Code text (optional)
  monospace-inline:   # Inline code (optional)
  monospace-block:    # Code blocks (optional)
  link:               # Hyperlinks (optional)

Font Sources#

Local/Remote Files#

yaml · 13 LINES

fonts:
  - family: Open Sans
    source: file
    files:
      - path: fonts/OpenSans-Regular.ttf
        weight: 400
        style: normal
      - path: fonts/OpenSans-Bold.ttf
        weight: 700
        style: normal
      - path: https://example.com/fonts/OpenSans-Italic.ttf
        weight: 400
        style: italic

Proprietary fonts, should be downloaded and stored adjacent to the brand.yml file and referenced via relative paths in the path field.

Google Fonts#

yaml · 6 LINES

fonts:
  - family: Roboto
    source: google
    weight: [400, 700]        # Optional: specific weights
    style: [normal, italic]   # Optional: specific styles
    display: block            # Optional: font-display property

Weight options:

Array of numbers: [400, 700]
Range (variable fonts): 400..900
Named weights: [thin, normal, bold]

yaml · 5 LINES

fonts:
  - family: Inter
    source: bunny
    weight: [400, 600]
    style: [normal, italic]

Same syntax as Google Fonts.

Typographic Elements#

All elements support these fields:

family: Font family name (must match a defined font)
weight: 100-900 or thin, normal, bold, etc.
style: normal or italic
size: CSS units (16px, 1rem, 0.9em)
line-height: Number or CSS unit
color: Hex value or reference to color name
background-color: Hex value or reference to color name

Simple Format (String)#

yaml · 4 LINES

typography:
  base: Open Sans
  headings: Roboto
  monospace: Fira Code

Extended Format (Object)#

yaml · 27 LINES

typography:
  base:
    family: Open Sans
    weight: 400
    size: 16px
    line-height: 1.5
  headings:
    family: Roboto
    weight: 600
    style: normal
    line-height: 1.2
    color: "#333333"
  monospace:
    family: Fira Code
    weight: 400
    size: 0.9em
  monospace-inline:
    color: "#7d12ba"
    background-color: "#f8f9fa"
  monospace-block:
    color: foreground
    background-color: background
    line-height: 1.4
  link:
    weight: 600
    color: primary
    decoration: underline

Note: Base text color uses color.foreground by default. Do not specify color in base unless overriding.

Complete Example#

yaml · 23 LINES

typography:
  fonts:
    - family: Open Sans
      source: google
      weight: [400, 600, 700]
      style: [normal, italic]
    - family: Roboto Slab
      source: google
      weight: [600, 900]
    - family: Fira Code
      source: bunny
      weight: [400, 500]
  base:
    family: Open Sans
    size: 16px
    line-height: 1.5
  headings:
    family: Roboto Slab
    weight: 600
  monospace: Fira Code
  link:
    color: primary
    weight: 600

Defaults Section#

Framework-specific customizations. Use sparingly - only when brand requirements cannot be met through the standard sections above.

Structure#

yaml · 12 LINES

defaults:
  bootstrap:      # Bootstrap/bslib customizations
    functions:    # SCSS function declarations (string)
    defaults:     # Bootstrap variable overrides (mapping)
    mixins:       # SCSS mixins (string)
    rules:        # Additional SCSS rules (string)
  quarto:         # Quarto-specific settings
    format:       # Format-specific options
  shiny:          # Shiny-specific settings
    theme:
      defaults:   # Bootstrap variables
      rules:      # Additional SCSS rules

Example#

yaml · 12 LINES

defaults:
  bootstrap:
    defaults:
      navbar-bg: $brand-orange
    rules: |
      .btn-primary {
        border-radius: 0.5rem;
      }
  shiny:
    theme:
      defaults:
        navbar-padding-y: 1rem

Note: Colors from color.palette are available as Sass variables: $brand-{color_name}

Validation Rules#

When creating _brand.yml files:

All fields are optional - only include what's needed
Prefer hex colors - use "#447099" format
Prefer simple syntax - use strings instead of objects when possible
Follow Sass naming - color/font names use lowercase and hyphens
Include URLs with protocol - always use https://
Reference before use - define colors/fonts before referencing them
Keep it concise - simpler is better

Complete Minimal Example#

yaml · 16 LINES

color:
  palette:
    blue: "#0066cc"
    gray: "#666666"
  primary: blue
  foreground: gray
  background: "#ffffff"

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

Complete Comprehensive Example#

See the example in the document provided to you (brand-yml.prompt.txt) for a full-featured _brand.yml with all options demonstrated.

Supporting file: references/quarto.md#

Using brand.yml with Quarto#

Guide for applying brand.yml styling to Quarto documents, presentations, websites, and PDFs.

Overview#

Quarto automatically integrates _brand.yml to provide unified visual styling across multiple output formats including HTML, dashboards, RevealJS presentations, and Typst PDFs.

Quick Start#

Place _brand.yml at your project root:

TEXT · 5 LINES

my-project/
├── _quarto.yml
├── _brand.yml
├── index.qmd
└── ...

Quarto automatically discovers and applies _brand.yml - no configuration needed.

Supported Formats#

Brand styling automatically applies to:

HTML documents - Web pages, reports
HTML dashboards - Interactive dashboards
RevealJS presentations - Slide decks
Typst PDFs - PDF documents via Typst
Websites - Multi-page Quarto websites

Document-Level Usage#

Specify brand in document frontmatter:

yaml · 6 LINES

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

Or use default discovery:

yaml · 4 LINES

---
title: "My Document"
format: html
---

If _brand.yml exists at project root, it's automatically applied.

Project-Level Usage#

Configure in _quarto.yml:

yaml · 7 LINES

project:
  type: website
  brand: _brand.yml

format:
  html:
    theme: default

Custom Brand File Location#

Specify a non-standard path:

yaml · 6 LINES

---
title: "My Document"
format:
  html:
    brand: branding/company-brand.yml
---

Or in project config:

yaml · 2 LINES

project:
  brand: path/to/brand.yml

Light/Dark Mode#

Specify color variants for light and dark modes:

yaml · 12 LINES

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

Any color in color or typography can have light/dark variants.

Theme Layering#

Control precedence with the "brand" keyword:

Default (Brand Lowest Priority)#

yaml · 5 LINES

format:
  revealjs:
    theme:
      - custom.scss
      - cosmo

Priority: cosmo > custom.scss > _brand.yml

Brand Highest Priority#

yaml · 6 LINES

format:
  revealjs:
    theme:
      - cosmo
      - custom.scss
      - brand

Priority: _brand.yml > custom.scss > cosmo

Brand in Middle#

yaml · 6 LINES

format:
  html:
    theme:
      - cosmo
      - brand
      - custom.scss

Priority: custom.scss > _brand.yml > cosmo

Accessing Brand Data in Documents#

Shortcodes#

Use shortcodes to access brand values (requires Quarto extensions):

markdown · 5 LINES

<!-- Access colors -->
Our primary color is {{{< brand-color primary >}}}.

<!-- Access meta information -->
Welcome to {{{< brand-meta name >}}}.

SCSS Variables#

Access brand colors in custom SCSS:

scss · 6 LINES

// Custom SCSS file
.branded-element {
  color: $brand-primary;
  background: $brand-background;
  border-color: $brand-secondary;
}

Brand colors are automatically available as Sass variables: $brand-{color-name}.

Typst PDF Support#

Brand styling works with Typst PDF output:

yaml · 6 LINES

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

Typst Color Variables#

Access colors in Typst templates:

brand-color.{name} - Palette colors (e.g., brand-color.blue, brand-color.primary)
brand-background-color.{name} - Lighter background variants

Typst Typography Support#

Element	family	weight	color	background-color	line-height
base	✓	✓	✓	-	✓
headings	✓	✓	✓	-	✓
title	✓	✓	✓	-	✓
monospace-inline	✓	✓	✓	✓	-
monospace-block	✓	✓	✓	✓	✓
link	-	✓	✓	✓	-

Typst Font Handling#

Quarto automatically downloads Google Fonts and caches them for Typst. Check fonts:

bash

quarto typst fonts --ignore-system-fonts --font-path .quarto/typst-font-cache/

Disable font fallback in Typst:

typst

#set text(fallback: false)

Complete Examples#

Simple HTML Document#

yaml · 10 LINES

---
title: "Quarterly Report"
format:
  html:
    toc: true
---

# Executive Summary

Content here uses brand colors and typography automatically.

With _brand.yml at project root:

yaml · 17 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

RevealJS Presentation#

yaml · 13 LINES

---
title: "Company Overview"
format:
  revealjs:
    theme:
      - default
      - brand
    logo: logo.png
---

# Introduction

Slides automatically use brand colors and fonts.

Website with Brand#

_quarto.yml:

yaml · 16 LINES

project:
  type: website
  brand: _brand.yml

website:
  title: "My Company"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css

Brand colors and typography apply across all pages.

Dashboard#

yaml · 12 LINES

---
title: "Sales Dashboard"
format:
  dashboard:
    brand: _brand.yml
    theme: default
---

## Row

```{python}
# Dashboard content

TEXT · 17 LINES


### Typst PDF

```yaml
---
title: "Technical Report"
format:
  typst:
    brand: _brand.yml
    margin:
      x: 2cm
      y: 2cm
---

# Overview

PDF uses brand colors and fonts via Typst.

Brand Extensions#

Create reusable brand packages:

bash

quarto create extension brand

Structure:

TEXT · 6 LINES

my-brand-extension/
├── _extension.yml
├── brand.yml
├── logo.png
└── fonts/
    └── ...

_extension.yml:

yaml · 5 LINES

title: Company Brand
author: Your Name
version: 1.0.0
contributes:
  brand: brand.yml

Install extension in projects:

bash

quarto add username/my-brand-extension

Requirement: Brand extensions need _quarto.yml project file.

Sample _brand.yml for Quarto#

Minimal example:

yaml · 21 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 1rem
    line-height: 1.6
  headings:
    family: Inter
    weight: 600
    line-height: 1.2

Complete example with light/dark mode:

yaml · 52 LINES

meta:
  name: My Company
  link: https://mycompany.com

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

color:
  palette:
    blue: "#0066cc"
    navy: "#003366"
    gray: "#666666"
    light-gray: "#f5f5f5"
  primary: blue
  secondary: gray
  success: "#28a745"
  info: blue
  warning: "#ffc107"
  danger: "#dc3545"
  foreground:
    light: navy
    dark: "#e0e0e0"
  background:
    light: "#ffffff"
    dark: "#1a1a1a"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 500, 600, 700]
      style: [normal, italic]
    - family: Fira Code
      source: google
      weight: [400, 500]
  base:
    family: Inter
    size: 1rem
    line-height: 1.6
  headings:
    family: Inter
    weight: 600
    line-height: 1.2
  monospace:
    family: Fira Code
    size: 0.9em
  link:
    color: primary
    weight: 500

Tips#

Automatic discovery: Place _brand.yml at project root for automatic application
Light/dark variants: Use for websites with theme toggles
Layer strategically: Use brand keyword to control theme precedence
Test across formats: Verify brand applies correctly to HTML, PDF, and presentations
Extension for reuse: Create brand extensions for multi-project consistency
Version control: Include _brand.yml in git repository

Troubleshooting#

Brand not applying?

Verify file is named _brand.yml (with underscore)
Check file is at project root or specified in brand: field
Ensure _quarto.yml exists for project-level branding
Try explicit path in frontmatter

Colors not matching?

Ensure hex colors have quotes: "#0066cc"
Check color references match palette definitions
Verify theme layering order

Fonts not loading?

Verify Google Fonts spelling
Check internet connection (required for Google Fonts)
For Typst, check font cache: quarto typst fonts
Ensure source: google is specified correctly

Typst-specific issues?

Check font cache path: .quarto/typst-font-cache/
Add #set text(fallback: false) to debug font issues
Verify typography properties are supported (see table above)

Brand extension not working?

Ensure _quarto.yml exists in project
Verify extension is installed: quarto list extensions
Check extension contributes brand: look for contributes.brand in _extension.yml

Supporting file: references/shiny-python.md#

Using brand.yml with Shiny for Python#

Guide for applying brand.yml styling to Shiny for Python applications using ui.Theme.

Overview#

Shiny for Python integrates brand.yml through the ui.Theme.from_brand() method, which creates custom themes from _brand.yml files. This enables consistent branding across Shiny apps with minimal configuration.

Installation#

bash · 8 LINES

# Install Shiny with theme support
pip install "shiny[theme]"

# Or install separately
pip install shiny libsass

# Optional: Install brand_yml for programmatic access
pip install brand_yml

Quick Start#

Automatic Discovery#

Place _brand.yml at your app directory root:

TEXT · 4 LINES

my-app/
├── _brand.yml
├── app.py
└── ...

Then use ui.Theme.from_brand():

Shiny Express:

python · 5 LINES

from shiny.express import ui

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

# ... rest of app

Shiny Core:

python · 12 LINES

from shiny import App, ui

app_ui = ui.page_fluid(
    ui.Theme.from_brand(__file__),
    ui.h2("My App"),
    # ... rest of UI
)

def server(input, output, session):
    pass

app = App(app_ui, server)

ui.Theme.from_brand() Parameters#

python

ui.Theme.from_brand(brand)

The brand parameter accepts:

File Path (Most Common)#

python · 8 LINES

# Use __file__ for app directory
ui.Theme.from_brand(__file__)

# Explicit file path
ui.Theme.from_brand("path/to/_brand.yml")

# Explicit directory (auto-finds _brand.yml)
ui.Theme.from_brand("branding/")

Brand Object#

python · 4 LINES

from brand_yml import Brand

brand = Brand.from_yaml("_brand.yml")
ui.Theme.from_brand(brand)

Search Behavior#

When given __file__ or a directory path, the method searches for _brand.yml:

In the specified directory
In _brand/ subdirectory
In brand/ subdirectory
In parent directories (recursive)

Complete Examples#

Shiny Express App#

python · 19 LINES

from shiny.express import input, render, ui

ui.page_opts(
    title="My Dashboard",
    theme=ui.Theme.from_brand(__file__)
)

with ui.sidebar():
    ui.input_slider("n", "Number of observations", 1, 100, 50)

@render.plot
def histogram():
    import matplotlib.pyplot as plt
    import numpy as np

    data = np.random.randn(input.n())
    plt.hist(data, bins=20)
    plt.xlabel("Value")
    plt.ylabel("Frequency")

Shiny Core App#

python · 23 LINES

from shiny import App, render, ui

app_ui = ui.page_sidebar(
    ui.sidebar(
        ui.input_slider("n", "Number of observations", 1, 100, 50),
    ),
    ui.output_plot("histogram"),
    title="My Dashboard",
    theme=ui.Theme.from_brand(__file__)
)

def server(input, output, session):
    @render.plot
    def histogram():
        import matplotlib.pyplot as plt
        import numpy as np

        data = np.random.randn(input.n())
        plt.hist(data, bins=20)
        plt.xlabel("Value")
        plt.ylabel("Frequency")

app = App(app_ui, server)

With Custom Path#

python · 10 LINES

from shiny.express import ui

# Shared brand file
ui.page_opts(theme=ui.Theme.from_brand("../shared-branding/_brand.yml"))

# Named brand file
ui.page_opts(theme=ui.Theme.from_brand("company-brand.yml"))

# Directory with _brand.yml inside
ui.page_opts(theme=ui.Theme.from_brand("branding/"))

Multiple Page Types#

python · 30 LINES

from shiny import App, ui

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

# page_sidebar
app_ui = ui.page_sidebar(
    theme=ui.Theme.from_brand(__file__),
    ui.sidebar(
        # ... sidebar content
    ),
    # ... main content
)

# page_navbar
app_ui = ui.page_navbar(
    ui.nav_panel("Tab 1", # ...),
    ui.nav_panel("Tab 2", # ...),
    title="My App",
    theme=ui.Theme.from_brand(__file__)
)

# page_fillable
app_ui = ui.page_fillable(
    theme=ui.Theme.from_brand(__file__),
    # ... content
)

Combining with Custom Theme Rules#

Extend brand.yml themes with custom Sass:

python · 13 LINES

from shiny.express import ui

theme = (
    ui.Theme.from_brand(__file__)
    .add_rules("""
        .custom-card {
            border-radius: 0.5rem;
            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        }
    """)
)

ui.page_opts(theme=theme)

Available theme methods (chainable):

.add_defaults() - Override Bootstrap variables
.add_functions() - Add Sass functions
.add_mixins() - Add Sass mixins
.add_rules() - Add CSS rules
.add_uses() - Add Sass declarations

Programmatic Access with brand_yml#

For advanced use cases, access brand data programmatically:

python · 28 LINES

from brand_yml import Brand

# Read brand file
brand = Brand.from_yaml("_brand.yml")

# Or from string
yaml_content = """
color:
  palette:
    blue: "#0066cc"
  primary: blue
"""
brand = Brand.from_yaml_str(yaml_content)

# Access brand elements
brand.meta.name                    # Organization name
brand.color.palette.blue           # "#0066cc"
brand.color.primary                # "blue"
brand.typography.base.family       # Font family name

# Use in UI
from shiny import ui

app_ui = ui.page_fluid(
    theme=ui.Theme.from_brand(brand),
    ui.h2(brand.meta.name),
    # ... more content
)

Sample _brand.yml for Shiny#

Minimal example:

yaml · 19 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

More complete example:

yaml · 39 LINES

meta:
  name: My Company
  link: https://mycompany.com

color:
  palette:
    blue: "#0066cc"
    navy: "#003366"
    gray: "#666666"
    light-gray: "#f5f5f5"
  primary: blue
  secondary: gray
  success: "#28a745"
  info: blue
  warning: "#ffc107"
  danger: "#dc3545"
  foreground: navy
  background: "#ffffff"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 500, 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
    line-height: 1.2
  monospace:
    family: Fira Code
    size: 14px

Tips#

Use file: Most reliable way to locate _brand.yml in app directory
Start simple: Begin with colors and one font
Test paths: If brand doesn't apply, try explicit paths
Version control: Include _brand.yml in git repository
Precompile for production: Use .to_css() to avoid runtime Sass compilation

python · 6 LINES

# Development
theme = ui.Theme.from_brand(__file__)

# Production (precompile)
theme_css = ui.Theme.from_brand(__file__).to_css()
# Save to static/theme.css, then reference in production

Troubleshooting#

Theme not applying?

Check file is named _brand.yml (with underscore)
Verify libsass is installed: pip install libsass
Try explicit path: ui.Theme.from_brand("path/to/_brand.yml")
Check for YAML syntax errors

Colors not matching?

Ensure hex colors have quotes: "#0066cc"
Verify color names match palette definitions
Check semantic colors reference valid palette names

Fonts not loading?

Verify Google Fonts spelling and availability
Ensure source: google is specified
Check font family names match exactly
Internet connection required for Google Fonts

Import errors?

Install theme support: pip install "shiny[theme]"
Or install libsass separately: pip install libsass

Performance Considerations#

For production apps with many instances, precompile the theme:

python · 11 LINES

# build_theme.py
from shiny import ui

theme = ui.Theme.from_brand("_brand.yml")
css = theme.to_css()

with open("static/brand-theme.css", "w") as f:
    f.write(css)

# Then in app.py, reference the CSS file directly
# This avoids runtime Sass compilation overhead

Supporting file: references/shiny-r.md#

Using brand.yml with Shiny for R#

Guide for applying brand.yml styling to Shiny applications using the bslib package.

Overview#

The bslib package integrates brand.yml to provide unified visual theming across Shiny applications. Define colors, fonts, and logos once in _brand.yml, and bslib automatically applies them to your Shiny app UI.

Installation#

r · 5 LINES

# Install bslib (includes brand.yml support)
install.packages("bslib")

# Optional: Install brand.yml package for theming plots/tables
install.packages("brand.yml")

Quick Start#

Automatic Discovery#

Place _brand.yml at your app directory root:

TEXT · 4 LINES

my-app/
├── _brand.yml
├── app.R
└── ...

Then use bs_theme() in your app:

r · 14 LINES

library(shiny)
library(bslib)

ui <- page_fluid(
  theme = bs_theme(),  # Automatically finds _brand.yml
  titlePanel("My App"),
  # ... rest of UI
)

server <- function(input, output, session) {
  # ...
}

shinyApp(ui, server)

Search Paths#

bslib automatically searches for _brand.yml in this order:

Current app directory
_brand/ subdirectory
brand/ subdirectory
Parent directories (recursive)

bs_theme() Brand Parameter#

The brand parameter controls how branding is applied:

Automatic (Default)#

theme = bs_theme()

Searches for _brand.yml and applies it if found. No error if file doesn't exist.

Required Brand#

theme = bs_theme(brand = TRUE)

Requires _brand.yml to exist. Throws error if not found.

Explicit Path#

theme = bs_theme(brand = "path/to/my-brand.yml")

Uses specific brand file. Path can be:

Relative to app directory: "branding/company-brand.yml"
Absolute: "/Users/name/brands/company.yml"
Directory (auto-finds _brand.yml): "branding/"

Inline Brand Definition#

r · 18 LINES

theme = bs_theme(
  brand = list(
    color = list(
      palette = list(
        blue = "#0066cc",
        gray = "#666666"
      ),
      primary = "blue",
      foreground = "gray"
    ),
    typography = list(
      fonts = list(
        list(family = "Inter", source = "google", weight = c(400, 600))
      ),
      base = "Inter"
    )
  )
)

Disable Branding#

theme = bs_theme(brand = FALSE)

Ignores _brand.yml even if it exists.

Using with page_*() Functions#

All bslib page functions support automatic brand discovery:

r · 27 LINES

# page_fluid
ui <- page_fluid(
  theme = bs_theme(),
  # ... content
)

# page_sidebar
ui <- page_sidebar(
  theme = bs_theme(),
  sidebar = sidebar(
    # ... sidebar content
  ),
  # ... main content
)

# page_navbar
ui <- page_navbar(
  theme = bs_theme(),
  nav_panel("Tab 1", # ...),
  nav_panel("Tab 2", # ...)
)

# page_fillable
ui <- page_fillable(
  theme = bs_theme(),
  # ... content
)

Branded Plots and Tables in Shiny#

Use theming functions from the brand.yml package to style plots and tables within Shiny apps. See brand-yml-in-r.md for complete documentation of theming functions.

Basic Example#

r · 38 LINES

library(shiny)
library(bslib)
library(ggplot2)
library(gt)
library(brand.yml)

ui <- page_sidebar(
  theme = bs_theme(brand = TRUE),

  sidebar = sidebar(
    selectInput("dataset", "Dataset:", c("mtcars", "iris"))
  ),

  card(
    card_header("Branded Plot"),
    plotOutput("plot")
  ),
  card(
    card_header("Branded Table"),
    gt_output("table")
  )
)

server <- function(input, output, session) {
  output$plot <- renderPlot({
    ggplot(mtcars, aes(mpg, hp)) +
      geom_point() +
      theme_brand_ggplot2()
  })

  output$table <- render_gt({
    head(mtcars) |>
      gt() |>
      theme_brand_gt()
  })
}

shinyApp(ui, server)

Benefits:

Consistent styling across UI, plots, and tables
Automatic brand detection from _brand.yml
Works with ggplot2, gt, flextable, plotly, and base R graphics

For detailed theming function documentation, see brand-yml-in-r.md.

Complete Shiny Example#

r · 39 LINES

library(shiny)
library(bslib)

ui <- page_sidebar(
  theme = bs_theme(brand = TRUE),  # Require _brand.yml

  sidebar = sidebar(
    title = "Controls",
    selectInput("dataset", "Dataset:",
                choices = c("iris", "mtcars")),
    numericInput("n", "Number of rows:", 10, min = 1, max = 50)
  ),

  card(
    card_header("Data Summary"),
    tableOutput("summary")
  ),

  card(
    card_header("Data Details"),
    verbatimTextOutput("details")
  )
)

server <- function(input, output, session) {
  dataset <- reactive({
    get(input$dataset)
  })

  output$summary <- renderTable({
    head(dataset(), input$n)
  })

  output$details <- renderPrint({
    summary(dataset())
  })
}

shinyApp(ui, server)

With _brand.yml:

yaml · 19 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

R Markdown Shiny Documents#

Use brand.yml in R Markdown documents with Shiny runtime:

yaml · 9 LINES

---
title: "Interactive Dashboard"
output:
  html_document:
    theme:
      version: 5          # Required for brand.yml
      brand: true         # Auto-discover _brand.yml
runtime: shiny
---

Or specify a path:

yaml · 9 LINES

---
title: "Interactive Dashboard"
output:
  html_document:
    theme:
      version: 5
      brand: "path/to/brand.yml"
runtime: shiny
---

Important: Set version: 5 to use Bootstrap 5, which has the best brand.yml support.

Note: For R Markdown documents without runtime: shiny, see brand-yml-in-r.md.

Programmatic Brand Access#

For advanced use cases, access brand data programmatically within Shiny:

r · 22 LINES

library(brand.yml)

server <- function(input, output, session) {
  # Read brand data
  brand <- read_brand_yml()

  # Use in custom UI elements
  output$brand_info <- renderUI({
    div(
      style = paste0("color: ", brand$color$primary, ";"),
      h3(brand$meta$name),
      p("Welcome to our branded app!")
    )
  })

  # Use in plots with custom styling
  output$custom_plot <- renderPlot({
    plot(mtcars$mpg, mtcars$hp,
         col = brand$color$primary,
         pch = 19)
  })
}

For complete documentation on programmatic access and theming functions, see brand-yml-in-r.md.

Tips#

Start simple: Begin with colors and one font family
Test automatically: Automatic discovery works well for most cases
Use explicit paths: For shared brand files across multiple apps
Version control: Include _brand.yml in your git repository
Validate early: Use brand = TRUE during development to catch missing files
Combine with theming functions: Style plots and tables consistently (see brand-yml-in-r.md)

Troubleshooting#

Brand not applying to Shiny UI?

Check file is named _brand.yml (with underscore)
Verify file is in app directory or parent directories
Try explicit path: bs_theme(brand = "path/to/_brand.yml")
Check for YAML syntax errors

Colors not matching?

Verify hex colors have quotes: "#0066cc"
Check color names match palette definitions
Ensure primary/secondary colors reference valid palette names

Fonts not loading?

Verify Google Fonts spelling and availability
Check source: google is specified correctly
Ensure font family names match exactly in typography elements

Plots/tables not branded?

Ensure brand.yml package is installed: install.packages("brand.yml")
Use theming functions: theme_brand_ggplot2(), theme_brand_gt(), etc.
See brand-yml-in-r.md for complete theming documentation

brand-yml-in-r.md (opens in a new tab): General R usage, R Markdown integration, theming functions, and programmatic access
brand-yml-spec.md (opens in a new tab): Complete brand.yml file specification

SHOWING THE FIRST PART OF 54 KB · THE FULL TEXT IS ON THIS PAGE

§06

FAQ

07 QUESTIONS

01What is the Brand yml agent skill?

Create and use brand.yml files for consistent branding across Shiny applications and Quarto documents. It is listed under brand in the 100xLab agent skills directory.

02How do I install Brand yml in Cursor, Claude Code, or Codex?

Run npx skills add posit-dev/skills --skill brand-yml in the project where you want it, then ask your agent for the skill by name. The --skill flag installs only Brand yml, not every skill in the repository.

03What does the Brand yml SKILL.md cover?

The SKILL.md includes sections on What is brand.yml?, File Naming Convention, Decision Tree, Creating brand.yml Files, Step 1: Gather Information and Step 2: Read the Specification. Read the full text on this page or in plain markdown at /resources/agent-skills/posit-dev-skills--brand-yml--j9s9d7/raw.

04Which agents can use Brand yml?

Brand yml installs with the cross-agent skills installer (npx skills add), which sets it up for agents such as Claude Code, Cursor and Codex. Each agent loads the SKILL.md when you ask for the skill by name.

05What license is Brand yml under?

The posit-dev/skills repository declares the MIT license. Read the license file in the repository before you copy or redistribute the skill.

06Is Brand yml free to use?

Reading, copying and installing Brand yml costs nothing: it is published in a public GitHub repository under the MIT license. Reuse and redistribution follow that license.

07Where is the source of Brand yml?

Brand yml comes from https://github.com/posit-dev/skills, which has 415 GitHub stars. The SKILL.md is at https://github.com/posit-dev/skills/blob/HEAD/brand-yml/SKILL.md. The author is posit-dev.

Need an agent workflow built around your stack?

Tell us the workflow you want automated. We reply within 4 working hours (IST).

BOOK A CALL

§09

ATTRIBUTION

Brand yml was written by its original authors and is published in posit-dev/skills (opens GitHub in a new tab) under the MIT license. All rights stay with the original authors.

100xLab did not write, maintain or endorse this skill. This page lists it for discovery. Repo stars belong to the source repository, not to the skill. Review any skill before you install it.

AGENT SKILLBY POSIT-DEV

Brand yml

AT A GLANCE

FIG. 01 · BRAND

SOURCE REPOSITORY: posit-dev/skills (opens GitHub in a new tab)
REPO STARS: SOURCE REPOSITORY
LICENSE: MIT
CATEGORIES: Brand
SKILL.MD SIZE: 54 KB2,529 LINES

§03

QUICK ANSWER

WHAT IT IS01: Create and use brand.yml files for consistent branding across Shiny applications and Quarto documents. It stands out by giving brand and messaging a defined shape, so the agent asks for better context and returns a more usable result.
INPUTS02: Context for brand and messaging: your goals, audience, constraints, and any source material the skill asks for.
OUTPUT03: A ready-to-use result for brand and messaging: the analysis, copy, or recommendations the agent produces.

§04

INSTALL

One command adds this skill from its source repository.

$ npx skills add posit-dev/skills --skill brand-yml

READ THE SKILL.MD BELOW BEFORE YOU RUN IT. SKILLS INSTRUCT YOUR AGENT.

§05

SKILL.MD

The full file, as published in the source repository. Copy it, download it or open it on GitHub.

Download SKILL.md Open on GitHub View raw markdown

ON THIS PAGE · 84

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:

Creating a new _brand.yml file? → Follow "Creating brand.yml Files"
Using brand.yml in Shiny for R? → Read references/shiny-r.md
Using brand.yml in Shiny for Python? → Read references/shiny-python.md
Using brand.yml in Quarto? → Read references/quarto.md
Using brand.yml in R (general)? → Read references/brand-yml-in-r.md (R Markdown, theming functions, programmatic access)
Modifying existing _brand.yml? → Follow "Modifying Existing Files"
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:

yaml · 12 LINES

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:

yaml · 10 LINES

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:

yaml · 17 LINES

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:

yaml · 4 LINES

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

Add meta information:

yaml · 3 LINES

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:

Read the current file to understand existing structure
Consult brand-yml-spec.md for valid field options
Maintain consistency with existing naming patterns
Preserve references - if other colors/elements reference a name, update consistently
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:

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

Quick example:

r · 7 LINES

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:

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

Quick example (Shiny Express):

python · 3 LINES

from shiny.express import ui

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

Quick example (Shiny Core):

python · 6 LINES

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:

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

Quick example (document):

yaml · 6 LINES

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

Quick example (project in _quarto.yml):

yaml · 6 LINES

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#

yaml · 10 LINES

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#

yaml · 9 LINES

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#

yaml · 12 LINES

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#

yaml · 9 LINES

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

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)

Supporting file: references/brand-yml-in-r.md#

Using brand.yml in R#

Guide for using brand.yml in R projects beyond Shiny, including R Markdown documents, theming functions for plots and tables, and programmatic access to brand data.

Overview#

Installation#

r · 2 LINES

# Install brand.yml package
install.packages("brand.yml")

R Markdown Integration#

Use brand.yml in R Markdown documents (without runtime: shiny):

yaml · 8 LINES

---
title: "My Report"
output:
  html_document:
    theme:
      version: 5          # Required for brand.yml
      brand: true         # Auto-discover _brand.yml
---

Or specify a path:

yaml · 8 LINES

---
title: "My Report"
output:
  html_document:
    theme:
      version: 5
      brand: "path/to/brand.yml"
---

Important: Set version: 5 to use Bootstrap 5, which has the best brand.yml support.

Other R Markdown Formats#

Brand.yml works with various R Markdown output formats:

yaml · 9 LINES

---
title: "Branded Report"
output:
  html_document:
    theme:
      version: 5
      brand: _brand.yml
  pdf_document: default
---

Programmatic Access#

Read and access brand data programmatically in any R script or document:

r · 18 LINES

library(brand.yml)

# Read from default location (_brand.yml in project)
brand <- read_brand_yml()

# Read from specific path
brand <- read_brand_yml("path/to/brand.yml")

# Access brand elements
brand$color$palette$blue          # "#447099"
brand$color$primary               # blue -> "#447099"
brand$typography$base$family      # "Open Sans"
brand$meta$name                   # "Company Name"

# Access all colors
brand$color$palette               # List of all palette colors
brand$color$foreground            # Foreground color
brand$color$background            # Background color

Use programmatically accessed brand data to:

Display brand colors in custom visualizations
Show brand logo with correct paths
Apply brand fonts to custom elements
Build branded themes dynamically
Generate branded reports programmatically

Branded Theming Functions#

The brand.yml package includes helper functions to apply brand colors to plots and tables from popular R packages. These functions work in any R context (scripts, R Markdown, Quarto, Shiny).

theme_brand_ggplot2()#

Apply brand colors to ggplot2 visualizations:

r · 21 LINES

library(ggplot2)
library(brand.yml)

# Automatic brand detection
ggplot(mtcars, aes(mpg, hp)) +
  geom_point() +
  theme_brand_ggplot2()

# Explicit brand file
ggplot(mtcars, aes(mpg, hp)) +
  geom_point() +
  theme_brand_ggplot2(brand = "_brand.yml")

# Override specific colors
ggplot(mtcars, aes(mpg, hp)) +
  geom_point() +
  theme_brand_ggplot2(
    background = "white",
    foreground = "brand-gray",
    accent = "brand-blue"
  )

Parameters:

brand: NULL (auto-detect), file path, brand object, or FALSE
background, foreground, accent: Primary color settings
base_size: Base font size (default: 11)
Additional parameters for fine-grained control: title_color, line_color, rect_fill, panel_background_fill, panel_grid_major_color, etc.

theme_brand_gt()#

Apply brand colors to gt tables:

r · 23 LINES

library(gt)
library(brand.yml)

# Create branded table
mtcars |>
  head() |>
  gt() |>
  theme_brand_gt()

# With explicit brand
mtcars |>
  head() |>
  gt() |>
  theme_brand_gt(brand = "_brand.yml")

# Override colors
mtcars |>
  head() |>
  gt() |>
  theme_brand_gt(
    background = "white",
    foreground = "brand-gray"
  )

Parameters:

table: The gt table object to theme
brand: NULL (auto-detect), file path, brand object, or FALSE
background: Table background color (default: brand.color.background)
foreground: Text color (default: brand.color.foreground)

theme_brand_flextable()#

Apply brand colors to flextable tables:

r · 23 LINES

library(flextable)
library(brand.yml)

# Create branded flextable
mtcars |>
  head() |>
  flextable() |>
  theme_brand_flextable()

# With explicit brand
mtcars |>
  head() |>
  flextable() |>
  theme_brand_flextable(brand = "_brand.yml")

# Override colors
mtcars |>
  head() |>
  flextable() |>
  theme_brand_flextable(
    background = "white",
    foreground = "brand-gray"
  )

Parameters:

table: The flextable object to theme
brand: NULL (auto-detect), file path, brand object, or FALSE
background: Table background color (default: brand.color.background)
foreground: Text color (default: brand.color.foreground)

theme_brand_plotly()#

Apply brand colors to plotly visualizations:

r · 18 LINES

library(plotly)
library(brand.yml)

# Create branded plotly chart
plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers") |>
  theme_brand_plotly()

# With explicit brand
plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers") |>
  theme_brand_plotly(brand = "_brand.yml")

# Override colors
plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers") |>
  theme_brand_plotly(
    background = "white",
    foreground = "brand-gray",
    accent = "brand-blue"
  )

Parameters:

plot: The plotly plot object to theme
brand: NULL (auto-detect), file path, brand object, or FALSE
background: Plot background color (default: brand.color.background)
foreground: Text/foreground color (default: brand.color.foreground)
accent: Accent/highlight color (default: brand.color.primary)

theme_brand_thematic()#

Apply brand colors to base R graphics via thematic:

r · 16 LINES

library(thematic)
library(brand.yml)

# Create theme object
theme <- theme_brand_thematic()

# Use with thematic_with_theme()
thematic::thematic_with_theme(theme, {
  plot(mtcars$mpg, mtcars$hp)
})

# Or use with ggplot2
thematic::thematic_with_theme(theme, {
  ggplot(mtcars, aes(mpg, hp)) +
    geom_point()
})

theme_brand_thematic_on()#

Immediately activate brand theming globally for base R graphics:

r · 12 LINES

library(thematic)
library(brand.yml)

# Turn on brand theming globally
theme_brand_thematic_on()

# Now all plots use brand colors
plot(mtcars$mpg, mtcars$hp)
hist(mtcars$mpg)

# Turn off later
thematic::thematic_off()

Parameters (both functions):

brand: NULL (auto-detect), file path, brand object, or FALSE
background: Background color (default: brand.color.background)
foreground: Foreground color (default: brand.color.foreground)
accent: Accent color (default: brand.color.primary)
...: Additional arguments passed to thematic package

Difference:

theme_brand_thematic(): Returns theme object for scoped use
theme_brand_thematic_on(): Immediately applies theme globally

R Markdown Example#

Complete example showing theming functions in R Markdown:

markdown · 33 LINES

---
title: "Branded Report"
output:
  html_document:
    theme:
      version: 5
      brand: _brand.yml
---

```{r setup}
library(ggplot2)
library(gt)
library(brand.yml)
```

## Sales Analysis

```{r plot}
ggplot(mtcars, aes(mpg, hp, color = factor(cyl))) +
  geom_point(size = 3) +
  labs(title = "MPG vs Horsepower", color = "Cylinders") +
  theme_brand_ggplot2()
```

## Data Summary

```{r table}
mtcars |>
  head(10) |>
  gt() |>
  theme_brand_gt() |>
  tab_header(title = "Motor Trend Car Data")
```

Quarto Integration#

Works seamlessly in Quarto documents:

markdown · 16 LINES

---
title: "Branded Analysis"
format:
  html:
    brand: _brand.yml
---

```{r}
#| label: branded-plot
library(ggplot2)
library(brand.yml)

ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
  geom_point() +
  theme_brand_ggplot2()
```

Script Usage#

Use in standalone R scripts:

r · 15 LINES

#!/usr/bin/env Rscript

library(brand.yml)
library(ggplot2)

# Read brand
brand <- read_brand_yml("_brand.yml")

# Create branded plot
p <- ggplot(mtcars, aes(mpg, hp)) +
  geom_point(color = brand$color$primary) +
  theme_brand_ggplot2()

# Save with brand colors
ggsave("output.png", p, width = 8, height = 6)

Benefits#

Consistency: Same brand styling across all R outputs (plots, tables, documents)
Automatic detection: Functions find _brand.yml automatically
Flexible override: Easy to customize colors when needed
Works everywhere: R scripts, R Markdown, Quarto, Shiny

Tips#

Place _brand.yml at project root for automatic discovery
Use read_brand_yml() for programmatic access to brand data
Combine theming functions for cohesive branded reports
Set version: 5 in R Markdown YAML for Bootstrap 5 support
Test theme functions individually before combining in documents

Common Patterns#

Branded Report with Multiple Visualizations#

r · 19 LINES

library(brand.yml)
library(ggplot2)
library(gt)

# Load brand
brand <- read_brand_yml()

# Create consistent visualizations
plot1 <- ggplot(data1, aes(x, y)) +
  geom_point() +
  theme_brand_ggplot2()

plot2 <- ggplot(data2, aes(x, y)) +
  geom_line() +
  theme_brand_ggplot2()

table1 <- data3 |>
  gt() |>
  theme_brand_gt()

Dynamic Brand Colors#

r · 13 LINES

library(brand.yml)

brand <- read_brand_yml()

# Use brand colors in custom visualizations
my_colors <- c(
  brand$color$primary,
  brand$color$secondary,
  brand$color$success
)

# Apply to plot
plot(data, col = my_colors[factor(group)])

Conditional Branding#

r · 11 LINES

library(brand.yml)

# Use different brands for different contexts
if (Sys.getenv("BRAND_MODE") == "internal") {
  brand <- read_brand_yml("internal-brand.yml")
} else {
  brand <- read_brand_yml("external-brand.yml")
}

# Apply to visualizations
theme <- theme_brand_ggplot2(brand = brand)

Supporting file: references/brand-yml-spec.md#

brand.yml Specification#

Complete specification for creating valid _brand.yml files for the brand.yml project.

File Naming Convention#

Conventional name: _brand.yml (auto-discovered by Shiny and Quarto)
Custom names: Any .yml file (e.g., my-brand.yml) requires explicit paths
Location: Typically at project root or in _brand/ or brand/ subdirectories

File Structure#

All fields are optional. Only include fields directly relevant to the brand.

yaml · 5 LINES

meta:           # Company/project identity information
logo:           # Logo files and variants
color:          # Color palette and semantic colors
typography:     # Fonts and text styling
defaults:       # Framework-specific customizations

Meta Section#

Company or project metadata.

Simple Format#

yaml · 3 LINES

meta:
  name: Acme
  link: https://acmecorp.com

Extended Format#

yaml · 13 LINES

meta:
  name:
    short: Acme
    full: Acme Corporation International
  link:
    home: https://www.acmecorp.com
    docs: https://docs.acmecorp.com
    github: https://github.com/acmecorp
    bluesky: https://bsky.app/profile/acmecorp.bsky.social
    mastodon: https://mastodon.social/@acmecorp
    linkedin: https://www.linkedin.com/company/acmecorp
    facebook: https://www.facebook.com/acmecorp
    twitter: https://twitter.com/acmecorp

Requirements:

All links must include https:// prefix
Additional custom fields are allowed

Logo Section#

Logo files for different contexts and sizes.

Structure#

yaml · 6 LINES

logo:
  images:           # Named logo resources (optional)
    name: path      # Map names to file paths or URLs
  small: path       # Icon-sized logo (favicons, mobile)
  medium: path      # Standard logo (headers, navigation)
  large: path       # Large logo (hero, title slides)

File Paths#

Local files: Relative paths from _brand.yml location (e.g., logos/logo.png)
Remote files: Full URLs with http:// or https://

Light/Dark Variants#

yaml · 4 LINES

logo:
  medium:
    light: logo-dark.png      # For light backgrounds
    dark: logo-white.png      # For dark backgrounds

With Alt Text#

yaml · 6 LINES

logo:
  images:
    header:
      path: logos/header.svg
      alt: Company logo
  medium: header

Complete Example#

yaml · 13 LINES

logo:
  images:
    header: logos/header-logo.png
    header-white: logos/header-logo-white.png
    icon: logos/icon.png
    full:
      path: logos/full-logo.svg
      alt: Acme Corporation logo
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Color Section#

Brand color palette and semantic color assignments.

Structure#

yaml · 15 LINES

color:
  palette:        # Named brand colors
    name: "#hex"  # Flat list of color names and hex values
  # Semantic theme colors (all optional)
  foreground: "#color"    # Main text color
  background: "#color"    # Main background color
  primary: "#color"       # Links, buttons, primary actions
  secondary: "#color"     # Lighter text, disabled states
  tertiary: "#color"      # Hover states, accents
  success: "#color"       # Positive actions
  info: "#color"          # Neutral information
  warning: "#color"       # Cautions
  danger: "#color"        # Errors, negative actions
  light: "#color"         # High contrast on dark
  dark: "#color"          # High contrast on light

Color Palette Best Practices#

Use hex color values: "#447099"
Use descriptive names following Sass conventions: blue, brand-orange, success-green
Create aliases by referencing other palette colors: purple: burgundy
Include Bootstrap color names when possible: blue, indigo, purple, pink, red, orange, yellow, green, teal, cyan, white, black
When brands define ranges of shades, choose the midpoint as the primary color

Referencing Colors#

Theme colors can reference palette names:

yaml · 6 LINES

color:
  palette:
    brand-blue: "#447099"
    brand-orange: "#EE6331"
  primary: brand-blue      # References palette
  warning: brand-orange    # References palette

Complete Example#

yaml · 16 LINES

color:
  palette:
    white: "#FFFFFF"
    black: "#151515"
    blue: "#447099"
    orange: "#EE6331"
    green: "#72994E"
    teal: "#419599"
    burgundy: "#9A4665"
  foreground: black
  background: white
  primary: blue
  success: green
  info: teal
  warning: orange
  danger: burgundy

Typography Section#

Font definitions and text element styling.

Structure#

yaml · 11 LINES

typography:
  fonts:              # Font definitions
    - family: Name
      source: type    # file, google, bunny, or system
      # Additional source-specific fields
  base:               # Body text (optional)
  headings:           # Heading text (optional)
  monospace:          # Code text (optional)
  monospace-inline:   # Inline code (optional)
  monospace-block:    # Code blocks (optional)
  link:               # Hyperlinks (optional)

Font Sources#

Local/Remote Files#

yaml · 13 LINES

fonts:
  - family: Open Sans
    source: file
    files:
      - path: fonts/OpenSans-Regular.ttf
        weight: 400
        style: normal
      - path: fonts/OpenSans-Bold.ttf
        weight: 700
        style: normal
      - path: https://example.com/fonts/OpenSans-Italic.ttf
        weight: 400
        style: italic

Proprietary fonts, should be downloaded and stored adjacent to the brand.yml file and referenced via relative paths in the path field.

Google Fonts#

yaml · 6 LINES

fonts:
  - family: Roboto
    source: google
    weight: [400, 700]        # Optional: specific weights
    style: [normal, italic]   # Optional: specific styles
    display: block            # Optional: font-display property

Weight options:

Array of numbers: [400, 700]
Range (variable fonts): 400..900
Named weights: [thin, normal, bold]

yaml · 5 LINES

fonts:
  - family: Inter
    source: bunny
    weight: [400, 600]
    style: [normal, italic]

Same syntax as Google Fonts.

Typographic Elements#

All elements support these fields:

family: Font family name (must match a defined font)
weight: 100-900 or thin, normal, bold, etc.
style: normal or italic
size: CSS units (16px, 1rem, 0.9em)
line-height: Number or CSS unit
color: Hex value or reference to color name
background-color: Hex value or reference to color name

Simple Format (String)#

yaml · 4 LINES

typography:
  base: Open Sans
  headings: Roboto
  monospace: Fira Code

Extended Format (Object)#

yaml · 27 LINES

typography:
  base:
    family: Open Sans
    weight: 400
    size: 16px
    line-height: 1.5
  headings:
    family: Roboto
    weight: 600
    style: normal
    line-height: 1.2
    color: "#333333"
  monospace:
    family: Fira Code
    weight: 400
    size: 0.9em
  monospace-inline:
    color: "#7d12ba"
    background-color: "#f8f9fa"
  monospace-block:
    color: foreground
    background-color: background
    line-height: 1.4
  link:
    weight: 600
    color: primary
    decoration: underline

Note: Base text color uses color.foreground by default. Do not specify color in base unless overriding.

Complete Example#

yaml · 23 LINES

typography:
  fonts:
    - family: Open Sans
      source: google
      weight: [400, 600, 700]
      style: [normal, italic]
    - family: Roboto Slab
      source: google
      weight: [600, 900]
    - family: Fira Code
      source: bunny
      weight: [400, 500]
  base:
    family: Open Sans
    size: 16px
    line-height: 1.5
  headings:
    family: Roboto Slab
    weight: 600
  monospace: Fira Code
  link:
    color: primary
    weight: 600

Defaults Section#

Framework-specific customizations. Use sparingly - only when brand requirements cannot be met through the standard sections above.

Structure#

yaml · 12 LINES

defaults:
  bootstrap:      # Bootstrap/bslib customizations
    functions:    # SCSS function declarations (string)
    defaults:     # Bootstrap variable overrides (mapping)
    mixins:       # SCSS mixins (string)
    rules:        # Additional SCSS rules (string)
  quarto:         # Quarto-specific settings
    format:       # Format-specific options
  shiny:          # Shiny-specific settings
    theme:
      defaults:   # Bootstrap variables
      rules:      # Additional SCSS rules

Example#

yaml · 12 LINES

defaults:
  bootstrap:
    defaults:
      navbar-bg: $brand-orange
    rules: |
      .btn-primary {
        border-radius: 0.5rem;
      }
  shiny:
    theme:
      defaults:
        navbar-padding-y: 1rem

Note: Colors from color.palette are available as Sass variables: $brand-{color_name}

Validation Rules#

When creating _brand.yml files:

All fields are optional - only include what's needed
Prefer hex colors - use "#447099" format
Prefer simple syntax - use strings instead of objects when possible
Follow Sass naming - color/font names use lowercase and hyphens
Include URLs with protocol - always use https://
Reference before use - define colors/fonts before referencing them
Keep it concise - simpler is better

Complete Minimal Example#

yaml · 16 LINES

color:
  palette:
    blue: "#0066cc"
    gray: "#666666"
  primary: blue
  foreground: gray
  background: "#ffffff"

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

Complete Comprehensive Example#

See the example in the document provided to you (brand-yml.prompt.txt) for a full-featured _brand.yml with all options demonstrated.

Supporting file: references/quarto.md#

Using brand.yml with Quarto#

Guide for applying brand.yml styling to Quarto documents, presentations, websites, and PDFs.

Overview#

Quarto automatically integrates _brand.yml to provide unified visual styling across multiple output formats including HTML, dashboards, RevealJS presentations, and Typst PDFs.

Quick Start#

Place _brand.yml at your project root:

TEXT · 5 LINES

my-project/
├── _quarto.yml
├── _brand.yml
├── index.qmd
└── ...

Quarto automatically discovers and applies _brand.yml - no configuration needed.

Supported Formats#

Brand styling automatically applies to:

HTML documents - Web pages, reports
HTML dashboards - Interactive dashboards
RevealJS presentations - Slide decks
Typst PDFs - PDF documents via Typst
Websites - Multi-page Quarto websites

Document-Level Usage#

Specify brand in document frontmatter:

yaml · 6 LINES

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

Or use default discovery:

yaml · 4 LINES

---
title: "My Document"
format: html
---

If _brand.yml exists at project root, it's automatically applied.

Project-Level Usage#

Configure in _quarto.yml:

yaml · 7 LINES

project:
  type: website
  brand: _brand.yml

format:
  html:
    theme: default

Custom Brand File Location#

Specify a non-standard path:

yaml · 6 LINES

---
title: "My Document"
format:
  html:
    brand: branding/company-brand.yml
---

Or in project config:

yaml · 2 LINES

project:
  brand: path/to/brand.yml

Light/Dark Mode#

Specify color variants for light and dark modes:

yaml · 12 LINES

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

Any color in color or typography can have light/dark variants.

Theme Layering#

Control precedence with the "brand" keyword:

Default (Brand Lowest Priority)#

yaml · 5 LINES

format:
  revealjs:
    theme:
      - custom.scss
      - cosmo

Priority: cosmo > custom.scss > _brand.yml

Brand Highest Priority#

yaml · 6 LINES

format:
  revealjs:
    theme:
      - cosmo
      - custom.scss
      - brand

Priority: _brand.yml > custom.scss > cosmo

Brand in Middle#

yaml · 6 LINES

format:
  html:
    theme:
      - cosmo
      - brand
      - custom.scss

Priority: custom.scss > _brand.yml > cosmo

Accessing Brand Data in Documents#

Shortcodes#

Use shortcodes to access brand values (requires Quarto extensions):

markdown · 5 LINES

<!-- Access colors -->
Our primary color is {{{< brand-color primary >}}}.

<!-- Access meta information -->
Welcome to {{{< brand-meta name >}}}.

SCSS Variables#

Access brand colors in custom SCSS:

scss · 6 LINES

// Custom SCSS file
.branded-element {
  color: $brand-primary;
  background: $brand-background;
  border-color: $brand-secondary;
}

Brand colors are automatically available as Sass variables: $brand-{color-name}.

Typst PDF Support#

Brand styling works with Typst PDF output:

yaml · 6 LINES

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

Typst Color Variables#

Access colors in Typst templates:

brand-color.{name} - Palette colors (e.g., brand-color.blue, brand-color.primary)
brand-background-color.{name} - Lighter background variants

Typst Typography Support#

Element	family	weight	color	background-color	line-height
base	✓	✓	✓	-	✓
headings	✓	✓	✓	-	✓
title	✓	✓	✓	-	✓
monospace-inline	✓	✓	✓	✓	-
monospace-block	✓	✓	✓	✓	✓
link	-	✓	✓	✓	-

Typst Font Handling#

Quarto automatically downloads Google Fonts and caches them for Typst. Check fonts:

bash

quarto typst fonts --ignore-system-fonts --font-path .quarto/typst-font-cache/

Disable font fallback in Typst:

typst

#set text(fallback: false)

Complete Examples#

Simple HTML Document#

yaml · 10 LINES

---
title: "Quarterly Report"
format:
  html:
    toc: true
---

# Executive Summary

Content here uses brand colors and typography automatically.

With _brand.yml at project root:

yaml · 17 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

RevealJS Presentation#

yaml · 13 LINES

---
title: "Company Overview"
format:
  revealjs:
    theme:
      - default
      - brand
    logo: logo.png
---

# Introduction

Slides automatically use brand colors and fonts.

Website with Brand#

_quarto.yml:

yaml · 16 LINES

project:
  type: website
  brand: _brand.yml

website:
  title: "My Company"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css

Brand colors and typography apply across all pages.

Dashboard#

yaml · 12 LINES

---
title: "Sales Dashboard"
format:
  dashboard:
    brand: _brand.yml
    theme: default
---

## Row

```{python}
# Dashboard content

TEXT · 17 LINES


### Typst PDF

```yaml
---
title: "Technical Report"
format:
  typst:
    brand: _brand.yml
    margin:
      x: 2cm
      y: 2cm
---

# Overview

PDF uses brand colors and fonts via Typst.

Brand Extensions#

Create reusable brand packages:

bash

quarto create extension brand

Structure:

TEXT · 6 LINES

my-brand-extension/
├── _extension.yml
├── brand.yml
├── logo.png
└── fonts/
    └── ...

_extension.yml:

yaml · 5 LINES

title: Company Brand
author: Your Name
version: 1.0.0
contributes:
  brand: brand.yml

Install extension in projects:

bash

quarto add username/my-brand-extension

Requirement: Brand extensions need _quarto.yml project file.

Sample _brand.yml for Quarto#

Minimal example:

yaml · 21 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 1rem
    line-height: 1.6
  headings:
    family: Inter
    weight: 600
    line-height: 1.2

Complete example with light/dark mode:

yaml · 52 LINES

meta:
  name: My Company
  link: https://mycompany.com

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

color:
  palette:
    blue: "#0066cc"
    navy: "#003366"
    gray: "#666666"
    light-gray: "#f5f5f5"
  primary: blue
  secondary: gray
  success: "#28a745"
  info: blue
  warning: "#ffc107"
  danger: "#dc3545"
  foreground:
    light: navy
    dark: "#e0e0e0"
  background:
    light: "#ffffff"
    dark: "#1a1a1a"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 500, 600, 700]
      style: [normal, italic]
    - family: Fira Code
      source: google
      weight: [400, 500]
  base:
    family: Inter
    size: 1rem
    line-height: 1.6
  headings:
    family: Inter
    weight: 600
    line-height: 1.2
  monospace:
    family: Fira Code
    size: 0.9em
  link:
    color: primary
    weight: 500

Tips#

Automatic discovery: Place _brand.yml at project root for automatic application
Light/dark variants: Use for websites with theme toggles
Layer strategically: Use brand keyword to control theme precedence
Test across formats: Verify brand applies correctly to HTML, PDF, and presentations
Extension for reuse: Create brand extensions for multi-project consistency
Version control: Include _brand.yml in git repository

Troubleshooting#

Brand not applying?

Verify file is named _brand.yml (with underscore)
Check file is at project root or specified in brand: field
Ensure _quarto.yml exists for project-level branding
Try explicit path in frontmatter

Colors not matching?

Ensure hex colors have quotes: "#0066cc"
Check color references match palette definitions
Verify theme layering order

Fonts not loading?

Verify Google Fonts spelling
Check internet connection (required for Google Fonts)
For Typst, check font cache: quarto typst fonts
Ensure source: google is specified correctly

Typst-specific issues?

Check font cache path: .quarto/typst-font-cache/
Add #set text(fallback: false) to debug font issues
Verify typography properties are supported (see table above)

Brand extension not working?

Ensure _quarto.yml exists in project
Verify extension is installed: quarto list extensions
Check extension contributes brand: look for contributes.brand in _extension.yml

Supporting file: references/shiny-python.md#

Using brand.yml with Shiny for Python#

Guide for applying brand.yml styling to Shiny for Python applications using ui.Theme.

Overview#

Installation#

bash · 8 LINES

# Install Shiny with theme support
pip install "shiny[theme]"

# Or install separately
pip install shiny libsass

# Optional: Install brand_yml for programmatic access
pip install brand_yml

Quick Start#

Automatic Discovery#

Place _brand.yml at your app directory root:

TEXT · 4 LINES

my-app/
├── _brand.yml
├── app.py
└── ...

Then use ui.Theme.from_brand():

Shiny Express:

python · 5 LINES

from shiny.express import ui

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

# ... rest of app

Shiny Core:

python · 12 LINES

from shiny import App, ui

app_ui = ui.page_fluid(
    ui.Theme.from_brand(__file__),
    ui.h2("My App"),
    # ... rest of UI
)

def server(input, output, session):
    pass

app = App(app_ui, server)

ui.Theme.from_brand() Parameters#

python

ui.Theme.from_brand(brand)

The brand parameter accepts:

File Path (Most Common)#

python · 8 LINES

# Use __file__ for app directory
ui.Theme.from_brand(__file__)

# Explicit file path
ui.Theme.from_brand("path/to/_brand.yml")

# Explicit directory (auto-finds _brand.yml)
ui.Theme.from_brand("branding/")

Brand Object#

python · 4 LINES

from brand_yml import Brand

brand = Brand.from_yaml("_brand.yml")
ui.Theme.from_brand(brand)

Search Behavior#

When given __file__ or a directory path, the method searches for _brand.yml:

In the specified directory
In _brand/ subdirectory
In brand/ subdirectory
In parent directories (recursive)

Complete Examples#

Shiny Express App#

python · 19 LINES

from shiny.express import input, render, ui

ui.page_opts(
    title="My Dashboard",
    theme=ui.Theme.from_brand(__file__)
)

with ui.sidebar():
    ui.input_slider("n", "Number of observations", 1, 100, 50)

@render.plot
def histogram():
    import matplotlib.pyplot as plt
    import numpy as np

    data = np.random.randn(input.n())
    plt.hist(data, bins=20)
    plt.xlabel("Value")
    plt.ylabel("Frequency")

Shiny Core App#

python · 23 LINES

from shiny import App, render, ui

app_ui = ui.page_sidebar(
    ui.sidebar(
        ui.input_slider("n", "Number of observations", 1, 100, 50),
    ),
    ui.output_plot("histogram"),
    title="My Dashboard",
    theme=ui.Theme.from_brand(__file__)
)

def server(input, output, session):
    @render.plot
    def histogram():
        import matplotlib.pyplot as plt
        import numpy as np

        data = np.random.randn(input.n())
        plt.hist(data, bins=20)
        plt.xlabel("Value")
        plt.ylabel("Frequency")

app = App(app_ui, server)

With Custom Path#

python · 10 LINES

from shiny.express import ui

# Shared brand file
ui.page_opts(theme=ui.Theme.from_brand("../shared-branding/_brand.yml"))

# Named brand file
ui.page_opts(theme=ui.Theme.from_brand("company-brand.yml"))

# Directory with _brand.yml inside
ui.page_opts(theme=ui.Theme.from_brand("branding/"))

Multiple Page Types#

python · 30 LINES

from shiny import App, ui

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

# page_sidebar
app_ui = ui.page_sidebar(
    theme=ui.Theme.from_brand(__file__),
    ui.sidebar(
        # ... sidebar content
    ),
    # ... main content
)

# page_navbar
app_ui = ui.page_navbar(
    ui.nav_panel("Tab 1", # ...),
    ui.nav_panel("Tab 2", # ...),
    title="My App",
    theme=ui.Theme.from_brand(__file__)
)

# page_fillable
app_ui = ui.page_fillable(
    theme=ui.Theme.from_brand(__file__),
    # ... content
)

Combining with Custom Theme Rules#

Extend brand.yml themes with custom Sass:

python · 13 LINES

from shiny.express import ui

theme = (
    ui.Theme.from_brand(__file__)
    .add_rules("""
        .custom-card {
            border-radius: 0.5rem;
            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        }
    """)
)

ui.page_opts(theme=theme)

Available theme methods (chainable):

.add_defaults() - Override Bootstrap variables
.add_functions() - Add Sass functions
.add_mixins() - Add Sass mixins
.add_rules() - Add CSS rules
.add_uses() - Add Sass declarations

Programmatic Access with brand_yml#

For advanced use cases, access brand data programmatically:

python · 28 LINES

from brand_yml import Brand

# Read brand file
brand = Brand.from_yaml("_brand.yml")

# Or from string
yaml_content = """
color:
  palette:
    blue: "#0066cc"
  primary: blue
"""
brand = Brand.from_yaml_str(yaml_content)

# Access brand elements
brand.meta.name                    # Organization name
brand.color.palette.blue           # "#0066cc"
brand.color.primary                # "blue"
brand.typography.base.family       # Font family name

# Use in UI
from shiny import ui

app_ui = ui.page_fluid(
    theme=ui.Theme.from_brand(brand),
    ui.h2(brand.meta.name),
    # ... more content
)

Sample _brand.yml for Shiny#

Minimal example:

yaml · 19 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

More complete example:

yaml · 39 LINES

meta:
  name: My Company
  link: https://mycompany.com

color:
  palette:
    blue: "#0066cc"
    navy: "#003366"
    gray: "#666666"
    light-gray: "#f5f5f5"
  primary: blue
  secondary: gray
  success: "#28a745"
  info: blue
  warning: "#ffc107"
  danger: "#dc3545"
  foreground: navy
  background: "#ffffff"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 500, 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
    line-height: 1.2
  monospace:
    family: Fira Code
    size: 14px

Tips#

Use file: Most reliable way to locate _brand.yml in app directory
Start simple: Begin with colors and one font
Test paths: If brand doesn't apply, try explicit paths
Version control: Include _brand.yml in git repository
Precompile for production: Use .to_css() to avoid runtime Sass compilation

python · 6 LINES

# Development
theme = ui.Theme.from_brand(__file__)

# Production (precompile)
theme_css = ui.Theme.from_brand(__file__).to_css()
# Save to static/theme.css, then reference in production

Troubleshooting#

Theme not applying?

Check file is named _brand.yml (with underscore)
Verify libsass is installed: pip install libsass
Try explicit path: ui.Theme.from_brand("path/to/_brand.yml")
Check for YAML syntax errors

Colors not matching?

Ensure hex colors have quotes: "#0066cc"
Verify color names match palette definitions
Check semantic colors reference valid palette names

Fonts not loading?

Verify Google Fonts spelling and availability
Ensure source: google is specified
Check font family names match exactly
Internet connection required for Google Fonts

Import errors?

Install theme support: pip install "shiny[theme]"
Or install libsass separately: pip install libsass

Performance Considerations#

For production apps with many instances, precompile the theme:

python · 11 LINES

# build_theme.py
from shiny import ui

theme = ui.Theme.from_brand("_brand.yml")
css = theme.to_css()

with open("static/brand-theme.css", "w") as f:
    f.write(css)

# Then in app.py, reference the CSS file directly
# This avoids runtime Sass compilation overhead

Supporting file: references/shiny-r.md#

Using brand.yml with Shiny for R#

Guide for applying brand.yml styling to Shiny applications using the bslib package.

Overview#

Installation#

r · 5 LINES

# Install bslib (includes brand.yml support)
install.packages("bslib")

# Optional: Install brand.yml package for theming plots/tables
install.packages("brand.yml")

Quick Start#

Automatic Discovery#

Place _brand.yml at your app directory root:

TEXT · 4 LINES

my-app/
├── _brand.yml
├── app.R
└── ...

Then use bs_theme() in your app:

r · 14 LINES

library(shiny)
library(bslib)

ui <- page_fluid(
  theme = bs_theme(),  # Automatically finds _brand.yml
  titlePanel("My App"),
  # ... rest of UI
)

server <- function(input, output, session) {
  # ...
}

shinyApp(ui, server)

Search Paths#

bslib automatically searches for _brand.yml in this order:

Current app directory
_brand/ subdirectory
brand/ subdirectory
Parent directories (recursive)

bs_theme() Brand Parameter#

The brand parameter controls how branding is applied:

Automatic (Default)#

theme = bs_theme()

Searches for _brand.yml and applies it if found. No error if file doesn't exist.

Required Brand#

theme = bs_theme(brand = TRUE)

Requires _brand.yml to exist. Throws error if not found.

Explicit Path#

theme = bs_theme(brand = "path/to/my-brand.yml")

Uses specific brand file. Path can be:

Relative to app directory: "branding/company-brand.yml"
Absolute: "/Users/name/brands/company.yml"
Directory (auto-finds _brand.yml): "branding/"

Inline Brand Definition#

r · 18 LINES

theme = bs_theme(
  brand = list(
    color = list(
      palette = list(
        blue = "#0066cc",
        gray = "#666666"
      ),
      primary = "blue",
      foreground = "gray"
    ),
    typography = list(
      fonts = list(
        list(family = "Inter", source = "google", weight = c(400, 600))
      ),
      base = "Inter"
    )
  )
)

Disable Branding#

theme = bs_theme(brand = FALSE)

Ignores _brand.yml even if it exists.

Using with page_*() Functions#

All bslib page functions support automatic brand discovery:

r · 27 LINES

# page_fluid
ui <- page_fluid(
  theme = bs_theme(),
  # ... content
)

# page_sidebar
ui <- page_sidebar(
  theme = bs_theme(),
  sidebar = sidebar(
    # ... sidebar content
  ),
  # ... main content
)

# page_navbar
ui <- page_navbar(
  theme = bs_theme(),
  nav_panel("Tab 1", # ...),
  nav_panel("Tab 2", # ...)
)

# page_fillable
ui <- page_fillable(
  theme = bs_theme(),
  # ... content
)

Branded Plots and Tables in Shiny#

Use theming functions from the brand.yml package to style plots and tables within Shiny apps. See brand-yml-in-r.md for complete documentation of theming functions.

Basic Example#

r · 38 LINES

library(shiny)
library(bslib)
library(ggplot2)
library(gt)
library(brand.yml)

ui <- page_sidebar(
  theme = bs_theme(brand = TRUE),

  sidebar = sidebar(
    selectInput("dataset", "Dataset:", c("mtcars", "iris"))
  ),

  card(
    card_header("Branded Plot"),
    plotOutput("plot")
  ),
  card(
    card_header("Branded Table"),
    gt_output("table")
  )
)

server <- function(input, output, session) {
  output$plot <- renderPlot({
    ggplot(mtcars, aes(mpg, hp)) +
      geom_point() +
      theme_brand_ggplot2()
  })

  output$table <- render_gt({
    head(mtcars) |>
      gt() |>
      theme_brand_gt()
  })
}

shinyApp(ui, server)

Benefits:

Consistent styling across UI, plots, and tables
Automatic brand detection from _brand.yml
Works with ggplot2, gt, flextable, plotly, and base R graphics

For detailed theming function documentation, see brand-yml-in-r.md.

Complete Shiny Example#

r · 39 LINES

library(shiny)
library(bslib)

ui <- page_sidebar(
  theme = bs_theme(brand = TRUE),  # Require _brand.yml

  sidebar = sidebar(
    title = "Controls",
    selectInput("dataset", "Dataset:",
                choices = c("iris", "mtcars")),
    numericInput("n", "Number of rows:", 10, min = 1, max = 50)
  ),

  card(
    card_header("Data Summary"),
    tableOutput("summary")
  ),

  card(
    card_header("Data Details"),
    verbatimTextOutput("details")
  )
)

server <- function(input, output, session) {
  dataset <- reactive({
    get(input$dataset)
  })

  output$summary <- renderTable({
    head(dataset(), input$n)
  })

  output$details <- renderPrint({
    summary(dataset())
  })
}

shinyApp(ui, server)

With _brand.yml:

yaml · 19 LINES

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

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

R Markdown Shiny Documents#

Use brand.yml in R Markdown documents with Shiny runtime:

yaml · 9 LINES

---
title: "Interactive Dashboard"
output:
  html_document:
    theme:
      version: 5          # Required for brand.yml
      brand: true         # Auto-discover _brand.yml
runtime: shiny
---

Or specify a path:

yaml · 9 LINES

---
title: "Interactive Dashboard"
output:
  html_document:
    theme:
      version: 5
      brand: "path/to/brand.yml"
runtime: shiny
---

Important: Set version: 5 to use Bootstrap 5, which has the best brand.yml support.

Note: For R Markdown documents without runtime: shiny, see brand-yml-in-r.md.

Programmatic Brand Access#

For advanced use cases, access brand data programmatically within Shiny:

r · 22 LINES

library(brand.yml)

server <- function(input, output, session) {
  # Read brand data
  brand <- read_brand_yml()

  # Use in custom UI elements
  output$brand_info <- renderUI({
    div(
      style = paste0("color: ", brand$color$primary, ";"),
      h3(brand$meta$name),
      p("Welcome to our branded app!")
    )
  })

  # Use in plots with custom styling
  output$custom_plot <- renderPlot({
    plot(mtcars$mpg, mtcars$hp,
         col = brand$color$primary,
         pch = 19)
  })
}

For complete documentation on programmatic access and theming functions, see brand-yml-in-r.md.

Tips#

Start simple: Begin with colors and one font family
Test automatically: Automatic discovery works well for most cases
Use explicit paths: For shared brand files across multiple apps
Version control: Include _brand.yml in your git repository
Validate early: Use brand = TRUE during development to catch missing files
Combine with theming functions: Style plots and tables consistently (see brand-yml-in-r.md)

Troubleshooting#

Brand not applying to Shiny UI?

Check file is named _brand.yml (with underscore)
Verify file is in app directory or parent directories
Try explicit path: bs_theme(brand = "path/to/_brand.yml")
Check for YAML syntax errors

Colors not matching?

Verify hex colors have quotes: "#0066cc"
Check color names match palette definitions
Ensure primary/secondary colors reference valid palette names

Fonts not loading?

Verify Google Fonts spelling and availability
Check source: google is specified correctly
Ensure font family names match exactly in typography elements

Plots/tables not branded?

Ensure brand.yml package is installed: install.packages("brand.yml")
Use theming functions: theme_brand_ggplot2(), theme_brand_gt(), etc.
See brand-yml-in-r.md for complete theming documentation

brand-yml-in-r.md (opens in a new tab): General R usage, R Markdown integration, theming functions, and programmatic access
brand-yml-spec.md (opens in a new tab): Complete brand.yml file specification

SHOWING THE FIRST PART OF 54 KB · THE FULL TEXT IS ON THIS PAGE

§06

FAQ

07 QUESTIONS

01What is the Brand yml agent skill?

Create and use brand.yml files for consistent branding across Shiny applications and Quarto documents. It is listed under brand in the 100xLab agent skills directory.

02How do I install Brand yml in Cursor, Claude Code, or Codex?

03What does the Brand yml SKILL.md cover?

04Which agents can use Brand yml?

05What license is Brand yml under?

The posit-dev/skills repository declares the MIT license. Read the license file in the repository before you copy or redistribute the skill.

06Is Brand yml free to use?

Reading, copying and installing Brand yml costs nothing: it is published in a public GitHub repository under the MIT license. Reuse and redistribution follow that license.

07Where is the source of Brand yml?

Brand yml comes from https://github.com/posit-dev/skills, which has 415 GitHub stars. The SKILL.md is at https://github.com/posit-dev/skills/blob/HEAD/brand-yml/SKILL.md. The author is posit-dev.

Need an agent workflow built around your stack?

Tell us the workflow you want automated. We reply within 4 working hours (IST).

BOOK A CALL

§09

ATTRIBUTION

Brand yml was written by its original authors and is published in posit-dev/skills (opens GitHub in a new tab) under the MIT license. All rights stay with the original authors.

100xLab did not write, maintain or endorse this skill. This page lists it for discovery. Repo stars belong to the source repository, not to the skill. Review any skill before you install it.

Brand yml

QUICK ANSWER

INSTALL

SKILL.MD

brand.yml Skill#

What is brand.yml?#

File Naming Convention#

Decision Tree#

Creating brand.yml Files#

Step 1: Gather Information#

Step 2: Read the Specification#

Step 3: Build the File Incrementally#

Step 4: Apply Best Practices#

Step 5: Validate Structure#

Modifying Existing Files#

Using with Shiny for R#

Using with Shiny for Python#

Using with Quarto#

Troubleshooting#

Brand Not Applying#

Colors Not Matching#

Fonts Not Loading#

YAML Syntax Errors#

Reference Documentation#

Key Principles#

Common Patterns#

Light/Dark Mode Colors#

Logo Variants#

Multiple Font Weights#

Color Aliases#

Tips#

Supporting file: references/brand-yml-in-r.md#

Using brand.yml in R#

Overview#

Installation#

R Markdown Integration#

Other R Markdown Formats#

Programmatic Access#

Branded Theming Functions#

theme_brand_ggplot2()#

theme_brand_gt()#

theme_brand_flextable()#

theme_brand_plotly()#

theme_brand_thematic()#

theme_brand_thematic_on()#

R Markdown Example#

Quarto Integration#

Script Usage#

Benefits#

Tips#

Common Patterns#

Branded Report with Multiple Visualizations#

Dynamic Brand Colors#

Conditional Branding#

Supporting file: references/brand-yml-spec.md#

brand.yml Specification#

File Naming Convention#

File Structure#

Meta Section#

Simple Format#

Extended Format#

Logo Section#

Structure#

File Paths#

Light/Dark Variants#

With Alt Text#

Complete Example#

Color Section#

Structure#

Color Palette Best Practices#

Referencing Colors#

Complete Example#

Typography Section#

Structure#

Font Sources#

Local/Remote Files#

Google Fonts#

Bunny Fonts (GDPR-compliant alternative)#

Typographic Elements#

Simple Format (String)#