Proposal: changes to dimension and duration tokens

design-tokens · Aug 16, 2024 · f5af127 · f5af127
1 parent e751860
commit f5af127
Show file tree

Hide file tree

Showing 5 changed files with 90 additions and 41 deletions.
diff --git a/technical-reports/format/composite-types.md b/technical-reports/format/composite-types.md
@@ -19,10 +19,10 @@ A design token whose type happens to be a composite type is sometimes also calle
     "$type": "shadow",
     "$value": {
       "color": "#00000080",
-      "offsetX": "0.5rem",
-      "offsetY": "0.5rem",
-      "blur": "1.5rem",
-      "spread": "0rem"
+      "offsetX": { "value": 0.5, "unit": "rem" },
+      "offsetY": { "value": 0.5, "unit": "rem" },
+      "blur": { "value": 1.5, "unit": "rem" },
+      "spread": { "value": 0, "unit": "rem" }
     }
   }
 }
@@ -37,7 +37,7 @@ A design token whose type happens to be a composite type is sometimes also calle
   "space": {
     "small": {
       "$type": "dimension",
-      "$value": "0.5rem"
+      "$value": { "value": 0.5, "unit": "rem" }
     }
   },
 
@@ -56,8 +56,8 @@ A design token whose type happens to be a composite type is sometimes also calle
         "color": "{color.shadow-050}",
         "offsetX": "{space.small}",
         "offsetY": "{space.small}",
-        "blur": "1.5rem",
-        "spread": "0rem"
+        "blur": { "value": 1.5, "unit": "rem" },
+        "spread": { "value": 0, "unit": "rem" }
       }
     }
   },
@@ -96,7 +96,7 @@ Represents the style applied to lines or borders. The `$type` property MUST be s
 - an object value as defined in the corresponding section below
 
 <div class="issue" data-number="98" title="Stroke style type feedback">
-  Is the current specification for stroke styles fit for purpose? Does it need more sub-values (e.g. equivalents to SVG's `stroke-linejoin`, `stroke-miterlimit` and `stroke-dashoffset` attributes)? 
+  Is the current specification for stroke styles fit for purpose? Does it need more sub-values (e.g. equivalents to SVG's `stroke-linejoin`, `stroke-miterlimit` and `stroke-dashoffset` attributes)?
 </div>
 
 ### String value
@@ -141,7 +141,10 @@ Object stroke style values MUST have the following properties:
   "alert-border-style": {
     "$type": "strokeStyle",
     "$value": {
-      "dashArray": ["0.5rem", "0.25rem"],
+      "dashArray": [
+        { "value": 0.5, "unit": "rem" },
+        { "value": 0.25, "unit": "rem" }
+      ],
       "lineCap": "round"
     }
   }
@@ -157,14 +160,17 @@ Object stroke style values MUST have the following properties:
   "notification-border-style": {
     "$type": "strokeStyle",
     "$value": {
-      "dashArray": ["{dash-length-medium}", "0.25rem"],
+      "dashArray": ["{dash-length-medium}", { "value": 0.25, "unit": "rem" }],
       "lineCap": "butt"
     }
   },
 
   "dash-length-medium": {
     "$type": "dimension",
-    "$value": "10px"
+    "$value": {
+      "value": 10,
+      "unit": "px"
+    }
   }
 }
 ```
@@ -214,17 +220,23 @@ Represents a border style. The `$type` property MUST be set to the string `borde
       "$type": "border",
       "$value": {
         "color": "#36363600",
-        "width": "3px",
+        "width": {
+          "value": 3,
+          "unit": "px"
+        },
         "style": "solid"
       }
     },
     "focusring": {
       "$type": "border",
       "$value": {
         "color": "{color.focusring}",
-        "width": "1px",
+        "width": {
+          "value": 1,
+          "unit": "px"
+        },
         "style": {
-          "dashArray": ["0.5rem", "0.25rem"],
+          "dashArray": [{ "value": 0.5, "unit": "rem" }, "0.25rem"],
           "lineCap": "round"
         }
       }
@@ -255,8 +267,8 @@ Represents a animated transition between two states. The `$type` property MUST b
     "emphasis": {
       "$type": "transition",
       "$value": {
-        "duration": "200ms",
-        "delay": "0ms",
+        "duration": { "value": 200, "unit": "ms" },
+        "delay": { "value": 0 },
         "timingFunction": [0.5, 0, 1, 1]
       }
     }
@@ -288,10 +300,10 @@ Represents a shadow style. The `$type` property MUST be set to the string `shado
     "$type": "shadow",
     "$value": {
       "color": "#00000080",
-      "offsetX": "0.5rem",
-      "offsetY": "0.5rem",
-      "blur": "1.5rem",
-      "spread": "0rem"
+      "offsetX": { "value": 0.5, "unit": "rem" },
+      "offsetY": { "value": 0.5, "unit": "rem" },
+      "blur": { "value": 1.5, "unit": "rem" },
+      "spread": { "value": 0, "unit": "rem" }
     }
   }
 }
@@ -300,7 +312,7 @@ Represents a shadow style. The `$type` property MUST be set to the string `shado
 </aside>
 
 <div class="issue" data-number="100" title="Shadow type feedback">
-  Is the current specification for shadows fit for purpose? Does it need to support multiple shadows, as some tools and platforms do? 
+  Is the current specification for shadows fit for purpose? Does it need to support multiple shadows, as some tools and platforms do?
 </div>
 
 ## Gradient
@@ -427,9 +439,15 @@ Represents a typographic style. The `$type` property MUST be set to the string `
       "$type": "typography",
       "$value": {
         "fontFamily": "Roboto",
-        "fontSize": "42px",
+        "fontSize": {
+          "value": 42,
+          "unit": "px"
+        },
         "fontWeight": 700,
-        "letterSpacing": "0.1px",
+        "letterSpacing": {
+          "value": 0.1,
+          "unit": "px"
+        },
         "lineHeight": 1.2
       }
     },
@@ -439,7 +457,10 @@ Represents a typographic style. The `$type` property MUST be set to the string `
         "fontFamily": "{font.serif}",
         "fontSize": "{font.size.smallest}",
         "fontWeight": "{font.weight.normal}",
-        "letterSpacing": "0px",
+        "letterSpacing": {
+          "value": 0,
+          "unit": "px"
+        },
         "lineHeight": 1
       }
     }

