more docs

docs/styles/border.md

@@ -0,0 +1,55 @@
+# Border
+
+The `border` rule enables the drawing of a box around a widget. A border is set with a border style (see below) followed by a color.
+
+- `"ascii"`
+- `"round"`
+- `"solid"`
+- `"double"`
+- `"dashed"`
+- `"heavy"`
+- `"inner"`
+- `"outer"`
+- `"hkey"`
+- `"vkey"`
+- `"tall"`
+- `"wide"`
+
+For examples `heavy white` would display a heavy white line around a widget.
+
+Borders may also be set individually with the `border-top`, `border-right`, `border-bottom` and `border-left` rules.
+
+## Example
+
+This examples shows three widgets with different border styles.
+
+=== "border.py"
+
+    ```python
+    --8<-- "docs/examples/styles/border.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/border.py"}
+    ```
+
+## CSS
+
+```sass
+/* Set a heavy white border */
+border: heavy white;
+
+/* set a red border on the left */
+border-left: outer red;
+```
+
+## Python
+
+```python
+# Set a heavy white border
+widget.border = ("heavy", "white)
+
+# Set a red border on the left
+widget.border_left = ("outer", "red)
+```

docs/styles/box_sizing.md

@@ -0,0 +1,42 @@
+# Box-sizing
+
+The `box-sizing` rule impacts how `width` and `height` rules are translated in to screen dimensions, when combined with `padding` and `border`.
+
+The default value is `border-box` which means that padding and border are included in in the width and height. This setting means that if you add padding and/or border the widget will not change in size, but you will have less space for content.
+
+You can set `box-sizing` to `content-box` which tells Textual that padding and border should increase the size of the widget, leaving the content area unaffected.
+
+## Example
+
+Both widgets in this example have the same height (5). The top widget has `box-sizing: border-box` which means that padding and border reduces the space for content. The bottom widget has `box-sizing: content-box` which increases the size of the widget to compensate for padding and border.
+
+=== "box_sizing.py"
+
+    ```python
+    --8<-- "docs/examples/styles/box_sizing.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/box_sizing.py"}
+    ```
+
+## CSS
+
+```sass
+/* Set box sizing to border-box (default) */
+box-sizing: border-box;
+
+/* Set box sizing to content-box */
+box-sizing: content-box;
+```
+
+## Python
+
+```python
+# Set box sizing to border-box (default)
+widget.box_sizing = "border-box"
+
+# Set box sizing to content-box
+widget.box_sizing = "content-box"
+```

docs/styles/color.md

@@ -16,10 +16,10 @@ The `color` rule sets the text color of a Widget.
 ## CSS
 
 ```sass
-/* Blue background */
+/* Blue text */
 color: blue;
 
-/* 20% red backround */
+/* 20% red text */
 color: red 20%;
 
 /* RGB color */
@@ -31,7 +31,7 @@ color: rgb(100,120,200);
 You can use the same syntax as CSS, or explicitly set a Color object.
 
 ```python
-# Set blue background
+# Set blue text
 widget.styles.color = "blue"
 
 from textual.color import Color

docs/styles/height.md

@@ -1,6 +1,6 @@
 # Height
 
-The `height` style sets a widget's height. By default, it sets the width of the content area, but if `box-sizing` is set to `border-box` it sets the width of the border area.
+The `height` style sets a widget's height. By default, it sets the height of the content area, but if `box-sizing` is set to `border-box` it sets the height of the border area.
 
 ## Example
 

docs/styles/margin.md

@@ -2,9 +2,11 @@
 
 The `margin` rule adds space around the entire widget.
 
-- `1` Sets a margin of 1 around all 4 edges
-- `1 2` Sets a margin of 1 on the top and bottom edges, and a margin of 2 on the left and right edges
-- `1 2 3 4` Sets a margin of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left.
+- `margin: 1;` Sets a margin of 1 around all 4 edges
+- `margin: 1 2;` Sets a margin of 1 on the top and bottom edges, and a margin of 2 on the left and right edges
+- `margin: 1 2 3 4;` Sets a margin of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left.
+
+Margin may also be set individually, following the same pattern as above, by setting `margin-top`, `margin-right`, `margin-bottom`, or `margin-left`.
 
 ## Example
 

docs/styles/outline.md

@@ -0,0 +1,57 @@
+# Outline
+
+The `outline` rule enables the drawing of a box around a widget. Similar to `border`, but unlike border, outline will draw over the content area. This rule can be useful for emphasis if you want to display a outline for a brief time to draw the user's attention to it.
+
+An outline is set with a border style (see below) followed by a color.
+
+- `"ascii"`
+- `"round"`
+- `"solid"`
+- `"double"`
+- `"dashed"`
+- `"heavy"`
+- `"inner"`
+- `"outer"`
+- `"hkey"`
+- `"vkey"`
+- `"tall"`
+- `"wide"`
+
+For examples `heavy white` would display a heavy white line around a widget.
+
+Outlines may also be set individually with the `outline-top`, `outline-right`, `outline-bottom` and `outline-left` rules.
+
+## Example
+
+This examples shows a widget with an outline. Note how the outline occludes the text area.
+
+=== "outline.py"
+
+    ```python
+    --8<-- "docs/examples/styles/outline.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/outline.py"}
+    ```
+
+## CSS
+
+```sass
+/* Set a heavy white outline */
+outline: heavy white;
+
+/* set a red outline on the left */
+outline-left: outer red;
+```
+
+## Python
+
+```python
+# Set a heavy white outline
+widget.outline = ("heavy", "white)
+
+# Set a red outline on the left
+widget.outline_left = ("outer", "red)
+```

docs/styles/padding.md

@@ -2,9 +2,11 @@
 
 The padding rule adds space around the content of a widget. You can specify padding with 1, 2 or 4 numbers.
 
-- `1` Sets a padding of 1 around all 4 edges
-- `1 2` Sets a padding of 1 on the top and bottom edges, and a padding of two on the left and right edges
-- `1 2 3 4` Sets a padding of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left.
+- `padding: 1;` Sets a padding of 1 around all 4 edges
+- `padding: 1 2;` Sets a padding of 1 on the top and bottom edges, and a padding of two on the left and right edges
+- `padding: 1 2 3 4;` Sets a padding of one on the top edge, 2 on the right, 3 on the bottom, and 4 on the left.
+
+Padding may also be set individually, following the same pattern as above, by setting `padding-top`, `padding-right`, `padding-bottom`, or `padding-left`.
 
 ## Example