feat!: refactor design tokens and token transformer #8149

alisonailea · 2023-11-08T20:57:50Z

Related Issue: #7325 #8141

Summary

This is a complete refactor of the token transformer. This introduces breaking changes to tokens.

BREAKING CHANGE:

removes tokens with “light” and “dark” in their names in favor of composite color mode tokens which now have separate outputs.
new platform output files. Replaces “headless” with “global” and removes “calcite” from filenames.
tokens no longer include "app" or "ui" in their names
breakpoint tokens are no longer included in "global" CSS or SCSS output
breakpoint tokens have been renamed to "container-size" (i.e --calcite-app-breakpoint-width-lg-min is now --calcite-container-size-width-lg-min)
global tokens have been refactored to use ordinal t-shirt sizing. These tokens reference the nominal token values in core. If you still need the nominal values you may import "core" tokens but this is not recommended.
tokens using the word "sizing" in their names now use "size"
remove duplicates in token names border-border-width is now border-width

jcfranco · 2023-11-16T02:25:18Z

@alisonailea Awesome! Some pre-review notes:

Can you update the PR description's breaking change note to follow conventional commits (see https://github.com/Esri/calcite-design-system/blob/main/CONTRIBUTING.md#breaking-changes, build(deps)!: bump Stencil to v4 #8108, refactor(card)!: remove deprecated deselected message #8099)?
Can you update the PR title so that the conventional commit message conveys what the feature entails? Possibly using design-tokens as the scope.
Can you change the PR's base to rc (instead of main)? We're keeping main (next deployments) free of breaking changes for the time being.

jcfranco · 2023-11-16T02:35:11Z

It also looks like this is addressing #8141. If so, can this be rolled back and tackled separately to have more focused PRs? If not, can you comment on this and cover it in the breaking changes notes?

jcfranco · 2023-11-16T02:36:56Z

BREAKING CHANGES

This must be singular to adhere to the spec.

set old core tokens for deprecation update token types align token reference syntax with design token standards

BREAKING CHANGE: removes “light” and “dark” tokens in favor of composite color mode tokens

BREAKING CHANGE: new platform output files. Replaces “headless” with “global” and removes “calcite” from filenames. Significantly reduces the filesize of platform output files. Now supports composite color mode tokens and typography tokens Adds multi-file output, including ./index files

removes unused $metadata

jcfranco

This is looking great, @alisonailea!

Regarding the spell checker, I think we can use a very terse explainer for ignored lines we can reuse for now. If we can separate files extended from sd-transforms, we can ignore those entirely.

jcfranco · 2023-11-16T20:32:16Z

