feat(theme): Note new default theme name and syntax (#3080)

**Migrated from atuinsh/docs PR:**
https://github.com/atuinsh/docs/pull/71
**Original author:** @philtweir

---

## What does this PR do?

* corrects the default theme name from `""` to `"default"`
* highlights the `@` color name in syntax
* explains the new _Meaning_: `Muted`
* comments on the (current) limitation of not being able to explicitly
"unset" the foreground

Co-authored-by: Phil Weir <phil.weir@flaxandteal.co.uk>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

2 files changed, 20 insertions, 9 deletions

diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md
index 408636a8..3dcc2aa2 100644
--- a/docs/docs/configuration/config.md
+++ b/docs/docs/configuration/config.md
@@ -691,17 +691,17 @@ The theme to use for showing the terminal interface.
 
 ```toml
 [theme]
-name = ""
+name = "default"
 debug = false
 max_depth = 10
 ```
 
 ### `name`
 
-Default: `""`
+Default: `"default"`
 
-A theme name that must be present as a built-in (an empty string for the default,
-`autumn` or `marine`), or found in the themes directory, with the suffix `.toml`.
+A theme name that must be present as a built-in (unset or `default` for the default,
+else `autumn` or `marine`), or found in the themes directory, with the suffix `.toml`.
 By default this is `~/.config/atuin/themes/` but can be overridden with the
 `ATUIN_THEME_DIR` environment variable.
 
diff --git a/docs/docs/guide/theming.md b/docs/docs/guide/theming.md
index a749d9cc..0a59d720 100644
--- a/docs/docs/guide/theming.md
+++ b/docs/docs/guide/theming.md
@@ -17,7 +17,7 @@ name = "THEMENAME"
 
 Where `THEMENAME` is a known theme. The following themes are available out-of-the-box:
 
-* default theme (can be explicitly referenced with an empty name `""`)
+* `default` theme
 * `autumn` theme
 * `marine` theme
 
@@ -59,6 +59,7 @@ to (at present) colors. In future, this may be expanded to allow richer style su
 * `Guidance`: instructing the user as help or context
 * `Important`: drawing the user's attention to information
 * `Title`: titling a section or view
+* `Muted`: anodyne, usually grey, foreground for contrast with other colors. Normally equivalent to the base color, but allows themes to change the base color, with less risk of breaking intentional color contrasts (e.g. stacked bar charts)
 
 These may expand over time as they are added to Atuin's codebase, but Atuin
 should have fallbacks added for any new *Meanings* so that, whether themes limit to
@@ -73,15 +74,25 @@ PRs, extend the Meanings enum if needed (along with a fallback Meaning!).
 When a theme name is read but not yet loaded, Atuin will look for it in the folder
 `~/.config/atuin/themes/` unless overridden by the `ATUIN_THEME_DIR` environment
 variable. It will attempt to open a file of name `THEMENAME.toml` and read it as a
-map from *Meanings* to colors.
+map from *Meanings* to foreground colors.
+
+Note that, at present, it is not possible to specify the default terminal color explicitly
+in a theme file. However, the default theme Base color will always be unset and therefore
+will be the user's default terminal color. Hence, you should only override the Base color
+in your theme, or derive from a theme that does so, if your theme would not make sense
+otherwise (e.g. the `marine` theme is intended to make everything green/blue, so it does,
+but the `autumn` theme only seeks to make the custom colors warmer, so it does not).
 
 Colors may be specified either as names from the [palette](https://ogeon.github.io/docs/palette/master/palette/named/index.html)
-crate in lowercase, or as six-character hex codes, prefixed with `#`. For example,
-the following are valid color names:
+crate in lowercase, or as six-character hex codes, prefixed with `#`. To explicitly select ANSI colors by integer, or for greater flexibility in general, you can prefix with `@` and the rest of the string will be handled by crossterm's color parsing. For examples, see [crossterm's color deserialization tests](https://github.com/crossterm-rs/crossterm/blob/5d50d8da62c5e034ef8b2787a771a2c0f9b3b2f9/src/style/types/color.rs#L389), remembering the need to add a `@` prefix for atuin.
+
+For example, the following are valid color names:
 
 * `#ff0088`
 * `teal`
 * `powderblue`
+* `@ansi_(255)`
+* `@rgb_(255, 128, 0)`
 
 A theme file, say `my-theme.toml` can then be built up, such as:
 
@@ -98,7 +109,7 @@ Guidance = "#888844"
 
 where not all of the *Meanings* need to be explicitly defined. If they are absent,
 then the color will be chosen from the parent theme, if one is defined, or if that
-key is missing in the `theme` block, from the default theme.
+key is missing in the `theme` block, from the `default` theme.
 
 This theme file should be moved to `~/.config/atuin/themes/my-theme.toml` and the
 following added to `~/.config/atuin/config.toml`: