Skip to content

design-tokens : allow unit assignments #589

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

Merged
romainmenke merged 2 commits into from
Aug 30, 2022
Merged

design-tokens : allow unit assignments #589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3db1eeb
design-tokens : allow unit assignments
romainmenke Aug 27, 2022
e79eb56
Merge branch 'main' into design-tokens-allow-unit-assignments--philos…
romainmenke Aug 27, 2022
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
4 changes: 2 additions & 2 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 21 additions & 13 deletions plugins/postcss-design-tokens/.tape.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,40 +8,48 @@ postcssTape(plugin)({
plugins: [
postcssImport(),
plugin()
]
],
warnings: 1
},
'basic:rootFontSize-20': {
message: "supports basic usage with { unitsAndValues { rootFontSize: 20 } }",
'units': {
message: "supports units usage",
plugins: [
plugin()
],
warnings: 2
},
'units:rootFontSize-20': {
message: "supports units usage with { unitsAndValues { rootFontSize: 20 } }",
plugins: [
postcssImport(),
plugin({
unitsAndValues: {
rootFontSize: 20
}
})
]
],
warnings: 2
},
'basic:rootFontSize-NaN': {
message: "supports basic usage with { unitsAndValues { rootFontSize: NaN } }",
'units:rootFontSize-NaN': {
message: "supports units usage with { unitsAndValues { rootFontSize: NaN } }",
plugins: [
postcssImport(),
plugin({
unitsAndValues: {
rootFontSize: NaN
}
})
]
],
warnings: 2
},
'basic:rootFontSize-invalid': {
message: "supports basic usage with { unitsAndValues { rootFontSize: invalid } }",
'units:rootFontSize-invalid': {
message: "supports units usage with { unitsAndValues { rootFontSize: invalid } }",
plugins: [
postcssImport(),
plugin({
unitsAndValues: {
rootFontSize: 'invalid'
}
})
]
],
warnings: 2
},
'errors': {
message: "handles issues correctly",
Expand Down
19 changes: 19 additions & 0 deletions plugins/postcss-design-tokens/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changes to PostCSS Design Tokens

### Unreleased

- Added support for arbitrary unit assignment to unit-less design tokens.

```json
{
"font-size": 0.2
}
```

```css
.example {
font-size: design-token('font-size' to vh);

/* becomes */
font-size: 0.2vh;
}
```

### 1.1.1 (August 23, 2022)

- Prevent stack overflow failures when importing files with format `style-dictionary3` that are not of that format.
Expand Down
105 changes: 55 additions & 50 deletions plugins/postcss-design-tokens/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,34 +74,6 @@ Use `style-dictionary3` in `@design-tokens` rules to pick this format.

## Options

### importAtRuleName

The `importAtRuleName` option allows you to set a custom alias for `@design-tokens`.

```js
postcssDesignTokens({ importAtRuleName: 'tokens' })
```

```pcss
@tokens url('./tokens.json') format('style-dictionary3');

.foo {
color: design-token('color.background.primary');
padding-top: design-token('size.spacing.small');
padding-left: design-token('size.spacing.small' to px);
padding-bottom: design-token('size.spacing.small' to rem);
}

/* becomes */

.foo {
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 1rem;
}
```

### is

The `is` option determines which design tokens are used.
Expand Down Expand Up @@ -188,22 +160,31 @@ postcssDesignTokens({ is: ['dark'] })
}
```

### valueFunctionName
### unitsAndValues

The `valueFunctionName` option allows you to set a custom alias for `design-token`.
The `unitsAndValues` option allows you to control some aspects of how design values are converted to CSS.
`rem` <-> `px` for example can only be calculated when we know the root font size.

#### rootFontSize

defaults to `16`

```js
postcssDesignTokens({ valueFunctionName: 'token' })
postcssDesignTokens({
unitsAndValues: {
rootFontSize: 20,
},
})
```

```pcss
@design-tokens url('./tokens.json') format('style-dictionary3');

.foo {
color: token('color.background.primary');
padding-top: token('size.spacing.small');
padding-left: token('size.spacing.small' to px);
padding-bottom: token('size.spacing.small' to rem);
color: design-token('color.background.primary');
padding-top: design-token('size.spacing.small');
padding-left: design-token('size.spacing.small' to px);
padding-bottom: design-token('size.spacing.small' to rem);
}

/* becomes */
Expand All @@ -212,29 +193,22 @@ postcssDesignTokens({ valueFunctionName: 'token' })
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 1rem;
padding-bottom: 0.8rem;
}
```

### unitsAndValues

The `unitsAndValues` option allows you to control some aspects of how design values are converted to CSS.
`rem` <-> `px` for example can only be calculated when we know the root font size.
### Customize function and at rule names

#### rootFontSize
#### importAtRuleName

defaults to `16`
The `importAtRuleName` option allows you to set a custom alias for `@design-tokens`.

```js
postcssDesignTokens({
unitsAndValues: {
rootFontSize: 20,
},
})
postcssDesignTokens({ importAtRuleName: 'tokens' })
```

```pcss
@design-tokens url('./tokens.json') format('style-dictionary3');
@tokens url('./tokens.json') format('style-dictionary3');

