Skip to content

Commit b67cfd3

Browse files
drwpowdrwpow
authored
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
1 parent 729cbd8 commit b67cfd3

File tree

5 files changed

+97
-41
lines changed

5 files changed

+97
-41
lines changed

‎technical-reports/format/composite-types.md

Lines changed: 50 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ A design token whose type happens to be a composite type is sometimes also calle
1919
"$type": "shadow",
2020
"$value": {
2121
"color": "#00000080",
22-
"offsetX": "0.5rem",
23-
"offsetY": "0.5rem",
24-
"blur": "1.5rem",
25-
"spread": "0rem"
22+
"offsetX": { "value": 0.5, "unit": "rem" },
23+
"offsetY": { "value": 0.5, "unit": "rem" },
24+
"blur": { "value": 1.5, "unit": "rem" },
25+
"spread": { "value": 0, "unit": "rem" }
2626
}
2727
}
2828
}
@@ -37,7 +37,7 @@ A design token whose type happens to be a composite type is sometimes also calle
3737
"space": {
3838
"small": {
3939
"$type": "dimension",
40-
"$value": "0.5rem"
40+
"$value": { "value": 0.5, "unit": "rem" }
4141
}
4242
},
4343

@@ -56,8 +56,8 @@ A design token whose type happens to be a composite type is sometimes also calle
5656
"color": "{color.shadow-050}",
5757
"offsetX": "{space.small}",
5858
"offsetY": "{space.small}",
59-
"blur": "1.5rem",
60-
"spread": "0rem"
59+
"blur": { "value": 1.5, "unit": "rem" },
60+
"spread": { "value": 0, "unit": "rem" }
6161
}
6262
}
6363
},
@@ -141,7 +141,10 @@ Object stroke style values MUST have the following properties:
141141
"alert-border-style": {
142142
"$type": "strokeStyle",
143143
"$value": {
144-
"dashArray": ["0.5rem", "0.25rem"],
144+
"dashArray": [
145+
{ "value": 0.5, "unit": "rem" },
146+
{ "value": 0.25, "unit": "rem" }
147+
],
145148
"lineCap": "round"
146149
}
147150
}
@@ -157,14 +160,17 @@ Object stroke style values MUST have the following properties:
157160
"notification-border-style": {
158161
"$type": "strokeStyle",
159162
"$value": {
160-
"dashArray": ["{dash-length-medium}", "0.25rem"],
163+
"dashArray": ["{dash-length-medium}", { "value": 0.25, "unit": "rem" }],
161164
"lineCap": "butt"
162165
}
163166
},
164167

165168
"dash-length-medium": {
166169
"$type": "dimension",
167-
"$value": "10px"
170+
"$value": {
171+
"value": 10,
172+
"unit": "px"
173+
}
168174
}
169175
}
170176
```
@@ -214,17 +220,26 @@ Represents a border style. The `$type` property MUST be set to the string `borde
214220
"$type": "border",
215221
"$value": {
216222
"color": "#36363600",
217-
"width": "3px",
223+
"width": {
224+
"value": 3,
225+
"unit": "px"
226+
},
218227
"style": "solid"
219228
}
220229
},
221230
"focusring": {
222231
"$type": "border",
223232
"$value": {
224233
"color": "{color.focusring}",
225-
"width": "1px",
234+
"width": {
235+
"value": 1,
236+
"unit": "px"
237+
},
226238
"style": {
227-
"dashArray": ["0.5rem", "0.25rem"],
239+
"dashArray": [
240+
{ "value": 0.5, "unit": "rem" },
241+
{ "value": 0.25, "unit": "rem" }
242+
],
228243
"lineCap": "round"
229244
}
230245
}
@@ -255,8 +270,8 @@ Represents a animated transition between two states. The `$type` property MUST b
255270
"emphasis": {
256271
"$type": "transition",
257272
"$value": {
258-
"duration": "200ms",
259-
"delay": "0ms",
273+
"duration": { "value": 200, "unit": "ms" },
274+
"delay": { "value": 0, "unit": "ms" },
260275
"timingFunction": [0.5, 0, 1, 1]
261276
}
262277
}
@@ -289,10 +304,10 @@ Represents a shadow style. The `$type` property MUST be set to the string `shado
289304
"$type": "shadow",
290305
"$value": {
291306
"color": "#00000080",
292-
"offsetX": "0.5rem",
293-
"offsetY": "0.5rem",
294-
"blur": "1.5rem",
295-
"spread": "0rem"
307+
"offsetX": { "value": 0.5, "unit": "rem" },
308+
"offsetY": { "value": 0.5, "unit": "rem" },
309+
"blur": { "value": 1.5, "unit": "rem" },
310+
"spread": { "value": 0, "unit": "rem" }
296311
}
297312
},
298313
"layered-shadow": {
@@ -337,6 +352,10 @@ Represents a shadow style. The `$type` property MUST be set to the string `shado
337352

338353
</aside>
339354

355+
<div class="issue" data-number="100" title="Shadow type feedback">
356+
Is the current specification for shadows fit for purpose? Does it need to support multiple shadows, as some tools and platforms do?
357+
</div>
358+
340359
## Gradient
341360

342361
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 `
461480
"$type": "typography",
462481
"$value": {
463482
"fontFamily": "Roboto",
464-
"fontSize": "42px",
483+
"fontSize": {
484+
"value": 42,
485+
"unit": "px"
486+
},
465487
"fontWeight": 700,
466-
"letterSpacing": "0.1px",
488+
"letterSpacing": {
489+
"value": 0.1,
490+
"unit": "px"
491+
},
467492
"lineHeight": 1.2
468493
}
469494
},
@@ -473,7 +498,10 @@ Represents a typographic style. The `$type` property MUST be set to the string `
473498
"fontFamily": "{font.serif}",
474499
"fontSize": "{font.size.smallest}",
475500
"fontWeight": "{font.weight.normal}",
476-
"letterSpacing": "0px",
501+
"letterSpacing": {
502+
"value": 0,
503+
"unit": "px"
504+
},
477505
"lineHeight": 1
478506
}
479507
}

