improve a bit the file formats docs

docs/file-formats/README.md

@@ -12,6 +12,6 @@ Lona additionally consumes a variety of other file formats for building design s
 |---|---|
 |[Colors](./colors.md)|`colors.json`|
 |[Text Styles](./text-styles.md)|`textStyles.json`|
-|Gradients|`gradients.json`|
-|Shadows|`shadows.json`|
-|Types|`types.json`|
+|[Gradients](./gradients.md)|`gradients.json`|
+|[Shadows](./shadows.md)|`shadows.json`|
+|Types|`types.json`|

docs/file-formats/colors.md

@@ -16,7 +16,6 @@ Each color has the following attributes:
 |`comment`|`string`|No|An optional description of the color, explaining contextual information, such as how it should be used. This may be displayed in the Lona Studio UI. This will not appear in the generated code. |
 
 
-
 ### Color Type
 
 Colors may be referenced from other files by their `id` (a `string`). This helps us achieve a single source of truth for colors.
@@ -25,7 +24,7 @@ Colors may also appear _inline_ in other files (where a CSS color value is given
 
 ### Sample File
 
-`cscolors.json`
+`colors.json`
 
 ```json
 {
@@ -44,4 +43,4 @@ Colors may also appear _inline_ in other files (where a CSS color value is given
     }
   ]
 }
-```
+```

docs/file-formats/gradients.md

@@ -0,0 +1,41 @@
+# Gradient Definitions
+
+This file defines the design system's gradients.
+
+### Specification
+
+At the top level, the file is an object containing a `"gradients"` array.
+
+Each gradient within the `"gradients"` array has the following attributes:
+
+|Attribute|Type|Required|Description|
+|---|---|---|---|
+|`id`|`string`|Yes|The unique `id` of the gradient, which will be used internally by Lona Studio and in the generated code. This should be _code-friendly_: it must not contain spaces or unusual characters, since it will be used as a variable name.|
+|`name`|`string`|Yes|The human-readable name of the gradient. This will be displayed in the Lona Studio UI. This will not appear in the generated code.|
+|`comment`|`string`|No|An optional description of the gradient, explaining contextual information, such as how it should be used. This may be displayed in the Lona Studio UI. This will not appear in the generated code. |
+|`colorStops`|`Array<{ position: number, color: Color }>`|Yes|The stops of the gradient.|
+
+### Sample File
+
+`gradients.json`
+
+```json
+{
+  "gradients": [
+    {
+      "id": "gradient1",
+      "name": "Gradient 1",
+      "colorStops": [
+        {
+          "position": 0,
+          "color": "black"
+        },
+        {
+          "position": 1,
+          "color": "white"
+        }
+      ]
+    }
+  ]
+}
+```

docs/file-formats/shadows.md

@@ -0,0 +1,57 @@
+# Shadow Definitions
+
+This file defines the design system's shadows.
+
+### Specification
+
+At the top level, the file is an object containing a `"shadows"` array and optionally a `"defaultShadowName"` string.
+
+Each shadow within the `"shadows"` array has the following attributes:
+
+|Attribute|Type|Required|Description|
+|---|---|---|---|
+|`id`|`string`|Yes|The unique `id` of the shadow, which will be used internally by Lona Studio and in the generated code. This should be _code-friendly_: it must not contain spaces or unusual characters, since it will be used as a variable name.|
+|`name`|`string`|Yes|The human-readable name of the shadow. This will be displayed in the Lona Studio UI. This will not appear in the generated code.|
+|`comment`|`string`|No|An optional description of the shadow, explaining contextual information, such as how it should be used. This may be displayed in the Lona Studio UI. This will not appear in the generated code. |
+|`x`|`number`|No|The horizontal offset of the shadow, in pixel.|
+|`y`|`number`|No|The vertical offset of the shadow, in pixel.|
+|`blur`|`number`|No|The blur radius of the shadow, in pixels.|
+|`color`|[`Color`](./colors.md#color-type)|No|The CSS color value or the `id` of the color defined in `colors.json`.|
+
+The optional `"defaultShadowName"` determines the style of newly-created shadow within Lona Studio. This value should be the `id` of one of the shadows in the `"shadow"` array. This value will not be used in code.
+
+### Sample File
+
+`shadows.json`
+
+```json
+{
+  "defaultShadowName": "elevation1",
+  "shadows": [
+    {
+      "id": "elevation1",
+      "name": "Elevation 1",
+      "color": "black",
+      "x": 0,
+      "y": 2,
+      "blur": 4
+    },
+    {
+      "id": "elevation2",
+      "name": "Elevation 2",
+      "color": "red",
+      "x": 0,
+      "y": -2,
+      "blur": 4
+    },
+    {
+      "id": "elevation3",
+      "name": "Elevation 3",
+      "color": "yellow",
+      "x": 0,
+      "y": -4,
+      "blur": 4
+    }
+  ]
+}
+```

docs/file-formats/text-styles.md

@@ -2,7 +2,9 @@
 
 This file defines the design system's text styles.
 
-At the top level, the file is an object containing a `"styles"` array and optionally a `"defaultStyleId"` string.
+### Specification
+
+At the top level, the file is an object containing a `"styles"` array and optionally a `"defaultStyleName"` string.
 
 Each text style within the `"styles"` array has the following attributes:
 
@@ -11,14 +13,16 @@ Each text style within the `"styles"` array has the following attributes:
 |`id`|`string`|Yes|The unique `id` of the text style, which will be used internally by Lona Studio and in the generated code. This should be _code-friendly_: it must not contain spaces or unusual characters, since it will be used as a variable name.|
 |`name`|`string`|Yes|The human-readable name of the text style. This will be displayed in the Lona Studio UI. This will not appear in the generated code.|
 |`comment`|`string`|No|An optional description of the text style, explaining contextual information, such as how it should be used. This may be displayed in the Lona Studio UI. This will not appear in the generated code. |
+|`fontName`|`string`|No|The name of the font.|
 |`fontFamily`|`string`|No|The name of the font family.|
 |`fontWeight`|`string`|No|The weight of the font, in CSS values: a string in increments of 100, from 100 to 900.|
 |`fontSize`|`number`|No|The size of the font, in pixels.|
 |`lineHeight`|`number`|No|The height of each line of text, in pixels.|
 |`letterSpacing`|`number`|No|Uniformly adjust the spacing between each character. A positive number indicates more space, while a negative number indicates less space.|
-|`color`|[`Color`](./colors.md#color-type)|No|The CSS color value or the `id` of the color defined in `cscolors.json`.|
+|`color`|[`Color`](./colors.md#color-type)|No|The CSS color value or the `id` of the color defined in `colors.json`.|
+|`extends`|`string`|No|The `id` of the another text style to extend.|
 
-The optional `"defaultStyleId"` determines the style of newly-created text within Lona Studio. This value should be the `id` of one of the text styles in the `"styles"` array. This value will not be used in code.
+The optional `"defaultStyleName"` determines the style of newly-created text within Lona Studio. This value should be the `id` of one of the text styles in the `"styles"` array. This value will not be used in code.
 
 ### Sample File