Implement EDS Theming tooling #1738

booc0mtaco · 2023-08-31T21:56:32Z

Summary:

This adds some utility scripts to EDS to support setting up, applying, and updating token definitions, using style-dictionary. Further enhancements will be to support reading outputs from figma into a format EDS understands, and flagging theming errors where possible. Final phase will include support for diffing against EDS updates, so that newly-added tokens are available, or deprecated tokens are flagged.

This will also include usage instructions in-repo, as this is developer tooling.

init script to set up theming in a project
apply script to convert JSON into CSS tokens to read in code
updated config to package the correct files (bin/, theme files, etc.)
instructions on usage (how to set up config, options, gotchas, etc.)
FAQ location in README
Remove TODOs, and test integrations (config to theme EDS, etc.)

Test Plan:

Wrote automated tests
CI tests / new tests are not applicable
Manually tested my changes, but I want to keep the details secret
Manually tested my changes, and here are the details:
- Create an alpha publish and try out in along

github-actions · 2023-08-31T22:03:19Z

size-limit report 📦

Path	Size
components	95.29 KB (0%)
styles	32.77 KB (0%)

codecov · 2023-08-31T22:03:36Z

Codecov Report

Merging #1738 (cf176f1) into next (2b0855e) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             next    #1738   +/-   ##
=======================================
  Coverage   92.28%   92.28%           
=======================================
  Files         146      146           
  Lines        2580     2580           
  Branches      665      665           
=======================================
  Hits         2381     2381           
  Misses        183      183           
  Partials       16       16

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

📢 Have feedback on the report? Share it here.

booc0mtaco · 2023-09-01T14:57:47Z

Document usage flow:

yarn.lock

booc0mtaco · 2023-09-06T15:02:48Z

Created alpha version to test out on a few projects chanzuckerberg/[email protected]

booc0mtaco · 2023-09-06T18:47:27Z

Two tools generate expected outputs! will add in some additional checks for reading config, then post for review

timzchang

This makes sense to me! A couple questions and a nit in the readme only

timzchang · 2023-09-06T20:53:12Z

bin/eds-apply-theme.js

