dark brand docs

Author: gordonwoodhull

docs/authoring/brand.qmd

@@ -73,6 +73,44 @@ brand: brand/_brand.yml
 
 Paths specified in `_brand.yml` are relative to the location of the brand file.
 
+### Dark Brand
+
+As with [Themes](/docs/output-formats/html-themes.qmd#dark-mode), you can specify both light and dark brands, making both a light and a dark version of your output available:
+
+```{.yaml filename="document.qmd"}
+---
+brand:
+  light: light-brand.yml
+  dark: dark-brand.yml
+---
+```
+
+This also works with brands specified directly in the document:
+
+```{.yaml filename="document.qmd"}
+---
+brand:
+  light:
+    color:
+      background: "#ffffff"
+      foreground: "#333333"
+  dark:
+    color:
+      background: "#333333"
+      foreground: "#ffffff"
+---
+```
+
+Light and dark brands can also be specifieds in a project:
+
+```{.yaml filename="_quarto.yml"}
+---
+brand:
+  light: light-brand.yml
+  dark: dark-brand.yml
+---
+```
+
 ## Brand Elements
 
 The elements of **brand.yml** are specified in the documentation for the [**brand.yml** project](https://posit-dev.github.io/brand-yml/){.external}. 
@@ -411,7 +449,7 @@ Beyond the automatic application of your brand file, you can also directly acces
 
 Some values from the `_brand.yml` configuration file can be accessed via the `brand` shortcode. In particular, you can access colors and logos by name:
 
--   Use `{{{< brand color COLOR_NAME >}}}` to return the brand color named `COLOR_NAME` as a string.
+-   Use `{{{< brand color COLOR_NAME BRAND_MODE >}}}` to return the brand color named `COLOR_NAME` as a string. Provide `dark` for `BRAND_MODE` in order to return the color from the [dark brand](#dark-brand); otherwise the light brand will be used.
 -   Use `{{{< brand logo LOGO_NAME >}}}` to return the brand logo named `LOGO_NAME` as an image.
 
 For example, you could use the shortcode to place a brand image you've named `icon` in a dashboard sidebar:
@@ -558,4 +596,17 @@ theme:
   - tweaks.scss  # a user-defined customization
 ```
 
+The analogous syntax also works for combining light and dark brands with light and dark themes:
+
+```yaml
+# Quarto 1.7 syntax
+theme:
+  light:
+    - cosmo
+    - brand
+  dark:
+    - slate
+    - brand
+```
+
 Learn more about how Quarto generates styles in [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd).

docs/output-formats/html-themes.qmd

@@ -101,10 +101,12 @@ Setting the above themes in your `_quarto.yml` results in both a dark and light
 
 When providing both a dark and light mode for your html output, Quarto will automatically create a toggle to allow your reader to select the desired dark or light appearance. The toggle will automatically appear in the top right corner of your html output. When possible, the toggle will use browser local storage to maintain the user's preference across sessions.
 
-The first appearance (light or dark) elements in the theme to determine the default appearance for your html output. For example, since the `light` option appears first in the above example, a reader will see the light appearance by default.
+To honor the user's operating system or browser preference for light or dark mode, specify `respect-user-color-scheme: true`. Otherwise, the order of light and dark elements in the theme or brand will determine the default appearance for your html output. For example, since the `light` option appears first in the above example, a reader will see the light appearance by default, if `respect-user-color-scheme` is not enabled.
 
 Quarto will automatically select the appropriate light or dark version of the text highlighter that you have specified when possible. For more information, see [Code Highlighting](html-code.qmd#highlighting).
 
+As of Quarto 1.7, `respect-user-color-scheme` applies on page load, and the page won't change if dark mode is changed dynamically. It also requires JavaScript support: users with JavaScript disabled will see the author-preferred (first) brand or theme.
+
 ### Customizing Themes
 
 As when providing a single theme, you may provide a custom theme for dark and light mode, or a list of `scss` files to customize the light and dark appearance. This website, for example uses the following to use a light `cosmo` theme and then customizes the `cosmo` theme with additional Sass variables when in dark mode:

docs/prerelease/1.7/_highlights.qmd

@@ -6,3 +6,6 @@ Quarto 1.7 includes the following new features:
   - [Caching](/docs/computations/julia.qmd#caching-julia): Save time rendering long-running notebooks by caching results.
   - [Revise.jl integration](/docs/computations/julia.qmd#revise.jl-integration): Automatically update function definitions in Julia sessions.
 
+- Improvements to dark mode:
+  - [Dark Brand](/docs/authoring/brand.qmd#dark-brand): Light and dark brands can be specified for a document or project, enabling dark mode via brand.yml.
+  - [`respect-user-color-scheme`](/docs/output-formats/html-themes.qmd#dark-mode): If enabled, this option detects the user's operating system / browser preference for whether to show the page in light or dark mode.