.foo {
color: design-token('color.background.primary');
Expand All @@ -249,7 +223,35 @@ postcssDesignTokens({
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 0.8rem;
padding-bottom: 1rem;
}
```

#### valueFunctionName

The `valueFunctionName` option allows you to set a custom alias for `design-token`.

```js
postcssDesignTokens({ valueFunctionName: 'token' })
```

```pcss
@design-tokens url('./tokens.json') format('style-dictionary3');

.foo {
color: token('color.background.primary');
padding-top: token('size.spacing.small');
padding-left: token('size.spacing.small' to px);
padding-bottom: token('size.spacing.small' to rem);
}

/* becomes */

.foo {
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 1rem;
}
```

Expand Down Expand Up @@ -328,9 +330,12 @@ The `design-token()` function takes a token path and returns the token value.
design-token() = design-token( <token-path> [ to <unit> ]? )

<token-path> = <string>
<unit> = [ px | rem ]
<unit> = [ px | rem | ... ]
```

The plugin can convert `px` to `rem` and `rem` to `px` via the [`unitsandvalues`](#unitsandvalues) plugin options.
When a design token is unit-less any `unit` can be assigned with `to`.

## Further reading

- [Why we think PostCSS Design Tokens is needed]
Expand Down
71 changes: 38 additions & 33 deletions plugins/postcss-design-tokens/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,22 +44,6 @@ Use `style-dictionary3` in `@design-tokens` rules to pick this format.

## Options

### importAtRuleName

The `importAtRuleName` option allows you to set a custom alias for `@design-tokens`.

```js
<exportName>({ importAtRuleName: 'tokens' })
```

```pcss
<example-custom-import-at-rule-name.css>

/* becomes */

<example-custom-import-at-rule-name.expect.css>
```

### is

The `is` option determines which design tokens are used.
Expand Down Expand Up @@ -115,22 +99,6 @@ By default only `@design-tokens` without any `when('foo')` conditions are used.
<example-conditional.dark.expect.css>
```

### valueFunctionName

The `valueFunctionName` option allows you to set a custom alias for `design-token`.

```js
<exportName>({ valueFunctionName: 'token' })
```

```pcss
<example-custom-value-function-name.css>

/* becomes */

<example-custom-value-function-name.expect.css>
```

### unitsAndValues

The `unitsAndValues` option allows you to control some aspects of how design values are converted to CSS.
Expand All @@ -156,6 +124,40 @@ defaults to `16`
<example.rootFontSize-20.expect.css>
```

### Customize function and at rule names

#### importAtRuleName

The `importAtRuleName` option allows you to set a custom alias for `@design-tokens`.

```js
<exportName>({ importAtRuleName: 'tokens' })
```

```pcss
<example-custom-import-at-rule-name.css>

/* becomes */

<example-custom-import-at-rule-name.expect.css>
```

#### valueFunctionName

The `valueFunctionName` option allows you to set a custom alias for `design-token`.

```js
<exportName>({ valueFunctionName: 'token' })
```

```pcss
<example-custom-value-function-name.css>

/* becomes */

<example-custom-value-function-name.expect.css>
```

## Syntax

[<humanReadableName>] is non-standard and is not part of any official CSS Specification.
Expand Down Expand Up @@ -231,9 +233,12 @@ The `design-token()` function takes a token path and returns the token value.
design-token() = design-token( <token-path> [ to <unit> ]? )

<token-path> = <string>
<unit> = [ px | rem ]
<unit> = [ px | rem | ... ]
```

The plugin can convert `px` to `rem` and `rem` to `px` via the [`unitsandvalues`](#unitsandvalues) plugin options.
When a design token is unit-less any `unit` can be assigned with `to`.

## Further reading

- [Why we think PostCSS Design Tokens is needed]
Expand Down
2 changes: 1 addition & 1 deletion plugins/postcss-design-tokens/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
},
"devDependencies": {
"postcss-import": "^14.1.0",
"style-dictionary-design-tokens-example": "^1.0.0"
"style-dictionary-design-tokens-example": "^1.1.0"
Copy link
Member Author

@romainmenke romainmenke Aug 27, 2022

Choose a reason for hiding this comment

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

The "exports" field was incorrect there.
Noticed it while trying to node module resolutions.

No work was done to resolve modules in this PR, but updating the package anyway.

},
"scripts": {
"build": "rollup -c ../../rollup/default.js",
Expand Down
4 changes: 2 additions & 2 deletions plugins/postcss-design-tokens/src/data-formats/style-dictionary/v3/group.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ function extractTokens(node: StyleDictionaryV3TokenGroup, path: Array<string>, f
for (const key in node) {
if (Object.hasOwnProperty.call(node, key)) {
if (
node[key] === null ||
typeof node[key] !== 'object' ||
Array.isArray(node[key]) &&
node[key] === null
Array.isArray(node[key])
) {
throw new Error(`Parsing error at "${[...path, key].join('.')}"`);
}
Expand Down
Loading