Broadens composite type definition and removes gradient stops as a st…

…andalone type.

technical-reports/format/composite-types.md

@@ -6,9 +6,7 @@ Every shadow style has the exact same parts (color, X & Y offsets, etc.), but th
 
 Specifically, a composite type has the following characteristics:
 
-- Its value is an object or array containing sub-values.
-- For object values, each sub-value has a pre-defined name and type.
-- For array values, all elements of the array are sub-values that have the same pre-defined type.
+- Its value is an object or array, potentially containing nested objects or arrays, following a pre-defined structure where the properties of the (nested) object(s) or the elements of the (nested) arrays are sub-values.
 - Sub-values may be explicit values (e.g. `"#ff0000"`) or references to other design tokens that have sub-value's type (e.g. `"{some.other.token}"`).
 
 A design token whose type happens to be a composite type is sometimes also called a composite (design) token. Besides their type, there is nothing special about composite tokens. They can have all the other additional properties like [description](#description) or [extensions](#extensions). They can also be referenced by other design tokens.
@@ -90,7 +88,7 @@ At first glance, groups and composite tokens might look very similar. However, t
   - Their type must be one of the composite types defined in this specification. Therefore their names and types of their sub-values are pre-defined. Adding additional sub-values or setting values that don't have the correct type make the composite token invalid.
   - Tools MAY provide specialised functionality for composite tokens. For example, a design tool may let the user pick from a list of all available shadow tokens when applying a drop shadow effect to an element.
 
-# Border
+## Border
 
 Represents a border style. The type property must be set to the string “border”. The value must be an object with the following properties:
 
@@ -125,11 +123,11 @@ Represents a border style. The type property must be set to the string “border
 
 </aside>
 
-# Transition
+## Transition
 
 TO-DO
 
-# Shadow
+## Shadow
 
 Represents a shadow style. The type property must be set to the string “shadow”. The value must be an object with the following properties:
 
@@ -139,16 +137,14 @@ Represents a shadow style. The type property must be set to the string “shadow
 - `blur`: The blur radius that is applied to the shadow. The value of this property must be a valid [dimension value](#dimension) or a reference to a dimension token.
 - `spread`: The amount by which to expand or contract the shadow. The value of this property must be a valid [dimension value](#dimension) or a reference to a dimension token.
 
-# Gradient Stop
+## Gradient
 
-Represents an individual stop on a color gradient. In practice, this type is unlikely to be useful by itself, but it is required by the [gradient type](#gradient). The value must be an object with the following properties:
+Represents a color gradient. The value must be an array of objects representing gradient stops that have the following structure:
 
 - `color`: The color value at the stop's position on the gradient. The value of this property must be a valid [color value](#color) or a reference to a color token.
 - `position`: The position of the stop along the gradient's axis. The value of this property must be a valid number value or reference to a number token. The number values must be in the range [0, 1], where 0 represents the start position of the gradient's axis and 1 the end position. If a number value outside of that range is given, it MUST be considered as if it were clamped to the range [0, 1]. For example, a value of 42 should be treated as if it were 1, i.e. the end position of the gradient axis. Similarly, a value of -99 should be treated as if it were 0, i.e. the start position of the gradient axis.
 
-# Gradient
-
-Represents a color gradient. The value must be an array of [gradient stops](#gradient-stop). If there are no stops at the very beginning or end of the gradient axis (i.e. with `position` 0 or 1, respectively), then the color from the stop closest to each end should be extended to that end of the axis.
+If there are no stops at the very beginning or end of the gradient axis (i.e. with `position` 0 or 1, respectively), then the color from the stop closest to each end should be extended to that end of the axis.
 
 <aside class="example" title="Gradient token example">
 
@@ -159,11 +155,11 @@ Represents a color gradient. The value must be an array of [gradient stops](#gra
     "value": [
       {
         "color": "#0000ff",
-        "pos": 0
+        "position": 0
       },
       {
         "color": "#ff0000",
-        "pos": 1
+        "position": 1
       }
     ]
   }
@@ -185,11 +181,11 @@ Describes a gradient that goes from blue to red:
     "value": [
       {
         "color": "#ffff00",
-        "pos": 0.666
+        "position": 0.666
       },
       {
         "color": "#ff0000",
-        "pos": 1
+        "position": 1
       }
     ]
   }
@@ -220,15 +216,15 @@ Describes a gradient that is solid yellow for the first 2/3 and then fades to re
     "value": [
       {
         "color": "#000000",
-        "pos": 0
+        "position": 0
       },
       {
         "color": "{brand-primary}",
-        "pos": 0.5
+        "position": 0.5
       },
       {
         "color": "#000000",
-        "pos": "{position-end}"
+        "position": "{position-end}"
       }
     ]
   }
@@ -241,7 +237,7 @@ Describes a color token called "brand-primary", which is referenced as the mid-p
 
 </aside>
 
-# Typography
+## Typography
 
 Represents a typographic style. The type property must be set to the string “typography”. The value must be an object with the following properties: