Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Oct 24, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cfcda14
Proposal: changes to dimension and duration tokens
drwpow Aug 16, 2024
67ab90a
Revert freeform dimension units
drwpow Aug 17, 2024
f95cc4d
PR Feedback
drwpow Aug 20, 2024
b7f8502
PR feedback
drwpow Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 50 additions & 22 deletions technical-reports/format/composite-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
}
}
}
Expand All @@ -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" }
}
},

Expand All @@ -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" }
}
}
},
Expand Down Expand Up @@ -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"
}
}
Expand All @@ -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"
}
}
}
```
Expand Down Expand Up @@ -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"
}
}
Expand Down Expand Up @@ -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]
}
}
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
}
},
Expand All @@ -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
}
}
Expand Down
7 changes: 5 additions & 2 deletions technical-reports/format/design-token.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
Expand Down
4 changes: 2 additions & 2 deletions technical-reports/format/groups.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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"
Expand Down
8 changes: 4 additions & 4 deletions technical-reports/format/terminology.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
}
}
}
Expand Down
47 changes: 36 additions & 11 deletions technical-reports/format/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Copy link
Contributor Author

@drwpow drwpow Aug 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: this new subheading is inconsistent with the other sections. This was done thinking back to #200 that observes the spec could be more explicit about validation.

This would be a change from the current structure of validation rules existing in prose, usually in the initial description. However, in many places, those aren’t exhaustive/complete (for good reason—it’d be hard to read).

All that said, we don’t have to introduce these subheadings in this PR; we could fold everything into prose form to match the existing format.


- **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

Expand Down Expand Up @@ -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). |
drwpow marked this conversation as resolved.
Show resolved Hide resolved

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].
Expand Down
Loading