Brand edits

docs/authoring/brand.qmd

@@ -166,7 +166,15 @@ logo:
   medium: logo.png
 ```
 
-You can specify a local file path, relative to the location of `_brand.yml`, or a URL (*is this true?*).
+You can specify a local file path, relative to the location of `_brand.yml`, or a URL that starts with `http://` or `https://`.
+
+::: {.callout-warning}
+
+## Limitation
+
+Logos specified as URLs are not currently supported in `format: typst`.
+
+::: 
 
 A single logo may not work well in all locations so **brand.yml** allows you to set three different logos: `small`, `medium` and `large`. For example:
 
@@ -434,19 +442,62 @@ You can't currently access `typography`, `meta`, or `defaults` values using the
 
 ### In SCSS
 
-If `_brand.yml` defines `color: blue`:
+The colors defined in `palette` are set as SCSS variables of the form `brand-COLOR_NAME`. 
+For example, if `_brand.yml` defines `blue`:
 
 ```{.yaml filename="_brand.yml"}
 color:
   palette:
     blue: "#ddeaf1"
 ```
 
-This should work:
+Then the variable `$brand-blue` is will be set to `#ddeaf1` in the `defaults` layer of  [Quarto's SCSS layering system](/docs/output-formats/html-themes-more.html#bootstrap-bootswatch-layering). 
+You can add a custom SCSS file, `styles.scss`, in the usual way:
+```{.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: [styles.scss]
+```
+
+Then `styles.scss` can use these brand variables to make style tweaks. 
+For example, you might want all `h1` elements to be `blue`:
+
+```{.scss filename="styles.scss"}
+/*-- scss:rules --*/
+
+h1 {
+  color: $brand-blue;
+}
+```
+
+When you specify SCSS files without an explicit `brand` element, it is equivalant to listing them after `brand`.
+For instance, the above `theme` is equivalant to:
+
+```{.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: [brand, styles.scss]
+```
+
+This order doesn't matter when you are setting items in the `/*-- scss:rules --*/` layer, because `rules` are layered on after `defaults`. 
+
+However, if you want to set a [Quarto SASS variable](https://quarto.org/docs/output-formats/html-themes.html#sass-variables) you'll use the `/*-- scss:defaults --*/` layer and the order of items in `theme` will matter.
 
-```{.scss filename="custom.scss"}
+As an example, consider setting the navigation bar background to the `blue` brand color:
+
+```{.scss filename="nav.scss"}
 /*-- scss:defaults --*/
-$navbar-bg: $brand-blue; 
+
+$navbar-bg: $brand-blue;
+```
+
+Because of the way Quarto layers SCSS, the order for the `defaults` layer is the reverse of what is specified in `theme`. 
+For `nav.scss` to find the `brand-blue` variable, `brand` must come after `nav.scss` in `theme`:
+
+```{.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: [nav.scss, brand]
 ```
 
 ### Typst