Package 'brand.yml'

Description

Create a Brand instance from a list or character vector.

Usage

as_brand_yml(brand)

Arguments

Value

A normalized brand_yml list.

Examples

as_brand_yml("
meta:
  name: Example Brand

color:
  primary: '#FF5733'
  secondary: '#33FF57'
")

as_brand_yml(list(
  meta = list(name = "Example Brand"),
  color = list(primary = "#FF5733", secondary = "#33FF57")
))

Description

Safely extracts a color value from a brand object based on the provided key. This function handles color references and resolves them, including references to palette colors and other theme colors. It detects and prevents cyclic references.

Usage

brand_color_pluck(brand, key)

Arguments

Details

The function checks for the color key in both the main color theme and the color palette. It can resolve references between colors (e.g., if "primary" references "palette.blue"). If a cyclic reference is detected (e.g., A references B which references A), the function will throw an error.

Value

The resolved color value (typically a hex color code) if the key exists, otherwise returns the key itself.

See Also

Other brand.yml helpers: brand_has(), brand_pluck(), with_brand_yml_path()

Examples

brand <- as_brand_yml(list(
  color = list(
    primary = "blue",
    secondary = "info",
    info = "light-blue",
    palette = list(
      blue = "#004488",
      light_blue = "#c3ddff"
    )
  )
))

# Extract the primary color
brand_color_pluck(brand, "primary") # "#004488"

# Extract a color that references another color
brand_color_pluck(brand, "info") # "#c3ddff"

# Extract a color that references another color
# which in turn references the palette
brand_color_pluck(brand, "secondary") # "#c3ddff"

# Extract a color that isn't defined
brand_color_pluck(brand, "green") # "green"

# Use brand_pluck() if you need direct (resolved) values
brand_pluck(brand, "color", "primary") # "#004488"
brand_pluck(brand, "color", "info") # "#c3ddff"
brand_pluck(brand, "color", "green") # NULL

Description

Checks if a given brand object has a specific nested element accessible via the additional arguments provided as key paths.

Usage

brand_has(brand, ...)

Arguments

Value

TRUE if the nested element exists in the brand object, FALSE otherwise.

See Also

Other brand.yml helpers: brand_color_pluck(), brand_pluck(), with_brand_yml_path()

Examples

brand <- as_brand_yml(list(
  meta = list(name = "Example Brand"),
  color = list(primary = "#FF5733")
))

# Check if brand has a primary color
brand_has(brand, "color", "primary") # TRUE

# Check if brand has a secondary color
brand_has(brand, "color", "secondary") # FALSE

Description

Safely extracts a nested element from a brand object using the provided key path. Returns NULL if the element doesn't exist.

Usage

brand_pluck(brand, ...)

Arguments

Value

The value of the nested element if it exists, NULL otherwise.

See Also

Other brand.yml helpers: brand_color_pluck(), brand_has(), with_brand_yml_path()

Examples

brand <- as_brand_yml(list(
  meta = list(name = "Example Brand"),
  color = list(primary = "#FF5733")
))

# Extract the primary color
brand_pluck(brand, "color", "primary") # "#FF5733"

# Try to extract a non-existent element
brand_pluck(brand, "color", "secondary") # NULL

Description

Creates Sass variables for brand colors with the brand_color_ prefix. Excludes the color palette which is handled by brand_sass_color_palette().

Usage

brand_sass_color(brand)

Arguments

Value

A list with one component:

• defaults: Sass variable definitions with !default flag

See Also

Other brand.yml Sass helpers: brand_sass_color_palette(), brand_sass_defaults_bootstrap(), brand_sass_fonts(), brand_sass_typography()

Examples

brand <- list(
  color = list(
    primary = "#007bff",
    danger = "#dc3545"
  )
)

brand_sass_color(brand)

Description

Converts color palette entries from a brand object to Sass variables with ⁠brand-⁠ prefix and CSS custom properties with ⁠--brand-⁠ prefix.

Usage

brand_sass_color_palette(brand)

Arguments

Value

A list with two components:

• defaults: Sass variable definitions with !default flag

• rules: CSS rules that define custom properties in ⁠:root⁠

See Also

Other brand.yml Sass helpers: brand_sass_color(), brand_sass_defaults_bootstrap(), brand_sass_fonts(), brand_sass_typography()

Examples

brand <- list(
  color = list(
    palette = list(
      primary = "#007bff",
      secondary = "#6c757d"
    )
  )
)

brand_sass_color_palette(brand)

Description

Creates Sass variables and a sass layer from Bootstrap defaults defined in the brand object. Allows overriding defaults from other sources like Shiny themes.

Usage

brand_sass_defaults_bootstrap(brand, overrides = "shiny.theme")

Arguments

Value

A list with two components:

• defaults: Sass variable definitions with !default flag

• layer: A sass_layer object with functions, mixins, and rules

See Also

Other brand.yml Sass helpers: brand_sass_color(), brand_sass_color_palette(), brand_sass_fonts(), brand_sass_typography()

Examples

brand <- list(
  defaults = list(
    bootstrap = list(
      defaults = list(
        primary = "#007bff",
        enable_rounded = TRUE
      ),
      functions = "@function brand-function() { @return true; }"
    ),
    shiny = list(
      theme = list(
        defaults = list(
          primary = "#428bca"  # Override bootstrap primary
        )
      )
    )
  )
)

brand_sass_defaults_bootstrap(brand)

Description

Creates Sass variables and CSS rules for fonts defined in the brand object. Supports Google fonts, Bunny fonts, and file-based fonts.

Usage

brand_sass_fonts(brand)

Arguments

Value

A list with two components:

• defaults: Sass variables for font definitions

• rules: CSS rules for applying fonts via classes

See Also

Other brand.yml Sass helpers: brand_sass_color(), brand_sass_color_palette(), brand_sass_defaults_bootstrap(), brand_sass_typography()

Examples

brand <- list(
  typography = list(
    fonts = list(
      list(
        family = "Roboto",
        source = "google",
        weight = c(400, 700),
        style = "normal"
      )
    )
  )
)

brand_sass_fonts(brand)

Description

Creates Sass variables for typography settings with the brand_typography_ prefix. Font size values in pixels are converted to rem units, and color references are resolved.

Usage

brand_sass_typography(brand)

Arguments

Value

A list with one component:

• defaults: Sass variable definitions with !default flag

See Also

Other brand.yml Sass helpers: brand_sass_color(), brand_sass_color_palette(), brand_sass_defaults_bootstrap(), brand_sass_fonts()

Examples

brand <- list(
  typography = list(
    base = list(
      size = "16px",
      "line-height" = 1.5
    ),
    headings = list(
      weight = "bold",
      style = "normal"
    )
  )
)

brand_sass_typography(brand)

Description

Returns a brand logo resource specified by name and variant from a brand object. The image paths in the returned object are adjusted to be absolute, relative to the location of the brand YAML file, if brand was read from a file, or the local working directory otherwise.

Usage

brand_use_logo(
  brand,
  name,
  variant = c("auto", "light", "dark", "light-dark"),
  ...,
  .required = !name %in% c("small", "medium", "large", "smallest", "largest"),
  .allow_fallback = TRUE
)

Arguments

Value

A brand_logo_resource object, a brand_logo_resource_light_dark object, or NULL if the requested logo doesn't exist and .required is FALSE.

Shiny apps and HTML documents

You can use brand_use_logo() to include logos in Shiny apps or in HTML documents produced by Quarto or R Markdown.

In Shiny apps, logos returned by brand_use_logo() will automatically be converted into HTML tags using htmltools::as.tags(), so you can include them directly in your UI code.

library(shiny)
library(bslib)

brand <- read_brand_yml()

ui <- page_navbar(
  title = tagList(
    brand_use_logo(brand, "small"),
    "Brand Use Logo Test"
  ),
  nav_panel(
    "Page 1",
    card(
      card_header("My Brand"),
      brand_use_logo(brand, "medium", variant = "dark")
    )
  )
  # ... The rest of your app
)

If your brand includes a light/dark variant for a specific size, both images will be included in the app, but only the appropriate image will be shown based on the user's system preference of the app's current theme mode if you are using bslib::input_dark_mode().

To include additional classes or attributes in the ⁠<img>⁠ tag, you can call htmltools::as.tags() directly and provide those attributes:

brand <- as_brand_yml(list(
  logo = list(
    images = list(
      "cat-light" = list(
        path = "https://placecats.com/louie/300/300",
        alt = "A light-colored tabby cat on a purple rug"
      ),
      "cat-dark" = list(
        path = "https://placecats.com/millie/300/300",
        alt = "A dark-colored cat looking into the camera"
      ),
      "cat-med" = "https://placecats.com/600/600"
    ),
    small = list(light = "cat-light", dark = "cat-dark"),
    medium = "cat-med"
  )
))

brand_use_logo(brand, "small") |>
  htmltools::as.tags(class = "my-logo", height = 32)

The same applies to HTML documents produced by Quarto or R Markdown, where images can be used in-line:

```{r}
brand_use_logo(brand, "small")
```

This is my brand's medium sized logo: `r brand_use_logo(brand, "medium")`

Finally, you can use format() to convert the logo to raw HTML or markdown:

cat(format(brand_use_logo(brand, "small", variant = "light")))
#> <img src="https://placecats.com/louie/300/300" alt="A light-colored tabby cat on a purple rug" class="brand-logo"/>

cat(format(
  brand_use_logo(brand, "medium"),
  .format = "markdown",
  class = "my-logo",
  height = 500
))
#> ![](https://placecats.com/600/600){.brand-logo .my-logo alt="" height="500"}

Examples

brand <- as_brand_yml(list(
  logo = list(
    images = list(
      small = "logos/small.png",
      huge = list(path = "logos/huge.png", alt = "Huge Logo")
    ),
    small = "small",
    medium = list(
      light = list(
        path = "logos/medium-light.png",
        alt = "Medium Light Logo"
      ),
      dark = list(path = "logos/medium-dark.png")
    )
  )
))

brand_use_logo(brand, "small")
brand_use_logo(brand, "medium")
brand_use_logo(brand, "large")
brand_use_logo(brand, "huge")

brand_use_logo(brand, "small", variant = "light")
brand_use_logo(brand, "small", variant = "light", allow_fallback = FALSE)
brand_use_logo(brand, "small", variant = "light-dark")
brand_use_logo(
  brand,
  "small",
  variant = "light-dark",
  allow_fallback = FALSE
)

brand_use_logo(brand, "medium", variant = "light")
brand_use_logo(brand, "medium", variant = "dark")
brand_use_logo(brand, "medium", variant = "light-dark")

Description

Reads a Brand YAML file or finds and reads a ⁠_brand.yml⁠ file and returns a validated Brand instance.

Usage

read_brand_yml(path = NULL)

Arguments

Details

By default, read_brand_yml() finds a project-specific ⁠_brand.yml⁠ file, by looking in the current working directory directory or any parent directory for a ⁠_brand.yml⁠, ⁠brand/_brand.yml⁠ or ⁠_brand/_brand.yml⁠ file (or the same variants with a .yaml extension). When path is provided, read_brand_yml() looks for these files in the provided directory; for automatic discovery, read_brand_yml() starts the search in the working directory and moves upward to find the ⁠_brand.yml⁠ file.

Value

A normalized brand_yml list from the brand.yml file.

References

https://posit-dev.github.io/brand-yml/

Examples

# For this example: copy a brand.yml to a temporary directory
tmp_dir <- tempfile()
dir.create(tmp_dir)
file.copy(
  system.file("examples/brand-posit.yml", package = "brand.yml"),
  file.path(tmp_dir, "_brand.yml")
)

brand <- read_brand_yml(tmp_dir)

Description

Apply brand colors to a flextable table.

Usage

theme_brand_flextable(
  table,
  brand = NULL,
  background = NULL,
  foreground = NULL
)

Arguments

Value

Returns a themed flextable object.

See Also

Other branded theming functions: theme_brand_ggplot2(), theme_brand_gt(), theme_brand_plotly(), theme_brand_thematic()

Examples

brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(flextable)
theme_brand_flextable(
  flextable(head(palmerpenguins::penguins)),
  brand
)


brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(flextable)
theme_brand_flextable(
  flextable(head(mtcars)),
  brand
)

Description

Create a ggplot2 theme using explicit colors or by automatically extracting colors from a brand.yml file.

Usage

theme_brand_ggplot2(
  brand = NULL,
  background = NULL,
  foreground = NULL,
  accent = NULL,
  ...,
  base_size = 11,
  title_size = base_size * 1.2,
  title_color = NULL,
  line_color = NULL,
  rect_fill = NULL,
  text_color = NULL,
  plot_background_fill = NULL,
  panel_background_fill = NULL,
  panel_grid_major_color = NULL,
  panel_grid_minor_color = NULL,
  axis_text_color = NULL,
  plot_caption_color = NULL
)

Arguments

Value

A ggplot2::theme() object.

Branded Theming

The ⁠theme_brand_*⁠ functions can be used in two ways:

1. With a brand.yml file: The ⁠theme_brand_*⁠ functions use read_brand_yml() to automatically detect and use a ⁠_brand.yml⁠ file in your current project. You can also explicitly pass a path to a brand.yml file or a brand object (as returned by read_brand_yml() or created with as_brand_yml()). When a brand is provided, the theme functions will use the colors defined in the brand file automatically.

2. With explicit colors: You can directly provide colors to override the default brand colors, or you can use brand = FALSE to ignore any project ⁠_brand.yml⁠ files and only use the explicitly provided colors.

See Also

Other branded theming functions: theme_brand_flextable(), theme_brand_gt(), theme_brand_plotly(), theme_brand_thematic()

Examples

brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(ggplot2)
ggplot(diamonds, aes(carat, price)) +
  geom_point() +
  theme_brand_ggplot2(brand)

Description

Apply brand colors to a gt table.

Usage

theme_brand_gt(table, brand = NULL, background = NULL, foreground = NULL)

Arguments

Value

Returns a themed gt table object.

See Also

Other branded theming functions: theme_brand_flextable(), theme_brand_ggplot2(), theme_brand_plotly(), theme_brand_thematic()

Examples

brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(gt)
theme_brand_gt(
  gt(head(palmerpenguins::penguins)),
  brand
)


brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(gt)
theme_brand_gt(
  gt(head(mtcars)),
  brand
)

Description

Apply brand colors to a plotly plot.

Usage

theme_brand_plotly(
  plot,
  brand = NULL,
  background = NULL,
  foreground = NULL,
  accent = NULL
)

Arguments

Value

Returns a themed plotly plot object.

See Also

Other branded theming functions: theme_brand_flextable(), theme_brand_ggplot2(), theme_brand_gt(), theme_brand_thematic()

Examples

brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(plotly)
plot_ly(palmerpenguins::penguins, x = ~bill_length_mm, y = ~bill_depth_mm) |>
  theme_brand_plotly(brand)


brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')

library(plotly)
plot_ly(mtcars, x = ~wt, y = ~mpg) |>
  theme_brand_plotly(brand)

Description

Apply thematic styling using explicit colors or by automatically extracting colors from a brand.yml file. This function sets global theming for base R graphics.

Usage

theme_brand_thematic(
  brand = NULL,
  background = NULL,
  foreground = NULL,
  accent = NULL,
  ...
)

theme_brand_thematic_on(
  brand = NULL,
  background = NULL,
  foreground = NULL,
  accent = NULL,
  ...
)

Arguments

Value

thematic_theme() returns a theme object as a list (which can be activated with thematic_with_theme() or thematic_set_theme()).

thematic_on(), thematic_off(), and thematic_shiny() all return the previous global theme.

Functions

• theme_brand_thematic(): brand.yml wrapper for thematic::thematic_theme()

• theme_brand_thematic_on(): brand.yml wrapper for thematic::thematic_theme()

See Also

See the "Branded Theming" section of theme_brand_ggplot2() for more details on how the brand argument works.

Other branded theming functions: theme_brand_flextable(), theme_brand_ggplot2(), theme_brand_gt(), theme_brand_plotly()

Examples

brand <- as_brand_yml('
color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
  foreground: black
  background: white
  primary: orange')


library(ggplot2)

thematic::thematic_with_theme(theme_brand_thematic(brand), {
  ggplot(diamonds, aes(carat, price)) +
    geom_point()
})

Description

This function sets the BRAND_YML_PATH environment variable to the specified path for the duration of the local environment. This ensures that, for the scope of the local environment, any calls to functions that automatically discover a ⁠_brand.yml⁠ file will use the path specified.

Usage

with_brand_yml_path(path, code)

local_brand_yml_path(path, .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

Functions

• with_brand_yml_path(): Run code in a temporary environment with the BRAND_YML_PATH environment variable set to path.

• local_brand_yml_path(): Set the BRAND_YML_PATH environment variable for the scope of the local environment (e.g. within the current function).

See Also

Other brand.yml helpers: brand_color_pluck(), brand_has(), brand_pluck()

Examples

# Create a temporary brand.yml file in a tempdir for this example
tmpdir <- withr::local_tempdir("brand")
path_brand <- file.path(tmpdir, "my-brand.yml")
yaml::write_yaml(
  list(color = list(primary = "#abc123")),
  path_brand
)

with_brand_yml_path(path_brand, {
  brand <- read_brand_yml()
  brand$color$primary
})