Themes updates for 1.17 (#634)

Documents a whole pile of stuff from 1.17:

* `useMica` microsoft/terminal#13935
* theme pairs microsoft/terminal#14497
* scheme pairs microsoft/terminal#14064
* closes #626

TerminalDocs/custom-terminal-gallery/theme-gallery.md

@@ -64,3 +64,40 @@ Below are some examples of [Themes](./../customize-settings/themes.md).
 
 (Color scheme is based on [Fun Forrest](https://github.com/mbadolato/iTerm2-Color-Schemes/blob/master/windowsterminal/FunForrest.json))
 
+## Chonk
+
+![Windows Terminal Chonk Theme](./../images/Chonk-Theme.png)
+
+For best results, this theme is combined with the global settings `"alwaysShowTabs": true` and `"showTabsInTitlebar": false`, and a profile `opacity` of `0`. You may also want to disable the "Show accent color on title bars and windows borders" setting in the Windows settings app (under "Personalization > Colors")
+
+```json
+    "profiles": {
+        "defaults": {
+            "opacity": 0
+        }
+    },
+    "alwaysShowTabs": true,
+    "showTabsInTitlebar": false,
+    "theme": "chonk",
+    "themes": [
+        {
+            "name": "chonk",
+            "tab":
+            {
+                "background": "#00000000",
+                "unfocusedBackground": "#00000000",
+                "showCloseButton": "hover"
+            },
+            "tabRow":
+            {
+                "background": "#00000000",
+                "unfocusedBackground": "#00000000",
+            },
+            "window":
+            {
+                "applicationTheme": "dark",
+                "useMica": true
+            }
+        }
+    ]
+```

TerminalDocs/customize-settings/profile-appearance.md

@@ -28,14 +28,30 @@ The settings listed below affect the visual settings of each profile separately.
 
 This is the name of the color scheme used in the profile. Color schemes are defined in the `schemes` object. More detailed information can be found on the [Color schemes page](./color-schemes.md).
 
+In addition to a single color scheme name, this property can accept a pair of color scheme names as follows:
+
+```json
+"colorScheme":
+{
+    "light": "One Half Light",
+    "dark": "One Half Dark",
+},
+```
+
+When specified in this manner, the Terminal will automatically switch between the two given color schemes depending on the theme of the application. The Terminal will follow the [`theme.applicationTheme`](./themes.md#application-theme) property of the Terminal's selected theme. If that `applicationTheme` is set to `system`, then this will instead use the color scheme matching the OS theme.
+
 **Property name:** `colorScheme`
 
 **Necessity:** Optional
 
-**Accepts:** Name of color scheme as a string
+**Accepts:** Name of color scheme as a string, or an object with a `light` and `dark` property
 
 **Default value:** `"Campbell"`
 
+
+> [!IMPORTANT]
+> Specifying a pair of `light` and `dark` color schemes is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Font
 
 This is the structure within which the other font settings must be defined. An example of what this could look like in the JSON file is shown below.
@@ -358,6 +374,9 @@ When `useAcrylic` is set to `true`, the window will use the acrylic material to
 > [!IMPORTANT]
 > Unblurred opacity (`"useAcrylic": false`) only works on Windows 11.
 
+> [!IMPORTANT]
+> When Mica is enabled in the [theme settings](./themes.md#mica), Mica will appear underneath the Terminal contents when the `opacity` of the Terminal is set to a value <100.
+
 ### Enable acrylic
 
 :::row:::

TerminalDocs/customize-settings/themes.md

@@ -39,6 +39,15 @@ Each theme in the `themes` list is comprised of a collection of property objects
 },
 ```
 
+You may also configure the Terminal to use separate themes for light and dark mode in the OS and change automatically between those themes when the OS theme changes. To do this, specify the `theme` property as an object containing the keys `light` and `dark`:
+
+```json
+"theme": { "dark": "<Dark Theme Name>", "light": "<Light Theme Name>" },
+```
+
+> [!IMPORTANT]
+> Specifying a pair of `light` and `dark` themes is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Theme name
 
 This is the name of the theme. Names should be unique. The names `dark`, `light`, and `system` are reserved for the built-in default themes.
@@ -55,6 +64,10 @@ ___
 
 ## Window
 
+These settings are used to configure the appearance of the whole of the window of the Terminal.
+
+**Property name:** `window`
+
 ### Application theme
 
 This sets the UI theme of the application. This will stylize items such as buttons, the command palette, and other application UI elements. It can either be light or dark. `"system"` will use the same theme as Windows.
@@ -69,12 +82,55 @@ This sets the UI theme of the application. This will stylize items such as butto
 
 <br />
 
+### Mica
+
+This enables the Mica effect on this window, beneath all other UI layers. For Mica to be visible, the layers above it need to be transparent. As an example, to have a tab row with Mica in it you'll need to configure the alpha channel of the background to be `0` as follows:
+
+```json
+{
+    "name": "My Mica Theme",
+    "tab":
+    {
+        "background": "terminalBackground"
+    },
+    "tabRow":
+    {
+        "background": "#00000000"
+    },
+    "window":
+    {
+        "applicationTheme": "system",
+        "useMica": true
+    }
+},
+```
+
+Note that when Mica is enabled for the window it is enabled under the entirety of the window, including as a backdrop for the Terminal panes in the window. This means that profiles which are using `opacity` without `useAcrylic` enabled will show through to the new Mica background. It is not currently possible to have a unblurred transparent background for the Terminal and a Mica background for the tabs / tab row simultaneously.
+
+**Property name:** `useMica`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+> [!IMPORTANT]
+> Mica is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+> [!NOTE]
+> Mica is only available on Windows builds >= 22621.
+
+<br />
+
 ___
 
 ## Tab row
 
 These settings are used to configure the appearance of the tab row. When `showTabsInTitlebar` is `true` (the default), this configures the title bar.
 
+**Property name:** `tabRow`
+
 ### Background color
 
 The color of the tab row when the window is in the foreground.
@@ -101,6 +157,10 @@ ___
 
 ## Tabs
 
+These are settings that control the appearance of individual tabs in the Terminal.
+
+**Property name:** `tab`
+
 ### Background color
 
 The color of the active tab. Setting a `tabColor` in a profile will override this value. Similarly, setting a color at runtime with the tab color picker will override this color.