Skip to content

Commit

Permalink
feat: final changes for SD v4 and this pkg v1.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@jorenbroekema
jorenbroekema committed Jul 1, 2024
1 parent ed687dc commit aed5535
Show file tree
Hide file tree
Showing 46 changed files with 3,690 additions and 2,938 deletions.
4 changes: 3 additions & 1 deletion .changeset/polite-cobras-arrive.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,6 @@
'@tokens-studio/sd-transforms': major
---

BREAKING: remove CSS shorthand transforms for border, typography and shadow. Use the Style Dictionary transforms instead: https://styledictionary.com/reference/hooks/transforms/predefined/#bordercssshorthand .
BREAKING: remove CSS shorthand transforms for border, typography and shadow. Use the Style Dictionary transforms instead: https://styledictionary.com/reference/hooks/transforms/predefined/#bordercssshorthand.

Note that if you're not disabling the `withSDBuiltins` option, the `tokens-studio` transformGroup will include the ones in the `css` built-in transformGroup, so you might not notice the fact that they are moved.
15 changes: 15 additions & 0 deletions .changeset/yellow-nails-live.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
'@tokens-studio/sd-transforms': major
---

- BREAKING: Compatible with Style Dictionary >= v4.0.0. Not compatible with anything below that SD version.

- BREAKING: `registerTransforms` function has been renamed to `register`.

- BREAKING: `transforms` array has been refactored to `getTransforms()`, which is a function you should call. Optionally pass in the new platform option as parameter `{ platform: 'css' /* or 'compose' */}`

- BREAKING: By default, registered `tokens-studio` transformGroup will include the platform's Style Dictionary built-in transforms. E.g. if you're registering for platform `css` it will include the `css` transformGroup transforms from Style Dictionary, appended to the Tokens Studio specific transforms. This behavior can be disabled by passing `{ withSDBuiltins: false }`.

- Allow passing platform to the `register()` call: `register(SD, { platform: 'compose' })`. Default value is `'css'`. This means your `tokens-studio` group will be registered for that specific platform.

- Allow passing `name` to the `register()` call to configure the transformGroup name: `register(SD, { name: 'tokens-studio-css' })`. Default value is `tokens-studio`.
2 changes: 1 addition & 1 deletion .github/workflows/verify.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ jobs:
run: npm run lint

- name: Install chromium
run: npx playwright install-deps chromium
run: npx playwright install --with-deps chromium

- name: Unit tests
run: npm run test:unit
Expand Down
8 changes: 7 additions & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Contributing Guidelines

Things to know before contributing:
Any contribution is greatly appreciated. If you feel like you lack knowledge/experience, even just creating a good issue with a minimal reproduction is already huge.
If you can create a PR with a failing test showing the bug you found, even better, don't worry about putting the test in the perfect location but as a rule of thumb, if your bug is only reproducible in combination with Style Dictionary, put it in the `test/integration`, if it's more isolated to sd-transforms you can put it in `test/spec` folder.

Is TypeScript not your strength and having issues? No problem, just do what you can and I'll help you fix whatever's broken in the PR.

## Tests

Expand All @@ -15,6 +18,9 @@ To run the tests and view the coverage report, to see which things are untested.

If some line of code really cannot be covered by a test or just doesn't make sense, [see here how to ignore them](https://modern-web.dev/docs/test-runner/writing-tests/code-coverage/#ignoring-uncovered-lines).

> 100% may seem a bit crazy, but just know that it's a lot easier to retain 100% than to get it for the first time ;)
> The biggest benefit to 100% is that it makes it very easy to identify redundant code; if it's redundant, it won't be covered.
## Linting

This checks code quality with ESLint, formatting with Prettier and types with TypeScript.
Expand Down
173 changes: 45 additions & 128 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,7 @@ CSS:

- Transform letterspacing from `%` to `em` -> `ts/size/css/letterspacing`
- Transform colors to `rgba()` format -> `ts/color/css/hexrgba`
- Transform font family into valid CSS, adding single quotes if necessary -> `ts/typography/css/fontFamily`
- Transform typography objects to CSS shorthand -> `ts/typography/css/shorthand`
- Transform Tokens Studio shadow objects to CSS shadow shorthand -> `ts/shadow/css/shorthand`
- Transform border objects to CSS border shorthand -> `ts/border/css/shorthand`
- Transform shadow "type" property "innerShadow" to "inset" -> `ts/shadow/innerShadow`

Android:

