_brand.yml - color field into HTML formats

[cscheid]

Towards #10249:

• add a Brand class to Quarto's typescript that will hold methods to get brand.yml information out. This is now used in Format instead of storing the raw JSON.
• resolve color entries from _brand.yml into a new SASS bundle, so that brand colors win by default when _brand.yml is in play.

Minimal demo. Note that primary controls link color by default in our themes, and so _brand.yml forwards the information to the theme automatically without requiring any additional theme.

_brand.yml

color:
  with:
    fire-engine-red: "#ff0000"
  primary: fire-engine-red

index.qmd

Currently, this requires _quarto.yml (or documents) to define no theme. An explicit theme will cause _brand.yml to lose, ie it's currently the lowest priority value. I think this makes sense since _brand.yml is configuration we pick up by default from the ambient, and so it should be overrideable by any explicit setting, including eg theme: cosmo.

[gadenbuie]

I think this makes sense since _brand.yml is configuration we pick up by default from the ambient, and so it should be overrideable by any explicit setting, including eg theme: cosmo.

FYI, I was thinking this relationship would be inverted in brand for values in defaults. In other words

color:
  with:
    fire-engine-red: "#ff0000"
  primary: fire-engine-red

defaults:
  quarto:
    format:
      html:
        theme: cosmo

would result in the Cosmo theme with $primary: #ff0000 applied. It's often reasonable to start from a Bootswatch theme and change a few variables as a way to get much closer to a brand's desired appearance without having to do a ton of additional Sass/CSS work.

[cscheid]

I hear you. Your suggestion would be easy for us to do as well, and we can experiment with both and see how they feel.

The current semantics are consistent with how Quarto configuration works in general: "ambient" settings are overrideable by explicit settings. The disadvantage of what you're suggesting is that the moment someone adds _brand.yml to a project, there'll be no way to disable those settings project-wide.

We also have some places where Quarto knows to interpret particular strings specially. One example of this is in filter chains, where we can declare

filters:
  - my-filter
  - quarto
  - my-other-filter

This denotes that Quarto's default filters should happen before my-other-filter, but after my-filter. One implementation we can consider is to have _brand be interpreted as a magic string in the "theme" field that would mean "insert _brand.yml settings at this level of specificity in the theme chain", something like

...
    format:
      html:
        theme: 
          - cosmo
          - _brand
          - more.scss

There, _brand would override the cosmo settings. But with this configuration:

...
    format:
      html:
        theme: 
          - cosmo
          - more.scss

Quarto would place the _brand.yml scss variables in "lowest priority" position.