+  } catch (e) {
+    console.error('EDS package not installed. Using local path...');
+    packageRootPath =
+      path.dirname(require.main.path) + '/src/tokens-dist/json/';


what do we expect to be at this directory if eds is not installed?

This little bit is essentially for testing WITHIN EDS. I tested most of the functionality by dog-fooding this in the repo. I can update the error message to be info or something, and make this say something closer to that

timzchang · 2023-09-06T20:55:33Z

bin/eds-init.js

+  if (config) {
+    try {
+      fs.copyFileSync(
+        packageRootPath + 'theme-base.json',


where is theme-base created?

theme-base.json is generated along side the other style-dictionary output files (e.g., variables.css, et al), and gets shipped with EDS. For consumers it will live somewhere in node_modules/@chanzuckerberg/eds, and this line will match that location

Each released version of EDS will include an updated version of this file for two uses:

new projects will start off with a fresh copy that includes all the available tokens

existing projects can do a diff against their copy and this one to add/remove tokens that changes from EDS version X to Y

That second thing is another reason we have people editing JSON, as it is MUCH easier to build tooling around diffing JSON object as opposed to CSS files or some other content.

timzchang · 2023-09-06T20:58:58Z

.storybook/components/Docs/Guidelines/Theming.stories.mdx

+
+`json` determines where the core theme file will be stored, and `css` determines where the resulting css token file will be stored.
+
+### eds-init-theme


nit: can we name the files generated by eds-init-theme and specify which one to modify?

👍🏾! added in file names in appropriate spots and better sequencing in the doc.s

booc0mtaco · 2023-09-07T18:05:08Z

FYI going to merge this one as a merge commit instead of a squash to preserve the tag and commit for the alpha I tested with. We will have 1-2 follow up alpha releases to test TS interop and make sure rollup still provides something that works with consumer projects

EDIT: i forgot, rebased, and now the hashes changed, so that tag is in a detached HEAD state. which is fine. I'll just do a squash and merge like normal :)

Tickets: [EDS-996, EDS-746, EDS-747, EDS-749] - handle initializing token override file from base - handle configuration for local paths to use - handle comparison to base in package for checksum - handle updates to themes when base has changed

- update naming for consistency - add in better ordering of commands and exception handling - sync changes to style-dictionary - add documentation for using EDS commands - update README to link to new documentation

This reverts commit 3abf575.

## [13.2.0](v13.1.1...v13.2.0) (2023-09-07) ### Features * **Avatar:** add in expanded size range ([#1734](#1734)) ([7af6e5e](7af6e5e)) * **tokens:** add tooling for EDS theming ([#1738](#1738)) ([91497bf](91497bf)) ### Bug Fixes * opt our rollup CJS build into TS's module interop behavior ([#1747](#1747)) ([2b0855e](2b0855e))

booc0mtaco force-pushed the aholloway/eds-themnig branch from 1b6508d to e00137b Compare August 31, 2023 21:59

booc0mtaco force-pushed the aholloway/eds-themnig branch from e00137b to ffb888f Compare September 1, 2023 14:01

booc0mtaco commented Sep 1, 2023

View reviewed changes

yarn.lock Outdated Show resolved Hide resolved

booc0mtaco force-pushed the aholloway/eds-themnig branch 8 times, most recently from 6c19d71 to 334ad8f Compare September 5, 2023 23:15

timzchang approved these changes Sep 6, 2023

View reviewed changes

booc0mtaco marked this pull request as ready for review September 7, 2023 16:24

booc0mtaco requested a review from a team September 7, 2023 16:24

booc0mtaco added 7 commits September 7, 2023 13:29

feat(tokens): add tooling for EDS theming

fbdb115

Tickets: [EDS-996, EDS-746, EDS-747, EDS-749] - handle initializing token override file from base - handle configuration for local paths to use - handle comparison to base in package for checksum - handle updates to themes when base has changed

refactor: apply updates to prepare for introduction to EDS

2db7134

- update naming for consistency - add in better ordering of commands and exception handling - sync changes to style-dictionary - add documentation for using EDS commands - update README to link to new documentation

chore(release): 13.2.0-alpha.0

2b421dd

fix: add in safety checks to scripts

1272d75

fix: add error handling for missing config

fff75d8

docs: clarify file names and what each script creates

ae0f4db

chore(revert): undo alpha publish

cf176f1

This reverts commit 3abf575.

booc0mtaco force-pushed the aholloway/eds-themnig branch from 663a8ab to cf176f1 Compare September 7, 2023 18:29

booc0mtaco merged commit 91497bf into next Sep 7, 2023

booc0mtaco deleted the aholloway/eds-themnig branch September 7, 2023 18:56

booc0mtaco mentioned this pull request Sep 7, 2023

Release v13.2.0 #1749

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement EDS Theming tooling #1738

Implement EDS Theming tooling #1738

booc0mtaco commented Aug 31, 2023 •

edited

Loading

github-actions bot commented Aug 31, 2023 •

edited

Loading

codecov bot commented Aug 31, 2023 •

edited

Loading

booc0mtaco commented Sep 1, 2023

booc0mtaco commented Sep 6, 2023 •

edited

Loading

booc0mtaco commented Sep 6, 2023

timzchang left a comment

timzchang Sep 6, 2023

booc0mtaco Sep 7, 2023

timzchang Sep 6, 2023

booc0mtaco Sep 7, 2023

timzchang Sep 6, 2023

booc0mtaco Sep 7, 2023

booc0mtaco commented Sep 7, 2023 •

edited

Loading


		`json` determines where the core theme file will be stored, and `css` determines where the resulting css token file will be stored.

		### eds-init-theme

Implement EDS Theming tooling #1738

Implement EDS Theming tooling #1738

Conversation

booc0mtaco commented Aug 31, 2023 • edited Loading

Summary:

Test Plan:

github-actions bot commented Aug 31, 2023 • edited Loading

size-limit report 📦

codecov bot commented Aug 31, 2023 • edited Loading

Codecov Report

booc0mtaco commented Sep 1, 2023

booc0mtaco commented Sep 6, 2023 • edited Loading

booc0mtaco commented Sep 6, 2023

timzchang left a comment

Choose a reason for hiding this comment

timzchang Sep 6, 2023

Choose a reason for hiding this comment

booc0mtaco Sep 7, 2023

Choose a reason for hiding this comment

timzchang Sep 6, 2023

Choose a reason for hiding this comment

booc0mtaco Sep 7, 2023

Choose a reason for hiding this comment

timzchang Sep 6, 2023

Choose a reason for hiding this comment

booc0mtaco Sep 7, 2023

Choose a reason for hiding this comment

booc0mtaco commented Sep 7, 2023 • edited Loading

booc0mtaco commented Aug 31, 2023 •

edited

Loading

github-actions bot commented Aug 31, 2023 •

edited

Loading

codecov bot commented Aug 31, 2023 •

edited

Loading

booc0mtaco commented Sep 6, 2023 •

edited

Loading

booc0mtaco commented Sep 7, 2023 •

edited

Loading