From c6312bba250df649a627865e8682983c72324b1e Mon Sep 17 00:00:00 2001
From: Darren Burns <darrenb900@gmail.com>
Date: Thu, 24 Oct 2024 16:33:34 +0100
Subject: [PATCH] Documenting additional variables

---
 docs/guide/design.md | 78 ++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 72 insertions(+), 6 deletions(-)

diff --git a/docs/guide/design.md b/docs/guide/design.md
index 440b9aa188..bc63e71715 100644
--- a/docs/guide/design.md
+++ b/docs/guide/design.md
@@ -20,8 +20,6 @@ Theme(
     panel="#434C5E",
     dark=True,
     variables={
-        "block-cursor-background": "#88C0D0",
-        "block-cursor-foreground": "#2E3440",
         "block-cursor-text-style": "none",
         "footer-key-foreground": "#88C0D0",
         "input-selection-background": "#81a1c1 35%",
@@ -43,10 +41,6 @@ MyWidget {
 }
 ```
 
-The base colors are also used as the default values for other variables, such as `$border`.
-`$border` defines the border color of focused widgets and is set to `$primary` by default.
-These variables can also be overridden by passing a `variables` argument to the `Theme` constructor.
-
 ## Base colors
 
 When defining a theme, only the `primary` color is required.
@@ -102,6 +96,78 @@ The theme system defines three CSS variables which you can use to ensure that te
 - `$text-muted` sets a slightly faded text color. Use this for text which has lower importance. For instance a sub-title or supplementary information.
 - `$text-disabled` sets faded out text which indicates it has been disabled. For instance, menu items which are not applicable and can't be clicked.
 
+## Additional variables
+
+Textual uses the base colors as default values for additional variables used throughout the framework.
+These variables can be overridden by passing a `variables` argument to the `Theme` constructor.
+
+Here's a comprehensive list of these variables, their purposes, and default values:
+
+### Border
+
+| Variable | Purpose | Default Value |
+|----------|---------|---------------|
+| `$border` | The border color for focused widgets with a border | `$primary` |
+| `$border-blurred` | The border color for unfocused widgets | Slightly darkened `$surface` |
+
+### Cursor
+
+| Variable | Purpose | Default Value |
+|----------|---------|---------------|
+| `$block-cursor-foreground` | Text color for block cursor (e.g., in OptionList) | `$text` |
+| `$block-cursor-background` | Background color for block cursor | `$primary` |
+| `$block-cursor-text-style` | Text style for block cursor | `"bold"` |
+| `$block-cursor-blurred-foreground` | Text color for unfocused block cursor | `$text` |
+| `$block-cursor-blurred-background` | Background color for unfocused block cursor | `$primary` with 30% opacity |
+| `$block-cursor-blurred-text-style` | Text style for unfocused block cursor | `"none"` |
+| `$block-hover-background` | Background color when hovering over a block | `$boost` with 5% opacity |
+
+### Input
+
+| Variable | Purpose | Default Value |
+|----------|---------|---------------|
+| `$input-cursor-background` | Background color of the input cursor | `$foreground` |
+| `$input-cursor-foreground` | Text color of the input cursor | `$background` |
+| `$input-cursor-text-style` | Text style of the input cursor | `"none"` |
+| `$input-selection-background` | Background color of selected text | `$primary-lighten-1` with 40% opacity |
+| `$input-selection-foreground` | Text color of selected text | `$background` |
+
+### Scrollbar
+
+| Variable | Purpose | Default Value |
+|----------|---------|---------------|
+| `$scrollbar` | Color of the scrollbar | `$panel` |
+| `$scrollbar-hover` | Color of the scrollbar when hovered | `$panel-lighten-1` |
+| `$scrollbar-active` | Color of the scrollbar when active (being dragged) | `$panel-lighten-2` |
+| `$scrollbar-background` | Background color behind the scrollbar | `$background-darken-1` |
+| `$scrollbar-corner-color` | Color of the scrollbar corner | Same as `$scrollbar-background` |
+| `$scrollbar-background-hover` | Background color when hovering over the scrollbar area | Same as `$scrollbar-background` |
+| `$scrollbar-background-active` | Background color when the scrollbar is active | Same as `$scrollbar-background` |
+
+### Links
+
+| Variable | Purpose | Default Value |
+|----------|---------|---------------|
+| `$link-background` | Background color of links | `"initial"` |
+| `$link-background-hover` | Background color of links when hovered | `$primary` |
+| `$link-color` | Text color of links | `$text` |
+| `$link-style` | Text style of links | `"underline"` |
+| `$link-color-hover` | Text color of links when hovered | `$text` |
+| `$link-style-hover` | Text style of links when hovered | `"bold not underline"` |
+
+### Footer
+
+| Variable | Purpose | Default Value |
+|----------|---------|---------------|
+| `$footer-foreground` | Text color in the footer | `$foreground` |
+| `$footer-background` | Background color of the footer | `$panel` |
+| `$footer-key-foreground` | Text color for key bindings in the footer | `$accent` |
+| `$footer-key-background` | Background color for key bindings in the footer | `"transparent"` |
+| `$footer-description-foreground` | Text color for descriptions in the footer | `$foreground` |
+| `$footer-description-background` | Background color for descriptions in the footer | `"transparent"` |
+| `$footer-item-background` | Background color for items in the footer | `"transparent"` |
+
+
 ## Previewing colors
 
 Run the following from the command line to preview the colors defined in the color system: