From 4897b9d1b7a447def4def388f61559aa56b5e2a7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?=
 <5621605+rodrigogiraoserrao@users.noreply.github.com>
Date: Thu, 15 Dec 2022 16:16:21 +0000
Subject: [PATCH] Complete border reference.

---
 docs/styles/border.md | 98 +++++++++++++++++++++++++++++++------------
 1 file changed, 72 insertions(+), 26 deletions(-)

diff --git a/docs/styles/border.md b/docs/styles/border.md
index 757ce988b..710bcb601 100644
--- a/docs/styles/border.md
+++ b/docs/styles/border.md
@@ -1,50 +1,77 @@
 # Border
 
-The `border` rule enables the drawing of a box around a widget. A border is set with a border value (see below) followed by a color.
+The `border` rule enables the drawing of a box around a widget. A border is set with a border type (see below) and a color.
 
 Borders may also be set individually for the four edges of a widget with the `border-top`, `border-right`, `border-bottom` and `border-left` rules.
 
 ## Syntax
 
 ```
-border: [<COLOR>] [<BORDER VALUE>];
-border-top: [<COLOR>] [<BORDER VALUE>];
-border-right: [<COLOR>] [<BORDER VALUE>];
-border-bottom: [<COLOR>] [<BORDER VALUE>];
-border-left: [<COLOR>] [<BORDER VALUE>];
+border: [<BORDER TYPE>] [<COLOR>];
+border-top: [<BORDER TYPE>] [<COLOR>];
+border-right: [<BORDER TYPE>] [<COLOR>];
+border-bottom: [<BORDER TYPE>] [<COLOR>];
+border-left: [<BORDER TYPE>] [<COLOR>];
 ```
 
-### Values
+### Border types
 
-| Border value | Description                                             |
-|--------------|---------------------------------------------------------|
-| `"ascii"`    | A border with plus, hyphen, and vertical bar            |
-| `"blank"`    | A blank border (reserves space for a border)            |
-| `"dashed"`   | Dashed line border                                      |
-| `"double"`   | Double lined border                                     |
-| `"heavy"`    | Heavy border                                            |
-| `"hidden"`   | Alias for "none"                                        |
-| `"hkey"`     | Horizontal key-line border                              |
-| `"inner"`    | Thick solid border                                      |
-| `"none"`     | Disabled border                                         |
-| `"outer"`    | Think solid border with additional space around content |
-| `"round"`    | Rounded corners                                         |
-| `"solid"`    | Solid border                                            |
-| `"tall"`     | Solid border with extras space top and bottom           |
-| `"vkey"`     | Vertical key-line border                                |
-| `"wide"`     | Solid border with additional space left and right       |
+| Border type | Description                                             |
+|-------------|---------------------------------------------------------|
+| `"ascii"`   | A border with plus, hyphen, and vertical bar characters |
+| `"blank"`   | A blank border (reserves space for a border)            |
+| `"dashed"`  | Dashed line border                                      |
+| `"double"`  | Double lined border                                     |
+| `"heavy"`   | Heavy border                                            |
+| `"hidden"`  | Alias for "none"                                        |
+| `"hkey"`    | Horizontal key-line border                              |
+| `"inner"`   | Thick solid border                                      |
+| `"none"`    | Disabled border                                         |
+| `"outer"`   | Solid border with additional space around content       |
+| `"round"`   | Rounded corners                                         |
+| `"solid"`   | Solid border                                            |
+| `"tall"`    | Solid border with extras space top and bottom           |
+| `"vkey"`    | Vertical key-line border                                |
+| `"wide"`    | Solid border with additional space left and right       |
 
 For example, `heavy white` would display a heavy white line around a widget.
 
+### Color syntax
+
+--8<-- "docs/styles/snippets/color_css_syntax.md"
+
+### Multiple edge rules
+
+If multiple border rules target the same edge, the last rule that targets a specific edge is the one that is applied to that edge.
+For example, consider the CSS below:
+
+```sass
+Static {
+    border-top: dashed red;
+    border: solid green;  /* overrides the border-top rule above */
+    /* Change the border but just for the bottom edge: */
+    border-bottom: double blue;
+}
+```
+
+The CSS snippet above will add a solid green border around `Static` widgets, except for the bottom edge, which will be double blue.
+
+### Defaults
+
+If a border color is specified but the border type is omitted, it defaults to solid.
+If a border type is specified but the border color is omitted, it defaults to green (RGB color `"#00FF00"`).
+
 ## Border command
 
-The `textual` CLI has a subcommand which will let you explore the various border types:
+The `textual` CLI has a subcommand which will let you explore the various border types interactively:
 
 ```
 textual borders
 ```
 
-## Example
+Alternatively, you can see the examples below.
+
+## Examples
 
 This examples shows three widgets with different border styles.
 
@@ -65,6 +92,25 @@ This examples shows three widgets with different border styles.
     ```{.textual path="docs/examples/styles/border.py"}
     ```
 
+The next example shows a grid with all the available border types.
+
+=== "border_all.py"
+
+    ```py
+    --8<-- "docs/examples/styles/border_all.py"
+    ```
+
+=== "border_all.css"
+
+    ```css
+    --8<-- "docs/examples/styles/border_all.css"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/border_all.py"}
+    ```
+
 ## CSS
 
 ```sass