Proposal: changes to type: $dimension and type: $duration tokens (#244)

* Proposal: changes to dimension and duration tokens * Revert freeform dimension units * PR Feedback * PR feedback
design-tokens · Oct 24, 2024 · b67cfd3 · b67cfd3
1 parent 729cbd8
commit b67cfd3
Show file tree

Hide file tree

Showing 5 changed files with 97 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" }
       }
     }
   },
@@ -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,26 @@ 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" },
+            { "value": 0.25, "unit": "rem" }
+          ],
           "lineCap": "round"
         }
       }
@@ -255,8 +270,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, "unit": "ms" },
         "timingFunction": [0.5, 0, 1, 1]
       }
     }
@@ -289,10 +304,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" }
     }
   },
   "layered-shadow": {
@@ -337,6 +352,10 @@ 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?
+</div>
+
 ## Gradient
 
 Represents a color gradient. The `$type` property MUST be set to the string `gradient`. The value MUST be an array of objects representing gradient stops that have the following structure:
@@ -461,9 +480,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
       }
     },
@@ -473,7 +498,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 containing a numeric `value` (integer or floating-point) and `unit` of measurement (`"px"` or `"rem"`).
+
+| Key     |   Type   | Required | Description                                                        |
+| :------ | :------: | :------: | :----------------------------------------------------------------- |
+| `value` | `number` |    Y     | An integer or floating-point value representing the numeric value. |
+| `unit`  | `string` |    Y     | Unit of distance. Supported values: `"px"`, `"rem"`.               |
 
 For example:
 
@@ -60,22 +65,30 @@ 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 only be `"px"` or `"rem"`.
+  - **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` is still required even if `$value.value` is `0`.
 
 ## Font family
 
@@ -148,27 +161,39 @@ 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 containing a numeric `value` (either integer or floating-point) and a `unit` of 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` |    Y     | Unit of time. Supported values: `"ms"` (millisecond), `"s"`(second). |
 
 For example:
 
 <aside class="example">
 
 ```json
 {
-  "Duration-100": {
-    "$value": "100ms",
+  "Duration-Quick": {
+    "$value": {
+      "value": 100,
+      "unit": "ms"
+    },
     "$type": "duration"
   },
-  "Duration-200": {
-    "$value": "200ms",
+  "Duration-Long": {
+    "$value": { "value": 1.5, "unit": "s" },
     "$type": "duration"
   }
 }
 ```
 
 </aside>
 
+### Validation
+
+- `$value.unit` may only be `"ms"` or `"s"`
+
 ## 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].