packages/calcite-design-tokens/src/core.json

      },
      "23": {
        "value": "144px",
-        "type": "sizing"
+        "type": "sizing",
+        "description": "For backwards compatibility only. This token will be removed from the published tokens in the next major version because the type \"size\" is prefered by designer",


Great job on adding a deprecation notice for these. ✨⭐✨

jcfranco · 2023-11-16T20:34:16Z

packages/calcite-design-tokens/src/core.json

      },
      "24": {
        "value": "160px",
-        "type": "sizing"
+        "type": "sizing",
+        "description": "For backwards compatibility only. This token will be removed from the published tokens in the next major version because the type \"size\" is prefered by designer",


Typo: prefered ➡️ preferred.

Question: should designer be pluralized?

thanks for the catch. Should be "preferred by design"

jcfranco · 2023-11-16T20:37:03Z

packages/calcite-design-tokens/src/semantic/border.json

+        "border-radius": {
+          "value": "{core.border.border-radius.none}",
+          "type": "borderRadius",
+          "description": "For backwards compatibility only. This token will be removed from the published tokens in the next major version in favor of removing the \"ui\" level that doesn't match the naming schema.",


I think this needs to be updated according to the latest breaking change notes in the description:

exported token no longer include "app" or "ui"

Applies to other items with the same description.

jcfranco · 2023-11-16T20:39:17Z

packages/calcite-design-tokens/src/semantic/font.json

+        "light": {
+          "value": "{core.font.font-weight.light}",
+          "type": "fontWeights",
+          "description": "only for Avenir Next World (secondary font family)"


Nitpick: For consistency, this description should also start capitalized.

jcfranco · 2023-11-16T20:40:38Z

packages/calcite-design-tokens/src/semantic/font.json

+        "7": {
+          "value": "{core.font.font-size.7}",
+          "type": "fontSizes",
+          "description": "For backwards compatibility only. This token will be removed from the published tokens in the next major version in favor of t-shirt sizing tokens.",


t-shirt sizing

TIL 🌠🤩

jcfranco · 2023-11-16T21:26:32Z

...cite-design-tokens/support/token-transformer/styleDictionary/formatter/utils/formatTokens.ts

+
+export function formatTokens(dictionary: Dictionary, args: MappedFormatterArguments): FormattedTokens {
+  const allTokens = [...dictionary.allTokens].sort(sortByReference(dictionary));
+  // const formatting = FormattingRules[args.options.platform] || FormattingRules.default;


Please remove all commented-out code.

jcfranco · 2023-11-16T21:30:59Z

...ite-design-tokens/support/token-transformer/styleDictionary/parser/utils/resolveRelevance.ts

@@ -0,0 +1,52 @@
+/**
+ * This is a copy/extension of sd-transforms/src/parsers/resolveReference.ts but now with better types!


Can you make sure all copies have a note on them? I think we need a way to separate them.

How will we keep these in sync with the upstream source?

We don't have to. I pulled in the fuctions they use that I think are helpful but since design is moving away from Token Studio we should not need to keep track of the upstream source.

jcfranco · 2023-11-16T21:31:51Z

packages/calcite-design-tokens/support/token-transformer/styleDictionary/formatter/utils.ts

+import { Options } from "../../../types/styleDictionary/options.js";
+import { PossibleRegistryArgs } from "../utils.js";
+import { PlatformOptions } from "../../../types/styleDictionary/platform.js";
+// import { TransformedToken } from "../../../types/styleDictionary/transformedToken.js";


Please remove commented-out code.

jcfranco · 2023-11-16T21:36:24Z

packages/calcite-design-tokens/support/types/styleDictionary/dictionary.ts

+  tokens: TransformedTokens;
+  allProperties: TransformedToken[];
+  properties: TransformedTokens;
+  usesReference: (value: any) => boolean;


Can the type be narrowed or is it unknown?

It could potentially be anything at this point.

jcfranco · 2023-11-16T21:42:34Z

packages/calcite-design-tokens/src/component/modal.json

-        "value": "$semantic.ui.color.foreground.1.dark",
-        "type": "color"
-      }
+      "value": "{semantic.ui.color.foreground.1}",


I noticed this was the only component-level token that has a description. Is it intentional? If so, will others be updated as well?

On a similar note, this was the only one I found where background entry that didn't have a default nor light/dark keys right under it.

component tokens haven't been fully updated yet

jcfranco · 2023-11-16T21:51:47Z

@alisonailea Thanks for updating the PR title/description, btw!

jcfranco · 2023-11-17T06:52:58Z

@alisonailea, we had to recreate rc and it unfortunately closed this PR. I think you can resubmit the PR by doing the following:

Delete your GitHub branch or run git push origin :astump/7325-reduce-tokens-output
Run git branch --unset-upstream on astump/7325-reduce-tokens-output
Run git fetch origin
Run git push origin astump/7325-reduce-tokens-output
Use that new branch to create a new PR.

Sorry for the trouble! 🙇

Recreated PR: #8215

alisonailea added the future breaking change Issues and pull requests with deprecation(s), requires a breaking change in a future milestone. label Nov 8, 2023

alisonailea self-assigned this Nov 8, 2023

alisonailea requested review from benelan, jcfranco, driskull, geospatialem and a team as code owners November 8, 2023 20:57

alisonailea marked this pull request as draft November 8, 2023 20:57

alisonailea force-pushed the astump/7325-reduce-tokens-output branch from c2f17f2 to 34d4a6e Compare November 16, 2023 00:57

alisonailea added 2 - in development Issues that are actively being worked on. and removed 2 - in development Issues that are actively being worked on. labels Nov 16, 2023

alisonailea added this to the 2023 November Priorities milestone Nov 16, 2023

alisonailea marked this pull request as ready for review November 16, 2023 01:01

alisonailea changed the title ~~WIP: reduce tokens output~~ feat!: design tokens refactor Nov 16, 2023

alisonailea changed the title ~~feat!: design tokens refactor~~ feat (design tokens)!: refactor Nov 16, 2023

alisonailea changed the base branch from main to rc November 16, 2023 18:07

alisonailea added 5 commits November 16, 2023 10:27

feat: token reference syntax should align with design token standards

b2b24e8

feat: align core token names with naming standards

cfb2114

set old core tokens for deprecation update token types align token reference syntax with design token standards

feat!: break semantic tokens into separate files

2db9f56

BREAKING CHANGE: removes “light” and “dark” tokens in favor of composite color mode tokens

feat: replace $themes with $config

5b10c62

removes unused $metadata

alisonailea force-pushed the astump/7325-reduce-tokens-output branch from 34d4a6e to 5b10c62 Compare November 16, 2023 18:29

alisonailea changed the title ~~feat (design tokens)!: refactor~~ feat (calcite-design-tokens)!: refactor Nov 16, 2023

alisonailea changed the title ~~feat (calcite-design-tokens)!: refactor~~ feat (calcite-design-tokens)!: refactor design tokens and token transformer Nov 16, 2023

jcfranco changed the title ~~feat (calcite-design-tokens)!: refactor design tokens and token transformer~~ feat!: refactor design tokens and token transformer Nov 16, 2023

jcfranco added breaking change Issues and pull requests with code changes that are not backwards compatible. and removed future breaking change Issues and pull requests with deprecation(s), requires a breaking change in a future milestone. labels Nov 16, 2023

jcfranco requested changes Nov 16, 2023

View reviewed changes

benelan deleted the branch rc November 17, 2023 05:32

benelan closed this Nov 17, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: refactor design tokens and token transformer #8149

feat!: refactor design tokens and token transformer #8149

alisonailea commented Nov 8, 2023 •

edited

Loading

jcfranco commented Nov 16, 2023

jcfranco commented Nov 16, 2023 •

edited

Loading

jcfranco commented Nov 16, 2023

jcfranco left a comment

jcfranco Nov 16, 2023

jcfranco Nov 16, 2023

alisonailea Nov 16, 2023

jcfranco Nov 16, 2023

jcfranco Nov 16, 2023

jcfranco Nov 16, 2023

jcfranco Nov 16, 2023

jcfranco Nov 16, 2023

alisonailea Nov 18, 2023

jcfranco Nov 16, 2023

jcfranco Nov 16, 2023

alisonailea Nov 18, 2023

jcfranco Nov 16, 2023

alisonailea Nov 16, 2023

jcfranco commented Nov 16, 2023

jcfranco commented Nov 17, 2023 •

edited

Loading

		@@ -0,0 +1,52 @@
		/**
		* This is a copy/extension of sd-transforms/src/parsers/resolveReference.ts but now with better types!

feat!: refactor design tokens and token transformer #8149

feat!: refactor design tokens and token transformer #8149

Conversation

alisonailea commented Nov 8, 2023 • edited Loading

Summary

jcfranco commented Nov 16, 2023

jcfranco commented Nov 16, 2023 • edited Loading

jcfranco commented Nov 16, 2023

jcfranco left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jcfranco commented Nov 16, 2023

jcfranco commented Nov 17, 2023 • edited Loading

alisonailea commented Nov 8, 2023 •

edited

Loading

jcfranco commented Nov 16, 2023 •

edited

Loading

jcfranco commented Nov 17, 2023 •

edited

Loading