Expand Down Expand Up @@ -67,24 +64,22 @@ There are some caveats however, with regards to which versions of Style Dictiona
| **4.0.0**-prerelease.**2** - **4.0.0**-prerelease.**18** | **0.13.0** - **0.14.4** |
| **4.0.0**-prerelease.**18** - **4.0.0**-prerelease.**26** | **0.13.0** - **0.15.2** |
| >= **4.0.0**-prerelease.**27** | >= **0.16.0** |
| >= **4.0.0** | >= **1.0.0** |

This may seem a little tedious, but the reason is because `sd-transforms` is still in alpha, and Style Dictionary v4 is still being worked on, iteratively doing lots of breaking changes.

This will be much simpler when Style Dictionary v4 is released, at that point `sd-transforms` v1 will be released and be out of alpha.
Both APIs will be stable then.
Now that Style Dictionary v4 is released, and `sd-transforms` v1 is released and out of alpha state,both APIs are stable and the recommendation is to use these.

## Usage

> [!NOTE]
> This library is only available in ESM
```js
import { registerTransforms } from '@tokens-studio/sd-transforms';
import { register } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';

// will register them on StyleDictionary object
// that is installed as a dependency of this package.
registerTransforms(StyleDictionary);
register(StyleDictionary);

const sd = new StyleDictionary({
// make sure to have source match your token files!
Expand All @@ -110,16 +105,12 @@ await sd.cleanAllPlatforms();
await sd.buildAllPlatforms();
```

> You can also import as ES Modules if needed.
To run it use the following command

```sh
node build-output.js
```

> From Style-Dictionary `4.0.0-prerelease.18`, [`transformGroup` and `transforms` can now be combined in a platform inside your config](https://github.com/amzn/style-dictionary/blob/v4/CHANGELOG.md#400-prerelease18).
### Using the preprocessor

You must add the `'tokens-studio'` preprocessor explicitly in the configuration:
Expand All @@ -132,7 +123,7 @@ You must add the `'tokens-studio'` preprocessor explicitly in the configuration:
}
```

This allows fontStyles to be extracted when they are embedded in fontWeights, aligns Tokens Studio token types with DTCG token types, and allows excluding parent keys for single-file Tokens Studio exports.
This allows `fontStyles` to be extracted when they are embedded in `fontWeights`, aligns Tokens Studio token types with DTCG token types, and allows excluding parent keys for single-file Tokens Studio exports.

### Using "Expand"

Expand Down Expand Up @@ -223,25 +214,32 @@ You can create a custom `transformGroup` that includes the individual transforms
If you wish to use the `transformGroup`, but adjust or remove a few transforms, your best option is to create a custom transform group:

```js
import { transforms } from '@tokens-studio/sd-transforms';
import { getTransforms } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';

