Brand: Website navbar-bg uses Quarto default rather than `$primary`

[gadenbuie]

Bug description

Here's a minimal set of files to reproduce the issue. With these files, the website should pick up color.primary from _brand.yml and use bright orange for the default navbar color, instead of Quarto's default blue.

_quarto.yml

project:
  type: website

website:
  title: "Brand navbar-bg default"
  navbar:
    left:
      - index.qmd

_brand.yml

color:
  primary: "#ff5100"

index.qmd

---
title: "Hello, world"
---

[xkcd comics](https://xkcd.com) are a unique blend of humor and intellect. They often tackle complex topics like science, technology, and mathematics, making them accessible and entertaining. The stick-figure art style adds to their charm, keeping the focus on the clever punchlines and ideas.

The problem is that in _bootstrap-variables.css, setting $navbar-default to $primary only happens when $theme is set. This Sass variable has a value if you include e.g. theme: cosmo but is empty for brand.

$navbar-default: if(
  variable-exists(theme),
  if(variable-exists(primary), $primary, #517699),
  #517699
);

My recommendation is that when brand is involved, $theme be set to brand. If theme includes another Bootstwatch theme, then I'm less clear what should happen, e.g. theme: [brand, cosmo]. The reason this variable exists is to make last-minute changes to colors from the Bootswatch theme. I think that having cosmo win regardless of order is the slightly better choice; $theme is primarily used in theme-override-value() (source) where most important color changes are gated with a check against the default value (letting user values pass through).

Steps to reproduce

No response

Expected behavior

No response

Actual behavior

No response

Your environment

No response

Quarto check output

Quarto 99.9.9
[✓] Checking environment information...
      Quarto cache location: /Users/garrick/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      commit: 603c2374d3562c473d2187269f0bfffd808be44a
      Path: /Users/garrick/work/quarto-dev/quarto-cli/package/dist/bin

[✓] Checking tools....................OK
      TinyTeX: (external install)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/garrick/Library/TinyTeX/bin/universal-darwin
      Version: 2022

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.13.0
      Path: /opt/homebrew/opt/python@3.13/bin/python3.13
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking R installation...........OK
      Version: 4.4.1
      Path: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources
      LibPaths:
        - /Users/garrick/Library/R/arm64/4.4/library
        - /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library
      knitr: 1.48
      rmarkdown: 2.28

[✓] Checking Knitr engine render......OK

[cscheid]

My recommendation is that when brand is involved, $theme be set to brand.

I like it.

If theme includes another Bootstwatch theme, then I'm less clear what should happen, e.g. theme: [brand, cosmo].

I think the best we can do is to use the name that the configuration deemed to be "the most important", eg theme: [brand, cosmo] gets $theme: "cosmo" and theme: [cosmo, brand] gets $theme: "brand".

[coatless]

Huh, I always thought that the first theme was the most important and, then, went downwards in precedents given the theme: [main, custom.scss] approach taken usually.

[cscheid]

Teaching myself how this all works

In addition to theme, we also have theme-name. _bootstrap-variables.scss has:

quarto-cli/src/resources/formats/html/bootstrap/_bootstrap-variables.scss

Line 2 in 8e51fc2

$theme-name: if(variable-exists(theme), $theme, "");

The theme variable itself is set by the specific SCSS files directly:

quarto-cli/src/resources/formats/html/bootstrap/themes/cerulean.scss

Line 4 in e7f8dbe

$theme: "cerulean" !default;

quarto-cli/src/resources/formats/html/bootstrap/themes/cosmo.scss

Line 4 in e7f8dbe

$theme: "cosmo" !default;

.. and so on. Those variable assignments all use !default and appear in the scss:defaults layer.

The theme name is also used by some style settings we have:

• src/resources/projects/website/listing/quarto-listing.scss
• src/resources/projects/website/navigation/quarto-nav.scss

[cscheid]

@coatless Two quick notes:

• if you find a situation in which the second entry in theme loses, then it's likely to be a Quarto bug (unless, that is, you specify variables in the defaults layer without !default, which is not what Quarto expects).
• The brand.yml features in Quarto is design to detect _brand.yml information from the project environment, and as other features in Quarto that sniff ambient information, we give it low priority on purpose, so that explicit project and configurations can override it.

Concretely speaking, it's always been the case that a configuration theme: [main, custom.scss] like you pointed out will allow custom.scss settings to override those of main.

[gadenbuie]

@cscheid We can set $theme: "brand" !default in the brand Sass layers. I tried this earlier but I didn't realize I was putting the rule in a place where it was conditionally included only if defaults.bootstrap.defaults was included in the _brand.yml. #11473 adds the default declaration in brand.ts.

[cscheid]

Draft #11474