diff --git a/technical-reports/format/composite-types.md b/technical-reports/format/composite-types.md index 4bc3acb..82c69e1 100644 --- 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
- 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)?
### 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,7 +220,10 @@ 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" } }, @@ -222,9 +231,12 @@ Represents a border style. The `$type` property MUST be set to the string `borde "$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
- 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?
## 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 index 6055683..00cebdb 100644 --- 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 index 18bf980..1098eb3 100644 --- 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 index 131fa7a..f237d94 100644 --- 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 index d6573d2..aa60e46 100644 --- 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,11 +65,17 @@ 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" } } @@ -72,10 +83,11 @@ For example: -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,11 +174,14 @@ For example: ```json { "Duration-100": { - "$value": "100ms", + "$value": { + "value": 100, + "unit": "ms" + }, "$type": "duration" }, "Duration-200": { - "$value": "200ms", + "$value": { "value": 200 }, "$type": "duration" } } @@ -169,6 +189,11 @@ For example: +### 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].