diff --git a/technical-reports/format/composite-types.md b/technical-reports/format/composite-types.md index 5fe5fa9..8b0a1d3 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" } } } }, @@ -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,15 @@ 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" }, + { "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 +
+ Is the current specification for shadows fit for purpose? Does it need to support multiple shadows, as some tools and platforms do? +
+ ## 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 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..a42a078 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 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,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,12 @@ 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 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,7 +161,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 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: @@ -156,12 +174,15 @@ For 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" } } @@ -169,6 +190,10 @@ For example: +### 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].