8709 task: design tokens used to output styles and documentation (colours) #2

creido-welly · 2021-07-09T15:54:41Z

Relates to wellcometrust/corporate#8709

Context

Design tokens will be the core of the design system long-term. Initially however the aim is to automate the process of outputting CSS variables for styling and also documentation for Storybook from a single source (i.e. a JSON file src/tokens/colour/base.json). Amazon's Style Dictionary enables us to do this very easily and for the long-term could be used to output other style formats e.g. iOS, Android, Kotlin.

This PR is a proof of concept for flat variables. Further discovery needed to work out how to output CSS containing media queries

Design token build files (src/build/css/colours.css, src/build/css/colours.js and src/build/css/colours.d.ts) are included in this commit and not specifically ignored as they are dependencies for the CSS and Storybook output.

To test

To run locally:

pull this branch
run npm install
run npm run storybook and check Globals > Colours
optionally, to preview how design tokens are generated run npm run build:tokens to output css, js and d.ts to src/build
run npm run build to output React and CSS for consumption in the dist folder

creido-welly · 2021-07-09T16:07:32Z

src/tokens/spacing/base.json

@@ -0,0 +1,39 @@
+{


Work in progress, not currently used to output CSS or docs

* initial work with using design tokens and style dictionary to output css variables for styling and js modules for documentation

src/stories/Colours.stories.tsx

aliceh75 · 2021-07-13T07:49:07Z

src/stories/Colours.stories.tsx

+      <tbody>
+        {tokenKeys.map((key) => {
+          const value = colourTokens[key];
+          const cssValue = /rgb/i.test(key) ? `rgb(${value})` : value;


This could fail if someone used the letters rgb in their variable name. For example, FlagColourGB. Doing a regex against the value might be safer than doing it against the key.

This line has been removed. Ultimately if we add RGB values we can handle that using a Style Dictionary transform.

aliceh75 · 2021-07-13T07:53:18Z

src/tokens/colour/base.json

+    "black":     { "value": "#000" },
+    "black-rgb": { "value": "0, 0, 0" },
+    "white":     { "value": "#fff" },
+    "white-rgb": { "value": "255, 255, 255" },


I'm wondering whether we couldn't auto-generate the rgb variants, rather than specify them manually ?

I like that idea. We could also auto output different formats such as HSL in future. It would also negate the issues around key names you highlighted

RGB values removed from the token file in favour of automatically inserting using a Style Dictionary transform.

src/utils/change-case.ts

aliceh75 · 2021-07-13T08:21:18Z

I've left a few comments. As a general feedback, I'm wondering whether generated files (the ones in src/build) should be added to the repository, or should be auto-generated by the build system. There are pros and cons to either approach - we should make sure we weigh them for our use case. Maybe you've already done this thought process, in which case it would be useful to document it ?

Pros of including them in the repository:

Local devs don't need to re-generate the files when they make changes. This might be particularly important for designers who want to use them.
This can potentially be used without a build system (though I expect other requirements mean that wouldn't be an option)
For this PR here, it was useful to be able to look at the output

Pros of generating them on-demand:

The files don't show in commits and pull requests
There's no risk of someone making a commit where the source version and build version are inconsistent

For me that last point - the risk of committing something inconsistent - is quite a strong one. It could be mitigated by CircleCi build checking for consistency.

creido-welly · 2021-07-13T11:15:54Z

@aliceh75 thanks for the feedback. I agree with you that committing build files to the repo seems to be the wrong approach given the reasons you mentioned above. As I mentioned in the PR blurb the only reason they are included is because the CSS and documentation output depend on them but I'm still not 100% happy with the approach.

If the build folder was ignored there is a risk of errors being raised when a user tries to build locally if the tokens haven't yet been generated. The obvious way to mitigate that would be to include npm run build:tokens at the beginning of every relevant npm script e.g.

"storybook": "npm run build:tokens && start-storybook -p 6006",

For me that last point - the risk of committing something inconsistent - is quite a strong one. It could be mitigated by CircleCi build checking for consistency.

I guess that's the alternative.

…ivalent for better robustness

… task/8709-design-token-prototyping # Conflicts: # .storybook/styles/storybook-app.scss

… task/8709-design-token-prototyping

* added token build process to build and dev processes to ensure generated variables are always available * removed rgb colour values from tokens list

… task/8709-design-token-prototyping

creido-welly · 2021-08-06T13:56:27Z

@aliceh75 thanks for the feedback. I agree with you that committing build files to the repo seems to be the wrong approach given the reasons you mentioned above. As I mentioned in the PR blurb the only reason they are included is because the CSS and documentation output depend on them but I'm still not 100% happy with the approach.

If the build folder was ignored there is a risk of errors being raised when a user tries to build locally if the tokens haven't yet been generated. The obvious way to mitigate that would be to include npm run build:tokens at the beginning of every relevant npm script e.g.
"storybook": "npm run build:tokens && start-storybook -p 6006",
For me that last point - the risk of committing something inconsistent - is quite a strong one. It could be mitigated by CircleCi build checking for consistency.

I guess that's the alternative.

@aliceh75 further to this previous discussion, the npm script has been updated to ensure tokens are generated before dependent processes run. This is really a temporary stop-gap while we work out a more suitable architecture.

…e naming to US English

creido-welly requested a review from chriddell July 9, 2021 15:54

creido-welly commented Jul 9, 2021

View reviewed changes

creido-welly added 3 commits July 9, 2021 17:11

8709 task: design token prototyping (WIP)

9510258

* initial work with using design tokens and style dictionary to output css variables for styling and js modules for documentation

8709 task: design token prototyping (WIP)

c524c72

* initial work with using design tokens and style dictionary to output css variables for styling and js modules for documentation

chore: added newline to gitignore end

c0e2ec6

creido-welly force-pushed the task/8709-design-token-prototyping branch from 1a6e6c6 to c0e2ec6 Compare July 9, 2021 16:11

creido-welly requested review from DipakShrestha18, stuartwilkes and aliceh75 July 9, 2021 16:17

aliceh75 reviewed Jul 13, 2021

View reviewed changes

src/stories/Colours.stories.tsx Outdated Show resolved Hide resolved

aliceh75 reviewed Jul 13, 2021

View reviewed changes

src/utils/change-case.ts Outdated Show resolved Hide resolved

aliceh75 reviewed Jul 13, 2021

View reviewed changes

src/utils/change-case.ts Outdated Show resolved Hide resolved

8709 task(chore): updated git ignore

e2ab937

creido-welly added 6 commits July 13, 2021 16:41

8709 task(chore): PR feedback - removed token build files from repo

5f6db7d

8709 task(chore): Replaced camelcase util with lodash

c374eb6

8709 task: Replaced camelCase and toCssVariable utils with lodash equ…

41ae07c

…ivalent for better robustness

Merge branch 'develop' of github.com:wellcometrust/design-system into…

3bf3147

… task/8709-design-token-prototyping # Conflicts: # .storybook/styles/storybook-app.scss

Merge branch 'develop' of github.com:wellcometrust/design-system into…

7cc62e5

… task/8709-design-token-prototyping

8709 task: design token prototyping pr feedback

d436a4c

* added token build process to build and dev processes to ensure generated variables are always available * removed rgb colour values from tokens list

creido-welly force-pushed the task/8709-design-token-prototyping branch from 10da041 to d436a4c Compare July 30, 2021 14:10

creido-welly mentioned this pull request Jul 30, 2021

8690 task: Added colours to storybook #7

Merged

Merge branch 'develop' of github.com:wellcometrust/design-system into…

6d10700

… task/8709-design-token-prototyping

creido-welly requested a review from aliceh75 August 6, 2021 13:56

8709 task: design token prototyping - updated colour variable and fil…

757ca49

…e naming to US English

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8709 task: design tokens used to output styles and documentation (colours) #2

8709 task: design tokens used to output styles and documentation (colours) #2

creido-welly commented Jul 9, 2021 •

edited

Loading

creido-welly Jul 9, 2021 •

edited

Loading

aliceh75 Jul 13, 2021

creido-welly Aug 6, 2021

aliceh75 Jul 13, 2021

creido-welly Jul 13, 2021

creido-welly Aug 6, 2021

aliceh75 commented Jul 13, 2021

creido-welly commented Jul 13, 2021

creido-welly commented Aug 6, 2021

8709 task: design tokens used to output styles and documentation (colours) #2

Are you sure you want to change the base?

8709 task: design tokens used to output styles and documentation (colours) #2

Conversation

creido-welly commented Jul 9, 2021 • edited Loading

Context

To test

creido-welly Jul 9, 2021 • edited Loading

Choose a reason for hiding this comment

aliceh75 Jul 13, 2021

Choose a reason for hiding this comment

creido-welly Aug 6, 2021

Choose a reason for hiding this comment

aliceh75 Jul 13, 2021

Choose a reason for hiding this comment

creido-welly Jul 13, 2021

Choose a reason for hiding this comment

creido-welly Aug 6, 2021

Choose a reason for hiding this comment

aliceh75 commented Jul 13, 2021

creido-welly commented Jul 13, 2021

creido-welly commented Aug 6, 2021

creido-welly commented Jul 9, 2021 •

edited

Loading

creido-welly Jul 9, 2021 •

edited

Loading