‎technical-reports/format/design-token.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,15 @@ Token names are case-sensitive, so the following example with 2 tokens in the sa
3434
```json
3535
{
3636
"font-size": {
37-
"$value": "3rem",
37+
"$value": { "value": 3, "unit": "rem" },
3838
"$type": "dimension"
3939
},
4040

4141
"FONT-SIZE": {
42-
"$value": "16px",
42+
"$value": {
43+
"value": 16,
44+
"unit": "px"
45+
},
4346
"$type": "dimension"
4447
}
4548
}

‎technical-reports/format/groups.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ A file MAY contain many tokens and they MAY be nested arbitrarily in groups like
1212
},
1313
"token group": {
1414
"token dos": {
15-
"$value": "2rem",
15+
"$value": { "value": 2, "unit": "rem" },
1616
"$type": "dimension"
1717
},
1818
"nested token group": {
@@ -41,7 +41,7 @@ The names of the groups leading to a given token (including that token's name) a
4141
- Token #2
4242
- Name: "token dos"
4343
- Path: "token group" / "token dos"
44-
- Value: "2rem"
44+
- Value: { "value": 2, "unit": "rem" }
4545
- Type: "dimension"
4646
- Token #3
4747
- Name: "token tres"

‎technical-reports/format/terminology.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,10 @@ Here's [an example of a composite shadow token](https://design-tokens.github.io/
125125
"$type": "shadow",
126126
"$value": {
127127
"color": "#00000080",
128-
"offsetX": "0.5rem",
129-
"offsetY": "0.5rem",
130-
"blur": "1.5rem",
131-
"spread": "0rem"
128+
"offsetX": { "value": 0.5, "unit": "rem" },
129+
"offsetY": { "value": 0.5, "unit": "rem" },
130+
"blur": { "value": 1.5, "unit": "rem" },
131+
"spread": { "value": 0, "unit": "rem" }
132132
}
133133
}
134134
}

‎technical-reports/format/types.md

Lines changed: 36 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,12 @@ $translucent-shadow: hsla(300, 100%, 50%, 0.5);
5151

5252
## Dimension
5353

54-
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.
54+
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"`).
55+
56+
| Key | Type | Required | Description |
57+
| :------ | :------: | :------: | :----------------------------------------------------------------- |
58+
| `value` | `number` | Y | An integer or floating-point value representing the numeric value. |
59+
| `unit` | `string` | Y | Unit of distance. Supported values: `"px"`, `"rem"`. |
5560

5661
For example:
5762

@@ -60,22 +65,30 @@ For example:
6065
```json
6166
{
6267
"spacing-stack-0": {
63-
"$value": "0rem",
68+
"$value": {
69+
"value": 0,
70+
"unit": "px"
71+
},
6472
"$type": "dimension"
6573
},
6674
"spacing-stack-1": {
67-
"$value": "0.25rem",
75+
"$value": {
76+
"value": 0.5,
77+
"unit": "rem"
78+
},
6879
"$type": "dimension"
6980
}
7081
}
7182
```
7283

7384
</aside>
7485

75-
The "px" and "rem" units are to be interpreted the same way they are in CSS:
86+
### Validation
7687

77-
- **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.
78-
- **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.
88+
- `$value.unit` may only be `"px"` or `"rem"`.
89+
- **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.
90+
- **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.
91+
- `$value.unit` is still required even if `$value.value` is `0`.
7992

8093
## Font family
8194

@@ -148,27 +161,39 @@ Example:
148161

149162
## Duration
150163

151-
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.
164+
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.
165+
166+
| Key | Type | Required | Description |
167+
| :------ | :------: | :------: | :------------------------------------------------------------------- |
168+
| `value` | `number` | Y | An integer or floating-point value representing the numeric value. |
169+
| `unit` | `string` | Y | Unit of time. Supported values: `"ms"` (millisecond), `"s"`(second). |
152170

153171
For example:
154172

155173
<aside class="example">
156174

157175
```json
158176
{
159-
"Duration-100": {
160-
"$value": "100ms",
177+
"Duration-Quick": {
178+
"$value": {
179+
"value": 100,
180+
"unit": "ms"
181+
},
161182
"$type": "duration"
162183
},
163-
"Duration-200": {
164-
"$value": "200ms",
184+
"Duration-Long": {
185+
"$value": { "value": 1.5, "unit": "s" },
165186
"$type": "duration"
166187
}
167188
}
168189
```
169190

170191
</aside>
171192

193+
### Validation
194+
195+
- `$value.unit` may only be `"ms"` or `"s"`
196+
172197
## Cubic Bézier
173198

174199
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].

0 commit comments

Comments
 (0)