// Register custom tokens-studio transform group
// without 'px' being added to numbers without a unit
// and also adding 'name/constant' for the token names
StyleDictionary.registerTransformGroup({
name: 'custom/tokens-studio',
transforms: [...transforms, 'name/constant'].filter(transform => transform !== 'ts/size/px'),
// default value for platform is css, specifies which Tokens Studio transforms for which platform to grab
transforms: [...getTransforms({ platform: 'css' }), 'name/constant'].filter(
transform => transform !== 'ts/size/px',
),
});
```

> Note that you can also manually grab some of the SD built-in transforms by using `StyleDictionary.hooks.transformGroups` or `StyleDictionary.hooks.transforms`
### Options

You can pass options to the `registerTransforms` function.
You can pass options to the `register` function.

```js
registerTransforms(StyleDictionary, {
register(StyleDictionary, {
excludeParentKeys: true,
platform: 'css',
name: 'tokens-studio',
'ts/color/modifiers': {
format: 'hex',
},
Expand All @@ -250,12 +248,15 @@ registerTransforms(StyleDictionary, {

Options:

| name | type | required | default | description |
| ----------------------------- | -------------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| excludeParentKeys | boolean | ❌ | `false` | Whether or not to exclude parent keys from your token files |
| alwaysAddFontStyle | boolean | ❌ | `false` | Whether or not to always add a 'normal' fontStyle property to typography tokens which do not have explicit fontStyle |
| ['ts/color/modifiers'] | ColorModifierOptions | ❌ | See props below | Color modifier options |
| ['ts/color/modifiers'].format | ColorModifierFormat | ❌ | `undefined` | Color modifier output format override ('hex' \| 'hsl' \| 'lch' \| 'p3' \| 'srgb'), uses local format or modifier space as default |
| name | type | required | default | description |
| ----------------------------- | -------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| excludeParentKeys | boolean | ❌ | `false` | Whether or not to exclude parent keys from your token files |
| platform | `'css'\|'compose'` | ❌ | `css` | Which platform to use the transforms for. |
| name | string | ❌ | `tokens-studio` | Under which name to register the `transformGroup` |
| withSDBuiltins | boolean | ❌ | `true` | Whether to append the Style Dictionary built-in `transformGroup` transforms for the configured platform into the `tokens-studio` transformGroup. |
| alwaysAddFontStyle | boolean | ❌ | `false` | Whether or not to always add a 'normal' fontStyle property to typography tokens which do not have explicit fontStyle |
| ['ts/color/modifiers'] | ColorModifierOptions | ❌ | See props below | Color modifier options |
| ['ts/color/modifiers'].format | ColorModifierFormat | ❌ | `undefined` | Color modifier output format override ('hex' \| 'hsl' \| 'lch' \| 'p3' \| 'srgb'), uses local format or modifier space as default |

> [!NOTE]
> You can also import and use the `parseTokens` function to run the parsing steps on your tokens object manually.
Expand All @@ -272,11 +273,11 @@ Here's a full example of how you can use this in conjunction with Style Dictiona
Run this script:

```cjs
import { registerTransforms } from '@tokens-studio/sd-transforms';
import { register } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';
import { promises } from 'fs';

registerTransforms(StyleDictionary, {
register(StyleDictionary, {
/* options here if needed */
});

Expand Down Expand Up @@ -406,11 +407,11 @@ Note that it is a best practice to generate standalone output files for each the
Full example with multi-dimensional themes:

```js
import { registerTransforms, permutateThemes } from '@tokens-studio/sd-transforms';
import { register, permutateThemes } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';
import { promises } from 'fs';

registerTransforms(StyleDictionary, {
register(StyleDictionary, {
/* options here if needed */
});

Expand Down Expand Up @@ -746,84 +747,24 @@ This transforms color token values with Figma's "hex code RGBA" into actual `rgb
}
```

### ts/typography/css/fontFamily

This transforms font-family token values into valid CSS, adding single quotes if necessary.

**matches**: `token.type` is `'fontFamilies'`

#### before

```json
{
"token": {
"type": "fontFamilies",
"value": "Arial Black, Times New Roman, Foo, sans-serif"
}
}
```

#### after

```json
{
"token": {
"type": "fontFamilies",
"value": "'Arial Black', 'Times New Roman', Foo, sans-serif"
}
}
```

### ts/typography/css/shorthand

This transforms typography tokens into a valid CSS shorthand

**matches**: `token.type` is `'typography'`

#### before

```json
{
"token": {
"type": "typography",
"value": {
"fontWeight": "500",
"fontSize": "20px",
"lineHeight": "1.5",
"fontFamily": "Arial"
}
}
}
```

#### after

```json
{
"token": {
"value": "500 20px/1.5 Arial"
}
}
```

### ts/shadow/css/shorthand
### ts/shadow/innerShadow

This transforms shadow tokens into a valid CSS shadow shorthand
This transforms shadow tokens to ensure that the `type` property gets converted from `innerShadow` to `inset` (CSS compatible).

**matches**: `token.type` is `'boxShadow'`
**matches**: `token.type` is `'shadow'`

#### before

```json
{
"token": {
"type": "boxShadow",
"type": "color",
"value": {
"x": "5px",
"y": "3px",
"blur": "6px",
"spread": "2px",
"color": "#000000"
"offsetX": "0",
"offsetY": "4px",
"blur": "10px",
"color": "#000",
"type": "innerShadow"
}
}
}
Expand All @@ -834,42 +775,18 @@ This transforms shadow tokens into a valid CSS shadow shorthand
```json
{
"token": {
"value": "5px 3px 6px 2px #000000"
}
}
```

### ts/border/css/shorthand

This transforms border tokens into a valid CSS border shorthand

**matches**: `token.type` is `'border'`

#### before

```json
{
"token": {
"type": "border",
"type": "color",
"value": {
"width": "5",
"style": "dashed",
"color": "rgba(#000000, 1)"
"offsetX": "0",
"offsetY": "4px",
"blur": "10px",
"color": "#000",
"type": "inset"
}
}
}
```

#### after

```json
{
"token": {
"value": "5px dashed rgba(0, 0, 0, 1)"
}
}
```

## Not sure how to fix your issue?

### Create a reproduction by:-
Expand Down
Loading

0 comments on commit aed5535

Please sign in to comment.