diff --git a/technical-reports/format/design-token.md b/technical-reports/format/design-token.md
@@ -34,12 +34,15 @@ Token names are case-sensitive, so the following example with 2 tokens in the sa
 ```json
 {
   "font-size": {
-    "$value": "3rem",
+    "$value": { "value": 3, "unit": "rem" },
     "$type": "dimension"
   },
 
   "FONT-SIZE": {
-    "$value": "16px",
+    "$value": {
+      "value": 16,
+      "unit": "px"
+    },
     "$type": "dimension"
   }
 }

diff --git a/technical-reports/format/groups.md b/technical-reports/format/groups.md
@@ -12,7 +12,7 @@ A file MAY contain many tokens and they MAY be nested arbitrarily in groups like
   },
   "token group": {
     "token dos": {
-      "$value": "2rem",
+      "$value": { "value": 2, "unit": "rem" },
       "$type": "dimension"
     },
     "nested token group": {
@@ -41,7 +41,7 @@ The names of the groups leading to a given token (including that token's name) a
 - Token #2
   - Name: "token dos"
   - Path: "token group" / "token dos"
-  - Value: "2rem"
+  - Value: { "value": 2, "unit": "rem" }
   - Type: "dimension"
 - Token #3
   - Name: "token tres"

diff --git a/technical-reports/format/terminology.md b/technical-reports/format/terminology.md
@@ -125,10 +125,10 @@ Here's [an example of a composite shadow token](https://design-tokens.github.io/
     "$type": "shadow",
     "$value": {
       "color": "#00000080",
-      "offsetX": "0.5rem",
-      "offsetY": "0.5rem",
-      "blur": "1.5rem",
-      "spread": "0rem"
+      "offsetX": { "value": 0.5, "unit": "rem" },
+      "offsetY": { "value": 0.5, "unit": "rem" },
+      "blur": { "value": 1.5, "unit": "rem" },
+      "spread": { "value": 0, "unit": "rem" }
     }
   }
 }

diff --git a/technical-reports/format/types.md b/technical-reports/format/types.md
@@ -51,7 +51,12 @@ $translucent-shadow: hsla(300, 100%, 50%, 0.5);
 
 ## Dimension
 
-Represents an amount of distance in a single dimension in the UI, such as a position, width, height, radius, or thickness. The `$type` property MUST be set to the string `dimension`. The value must be a string containing a number (either integer or floating-point) followed by either a "px" or "rem" unit (future spec iterations may add support for additional units). This includes `0` which also MUST be followed by either a "px" or "rem" unit.
+Represents an amount of distance in a single dimension in the UI, such as a position, width, height, radius, or thickness. The `$type` property MUST be set to the string `dimension`. The value MUST be an object with `value` and `unit` keys.
+
+| Key     |   Type   | Required | Description                                                        |
+| :------ | :------: | :------: | :----------------------------------------------------------------- |
+| `value` | `number` |    Y     | An integer or floating-point value representing the numeric value. |
+| `unit`  | `string` |    Y     | A string specifying the units of measurement                       |
 
 For example:
 
@@ -60,22 +65,29 @@ For example:
 ```json
 {
   "spacing-stack-0": {
-    "$value": "0rem",
+    "$value": {
+      "value": 0,
+      "unit": "px"
+    },
     "$type": "dimension"
   },
   "spacing-stack-1": {
-    "$value": "0.25rem",
+    "$value": {
+      "value": 0.5,
+      "unit": "rem"
+    },
     "$type": "dimension"
   }
 }
 ```
 
 </aside>
 
-The "px" and "rem" units are to be interpreted the same way they are in CSS:
+### Validation
 
-- **px**: Represents an idealized pixel on the viewport. The equivalent in Android is dp and iOS is pt. Translation tools SHOULD therefore convert to these or other equivalent units as needed.
-- **rem**: Represents a multiple of the system's default font size (which MAY be configurable by the user). 1rem is 100% of the default font size. The equivalent of 1rem on Android is 16sp. Not all platforms have an equivalent to rem, so translation tools MAY need to do a lossy conversion to a fixed px size by assuming a default font size (usually 16px) for such platforms.
+- `$value.unit` may be any string. It is up to tooling to translate units into the appropriate platform.
+- `$value.unit` may NOT be an empty string (`""`).
+- `$value.unit` is still requird even if `$value.value` is `0`.
 
 ## Font family
 
@@ -148,7 +160,12 @@ Example:
 
 ## Duration
 
-Represents the length of time in milliseconds an animation or animation cycle takes to complete, such as 200 milliseconds. The `$type` property MUST be set to the string `duration`. The value MUST be a string containing a number (either integer or floating-point) followed by an "ms" unit. A millisecond is a unit of time equal to one thousandth of a second.
+Represents the length of time in milliseconds an animation or animation cycle takes to complete, such as 200 milliseconds. The `$type` property MUST be set to the string `duration`. The value MUST be an object containin a numeric `value` (either integer or floating-point) and optionally a `unit` to specify milliseconds (`"ms"`) or seconds (`"s"`). A millisecond is a unit of time equal to one thousandth of a second.
+
+| Key     |   Type   | Required | Description                                                            |
+| :------ | :------: | :------: | :--------------------------------------------------------------------- |
+| `value` | `number` |    Y     | An integer or floating-point value representing the numeric value.     |
+| `unit`  | `string` |          | The unit of time. Only `"ms"`, `"s`", or (undefined) are valid values. |
 
 For example:
 
@@ -157,18 +174,26 @@ For example:
 ```json
 {
   "Duration-100": {
-    "$value": "100ms",
+    "$value": {
+      "value": 100,
+      "unit": "ms"
+    },
     "$type": "duration"
   },
   "Duration-200": {
-    "$value": "200ms",
+    "$value": { "value": 200 },
     "$type": "duration"
   }
 }
 ```
 
 </aside>
 
+### Validation
+
+- `$value.unit` may only be `"ms"`, `"s"`, or omitted (`"ms"`)
+- `$value.unit`, if omitted, is parsed as if it’s `"ms"`
+
 ## Cubic Bézier
 
 Represents how the value of an animated property progresses towards completion over the duration of an animation, effectively creating visual effects such as acceleration, deceleration, and bounce. The `$type` property MUST be set to the string `cubicBezier`. The value MUST be an array containing four numbers. These numbers represent two points (P1, P2) with one x coordinate and one y coordinate each [P1x, P1y, P2x, P2y]. The y coordinates of P1 and P2 can be any real number in the range [-∞, ∞], but the x coordinates are restricted to the range [0, 1].