feat(gatsby-design-tokens): v2 #21240

fk · 2020-02-06T16:08:08Z

Description

This PR drafts the next major version (2) of gatsby-design-tokens.
TL;DR, we want to

adjust tokens following suggestion from https://github.com/gatsby-inc/gatsby-interface/issues/181
add a base theme-ui Gatsby theme, and the gatsbyjs.org-specific theme-ui theme; also ref. [www][gatsby-design-tokens] Port tokens / consolidate/add theme-ui theme from www #19115; wondering if those should be separate packages?

Documentation / Changelog

Preview of the updated README

Tokens

This update, apart from the goals mentioned above, moves the rudimentary tokens even closer to our current sole target, CSS. This e.g. means that instead of exporting an array of integers for fontSizes or space, we now provide rem values instead (while still making the v1 variants available — but we do have "soft" preferences irt default units for CSS which are emphasized by these breaking changes).
We currently only consume these tokens in the context of CSS, so let's make things a bit easier there:

fontsSizes exports rem values now; old values available at fontSizesRaw
space exports rem values now, too; old stuff available at spaceRaw
fonts exports a string now, ready to be used with the font-family CSS prop; old array of font family names available as fontsLists
radii now contains the px unit

The update also embraces theme-ui a bit more directly by partially adopting and/or inheriting its naming conventions for a bunch of tokens, making "theme composition using token groups" even easier than before.

Regarding the discussion in https://github.com/gatsby-inc/gatsby-interface/issues/181, everything but the space scale has been adjusted to hopefully "just work", or work easier than before. The update to v2 of gatsby-design-tokens should require almost no refactoring of values in gatsby-interface —

the transition properties partially follow a different naming convention
fonts.header changed to fonts.headling
radii values now come with the px unit, so the latter is not needed anymore in template literals

— and apart from that should be solved by removing the transformation of fontSizes and spaces to rem, and the joinoffonts` stacks. (cc @amberleyromo @greglobinski @Elanhant — please also see the "Infamous last words" section at the end).

Here's all changes listed by "token group":

`breakpoints`

BREAKING CHANGE: Remove breakpoints.xxs
- All tokens started as only being consumed via styled-system. In its context, and using an object to define breakpoints, breakpoints.xxs made sense/was required. Since we switched to theme-ui, it doesn't anymore. gatsby-interface defines its own set of breakpoints; the www source already adjusted this when composing its theme-uitheme, so this shouldn't hurt at all.
feat: add export breakpointsArray, ready for theme-ui's responsive styles feature

`colors`

feat: add missing steps in colors.blackFade and colors.whiteFade:
- add colors.blackFade[90]
- add colors.blackFade[40]
- add colors.blackFade[20]
- add colors.blackFade[5]
- add colors.whiteFade[90]
- add colors.whiteFade[40]
- add colors.whiteFade[20]
- add colors.whiteFade[5]
BREAKING CHANGE: fix colors.blackFade[80], colors.whiteFade[80]
- both were set to an opacity of .85, adjusted to .8
- TODO: Adjust a couple of values for gatsbyjs.org; no clue about where we currently might use this in gatsby-interface and related (.com/Cloud dashboard).
feat: port colors.code from the gatsbyjs.org theme-ui theme to the colors tokens
- 💚 This improves compliance with WCAG 2.0 AA color contrasts.
feat: add colors.code.copyButton
feat: add colors.code.lineHighlightBackground
feat: add colors.code.scrollbarTrack

`fonts`

feat: Add aliases body and sans for fonts.system
BREAKING CHANGE: rename fonts.header to fonts.heading
- Comply with theme-ui requirements: https://theme-ui.com/theme-spec#typography.
- TODO: Consumers need to refactor fonts.header to fonts.heading.
feat: Add alias brand for fonts.heading
BREAKING CHANGE: fonts exports a string now, ready to be used with the font-family CSS prop; the array of font family names is still available as fontsLists
💚 No need to join font family names in gatsby-interface any longer.

`fontSizes`

BREAKING CHANGE: fontSizes does now contain rem values; old scale (integers) still available as fontSizesRaw
feat: add export fontSizesPx
💚 No need to recalculate to rem in gatsby-interface anymore.

`fontWeights`

BREAKING CHANGE: Name fontWeights — switch from array to object
- Include the required theme-ui defaults body, heading, and bold (https://theme-ui.com/theme-spec#typography).
- body: 400
- semiBold: 600
  - TODO: gatsbyjs.org's source code expects this to be medium, needs minor refactor
- bold: 700
  - TODO: gatsby-interface defines bold as 800, whatever it consumes needs to refactor to use extraBold instead
- heading: 700
- extraBold: 800
  - TODO: gatsbyjs.org's source code expects this to be headingPrimary, needs minor refactor

`lineHeights`

feat: Add line heights heading (equivalent to the existing dense) and body (equivalent to the existing default) to satisfy theme-ui's "Typography" theme requirements

`radii`

BREAKING CHANGE: Add px unit to radii scale values.
💚 No need to add the px unit in when used in template literals, etc.
TODO: Consumers need to remove px from usages in template literals, etc.

`sizes`

BREAKING CHANGE: removed
- As discussed in https://github.com/gatsby-inc/gatsby-interface/issues/181, this moves the current gatsbyjs.org-centric sizes tokens to theme-gatsbyjs-org for clarity, until a clear pattern emerges.

`space`

BREAKING CHANGE: space does now contain rem values; old scale (integers) still available as spaceRaw
feat: add export spacePx
💚 No need to recalculate to rem in gatsby-interface anymore.

`transition`

feat: Add transition.default shortcut
feat: Add transition.curve.fastOutLinearIn from gatsby-interface
feat: Add transition.speed.faster (50ms), matching gatsby-interface's blink
feat: Add transition.speed.slower (1000ms), matching gatsby-interface's snail
BREAKING CHANGE: change transition.speed.slow from 350ms to 500ms, now matching gatsby-interface
💚 🔶 All values are now matching gatsby-interface, naming of two properties differs.
TODO: Adjust a couple gatsbyjs.org things, would suggest refactoring gatsby-interface and related.

`zIndices`

BREAKING CHANGE: removed
- As discussed in https://github.com/gatsby-inc/gatsby-interface/issues/181, this moves the current gatsbyjs.org-centric zIndices tokens to theme-gatsbyjs-orgfor clarity, until a clear pattern emerges.

Themes

Tested and working with gatsby-plugin-theme-ui@^0.3.0, theme-ui@^0.3.1; current www version of the two is assumed to be working, too. I have a version of www working with gatsby-design-tokens-next that I'll get a PR up for. — Edit: see PR #21276

feat: add base theme-ui Gatsby theme, gatsbyjs.org theme-ui theme
- Both themes don't tree-shake yet, so no agadoo yet in the corresponding gatsby-design-tokens/package.json scripts. @wardpeet I'd love to take your offer and would appreciate if we could take a look at the mess I made next week! 🙏
- Both export the theme-ui theme as theme and also provide individual token group exports (because we require them in www for usage outside of the theme-ui context).
- Example usage in www — see PR chore(www): Adjust for gatsby-design-tokens v2 #21276:
  - export { theme as default } from "gatsby-design-tokens/dist/theme-gatsbyjs-org" in www/src/gatsby-plugin-theme-ui/index
  - Directly import individual token groups with import { mediaQueries } from "gatsby-design-tokens/dist/theme-gatsbyjs-org".

Related Issues

[www][gatsby-design-tokens] Port tokens / consolidate/add theme-ui theme from www #19115 [www][gatsby-design-tokens] Port tokens / consolidate/add theme-ui theme from www
https://github.com/gatsby-inc/gatsby-interface/issues/181 gatsby-design-tokens update
chore(www): Adjust for gatsby-design-tokens v2 #21276 chore(www): Adjust for gatsby-design-tokens v2

Infamous last words

move gatsby-design-tokens to gatsby-interface?
add TS definitions right in the tokens package`?
move themes to bespoke packages?
gatsby-interface TONES vs "role-based tokens" in gatsby-design-tokens, and theme-ui's variants — e.g. would be nice to have the TONES available for usage with the themes, and theme-ui's sx prop, variants seems great to spec components (even if we don't use theme-ui components), etc.
transformers (px to rem, hex to rgb(a)) are cool :P
irt colors, we already have a need for a bit of functionality like e.g. this around additional metadata

- add black/whiteFade[90,40,20,5] - fix black/whiteFade[80], was 85%

- bgInline -> backgroundInline - bg -> background

This contained almost only sizes very specific to gatsbyjs.org — `avatar` and `headerHeight` aside. `gatsby-interface` has its own `dimensions` definitions and should be unaffected by this change.

Add named font-weights, including the required theme-ui defaults `body`, `heading`, and `bold` (https://theme-ui.com/theme-spec#typography): - body: 400 - semiBold: 600 - gatsbyjs.org's source code expects this to be `medium`, needs minor refactor - bold: 700 - `gatsby-interface` defines `bold` as `800`, whatever it consumes needs to refactor to use `extraBold` instead - heading: 700 - extraBold: 800 - gatsbyjs.org's source code expects this to be `headingPrimary`, needs minor refactor

- comply with theme-ui requirements: https://theme-ui.com/theme-spec#typography - consumers need to refactor `fonts.header` to `fonts.heading`

… ah well. TBD.

These tokens started as only being consumed via styled-system. In its context, and using an object to define breakpoints, this somewhat made sense/was required. Since we switched to theme-ui, it doesn't anymore. And since `gatsby-interface` defines its own breakpoints, and gatsbyjs.org's source code already removes this breakpoint along adjusting the scale from object to array as required by `theme-ui`, this shouldn't hurt.

… first step to bring stuff in line with `gatsby-interface`

Both themes don't tree-shake yet, so no agadoo. This enables - `import { theme as default } from "gatsby-design-tokens/dist/theme-gatsbyjs-org"` in `www/src/gatsby-plugin-theme-ui/index` - directly import individual token groups with `import { mediaQueries } from "gatsby-design-tokens/dist/theme-gatsbyjs-org"`

Pretty sure this is the most unelegant way to do this :D - add export `breakpointsArray`: breakpoints as expected by `theme-ui` - add export `fontsStrings`: oh naming things :-P … CSS value for `font-family` - add export `fontSizesRem`, - add export `spaceRem`: values in `rem`, as used by both gatsbyjs.org and `gatsby-interface` - adust `theme.js` accordingly - add TODO re:https://reverent-keller-9597e8.netlify.com/?path=/story/theme--tones

Ref. gatsby-inc/gatsby-interface#181

- alias `fonts.system` as `sans` - alias `fonts.heading` as `brand` - less noob - add `spacePx`, `fontSizesPx` (FWIW … ;))

We also have preferences irt default units. - `fontsSizes` exports `rem` values now; old values available at `fontSizesRaw` - `space` exports `rem` values now, too; old stuff available at `spaceRaw` - `fonts` exports a string now, ready to be used with the `font-family` CSS prop; old array of font family names available as `fontsLists`

gatsby-inc/gatsby-interface#181

For clarity, see discussion in gatsby-inc/gatsby-interface#181

- backgroundInline -> bgInline - background -> bg

…ign-tokens-next

- bump `gatsby-plugin-emotion` - remove `@emotion/core`, `@mdx-js/react` (ref. https://github.com/system-ui/theme-ui/blob/master/CHANGELOG.md#v030-2019-01-22) - `gatsby-design-tokens` currently has the version number provided by `gatsby-dev`, see #21240 for context)

fk · 2020-02-10T13:38:53Z

Ay, this is missing a youtube link: https://www.youtube.com/watch?v=zhVgbZdMdb0

sidharthachatterjee

🌮 🌮 🌮

sidharthachatterjee · 2020-02-10T14:53:28Z

Published in gatsby-design-tokens@2.0.0

fk · 2020-02-10T15:06:09Z

Thank you @sidharthachatterjee! 💜

To everyone following along: Let's continue the discussion about further changes over at https://github.com/gatsby-inc/gatsby-interface/issues/181 — the 2.0 release is by no means meant to be a stop to that (, and moar updates). 🤗

cc @wardpeet The changed microbundle scripts seem to have at least worked ("worked well" is another thing 😉) — still would love to take another look together at some point! 🙏

fk · 2020-02-10T15:18:21Z

FWIW — botched updating the changelog — my commit messages (that, squashed, became the PR commit message body) didn't contain the required things, only my PR description had these, and we missed c&p that when merging.

Will get a follow-up PR in. ✌️

fk · 2020-02-10T18:56:37Z

For anyone following along, unfortunately the 2.0.0 package is missing dist/theme and dist/theme-gatsbyjs-org (see https://unpkg.com/browse/gatsby-design-tokens@2.0.0/dist/ — thanks @sidharthachatterjee)!

I have my guesses on why that is (or … hold on, dist/index.esm.js also seems missing — well maybe I'm completely clueless 😛). Will figure out tomorrow — hoping for @sidharthachatterjee to help out the doge in me. 🤞 🤗

* Update to `theme-ui`, `gatsby-plugin-theme-ui` v0.3 - bump `gatsby-plugin-emotion` - remove `@emotion/core`, `@mdx-js/react` (ref. https://github.com/system-ui/theme-ui/blob/master/CHANGELOG.md#v030-2019-01-22) - `gatsby-design-tokens` currently has the version number provided by `gatsby-dev`, see #21240 for context) * No need to suffix `px` for `radii` in template literals and outside of `sx` anymore * Import `theme-ui` theme from `gatsby-design-tokens` * `fonts.header` -> `fonts-heading * Import from `gatsby-design-tokens/dist/theme-gatsbyjs-org` * `fonts.system` -> `fonts.body` Not a required change because `fonts.system` is still available, but IMO it's good to follow the `theme-ui` convention. * Stray `radii` suffix missed in 86de7c0 * `fontWeights.headingPrimary` -> `fontWeights.extraBold` * `fontWeights.medium` -> `fontWeights.semiBold` * `${t.transition.speed.default} ${t.transition.curve.default}` -> `default We can omit the transition-property/keyword, defaults to `all`. * `code.background` -> `code.bg` * Adjust sidebar transition speed The next v of `gatsby-design-tokens` defines `speed.slow` as `500ms`, before it was `250`. Let's use the default of `250ms` instead. Snappier actually feels better. * Use `transition.default` shortcut * Bump `gatsby-design-tokens` * FWIW bump moar

* Update to `theme-ui`, `gatsby-plugin-theme-ui` v0.3 - bump `gatsby-plugin-emotion` - remove `@emotion/core`, `@mdx-js/react` (ref. https://github.com/system-ui/theme-ui/blob/master/CHANGELOG.md#v030-2019-01-22) - `gatsby-design-tokens` currently has the version number provided by `gatsby-dev`, see gatsbyjs/gatsby#21240 for context) * No need to suffix `px` for `radii` in template literals and outside of `sx` anymore * Import `theme-ui` theme from `gatsby-design-tokens` * `fonts.header` -> `fonts-heading * Import from `gatsby-design-tokens/dist/theme-gatsbyjs-org` * `fonts.system` -> `fonts.body` Not a required change because `fonts.system` is still available, but IMO it's good to follow the `theme-ui` convention. * Stray `radii` suffix missed in 86de7c0 * `fontWeights.headingPrimary` -> `fontWeights.extraBold` * `fontWeights.medium` -> `fontWeights.semiBold` * `${t.transition.speed.default} ${t.transition.curve.default}` -> `default We can omit the transition-property/keyword, defaults to `all`. * `code.background` -> `code.bg` * Adjust sidebar transition speed The next v of `gatsby-design-tokens` defines `speed.slow` as `500ms`, before it was `250`. Let's use the default of `250ms` instead. Snappier actually feels better. * Use `transition.default` shortcut * Bump `gatsby-design-tokens` * FWIW bump moar

Elanhant · 2020-02-20T16:33:36Z

@fk

move gatsby-design-tokens to gatsby-interface?

If we ever use gatsby-design-tokens as part of gatsby-interface, then we could do this. Otherwise I'm not sure, since I don't think we want people having to pull the entire gatsby-interface library to get just the design tokens.

add TS definitions right in the tokens package`?

This makes sense, I can try tackling this when I have a bit more free time :)

fk · 2020-02-21T12:10:10Z

If we ever use gatsby-design-tokens as part of gatsby-interface, then we could do this. Otherwise I'm not sure, since I don't think we want people having to pull the entire gatsby-interface library to get just the design tokens.

👍 Yeah TBH I can't really make sense of this myself anymore (multiple entry points/tree-shaking aside) — I probably thought gatsby-interface was its own GitHub org for a minute there 🤷‍♂

fk · 2020-02-21T12:11:01Z

add TS definitions right in the tokens package`?

This makes sense, I can try tackling this when I have a bit more free time :)

I already did look into this a little, maybe I can get a draft PR up …

Elanhant · 2020-02-21T15:47:05Z

add TS definitions right in the tokens package`?

This makes sense, I can try tackling this when I have a bit more free time :)

I already did look into this a little, maybe I can get a draft PR up …

I actually have added some definitions to gatsby-interface here, so probably the easiest approach for now is just to add an index.d.ts file with those definitions (updated to reflect latest changes) and make sure it's included in the bundle and correctly linked via types property in package.json 🙂

* Update to `theme-ui`, `gatsby-plugin-theme-ui` v0.3 - bump `gatsby-plugin-emotion` - remove `@emotion/core`, `@mdx-js/react` (ref. https://github.com/system-ui/theme-ui/blob/master/CHANGELOG.md#v030-2019-01-22) - `gatsby-design-tokens` currently has the version number provided by `gatsby-dev`, see gatsbyjs/gatsby#21240 for context) * No need to suffix `px` for `radii` in template literals and outside of `sx` anymore * Import `theme-ui` theme from `gatsby-design-tokens` * `fonts.header` -> `fonts-heading * Import from `gatsby-design-tokens/dist/theme-gatsbyjs-org` * `fonts.system` -> `fonts.body` Not a required change because `fonts.system` is still available, but IMO it's good to follow the `theme-ui` convention. * Stray `radii` suffix missed in 86de7c0 * `fontWeights.headingPrimary` -> `fontWeights.extraBold` * `fontWeights.medium` -> `fontWeights.semiBold` * `${t.transition.speed.default} ${t.transition.curve.default}` -> `default We can omit the transition-property/keyword, defaults to `all`. * `code.background` -> `code.bg` * Adjust sidebar transition speed The next v of `gatsby-design-tokens` defines `speed.slow` as `500ms`, before it was `250`. Let's use the default of `250ms` instead. Snappier actually feels better. * Use `transition.default` shortcut * Bump `gatsby-design-tokens` * FWIW bump moar

fk added 23 commits January 25, 2020 03:40

Fix colors.black/whiteFade

7973ea6

- add black/whiteFade[90,40,20,5] - fix black/whiteFade[80], was 85%

Modify code colors to comply to WCAG 2.0 AA

9894c03

Add code colors copyButton, lineHighlightBackground, scrollbarTrack

1f6a056

Refactor code color names

17ae7a6

- bgInline -> backgroundInline - bg -> background

Remove sizes

bead6a4

This contained almost only sizes very specific to gatsbyjs.org — `avatar` and `headerHeight` aside. `gatsby-interface` has its own `dimensions` definitions and should be unaffected by this change.

Add alias body for fonts.system, rename fonts.header to .heading

be59ada

- comply with theme-ui requirements: https://theme-ui.com/theme-spec#typography - consumers need to refactor `fonts.header` to `fonts.heading`

Add line-heights required by theme-ui

b5ccb53

… ah well. TBD.

Add transition.default, .curve.fastOutLinearIn, .speed.faster, .slower

f1fcae7

… first step to bring stuff in line with `gatsby-interface`

@todo -> TODO

be1acf1

Add basic theme-ui theme

8938272

Fix that watch script stuff lol

c93f437

Add px unit to radii scale values

017170a

Ref. gatsby-inc/gatsby-interface#181

Tidy

17a9ae2

- alias `fonts.system` as `sans` - alias `fonts.heading` as `brand` - less noob - add `spacePx`, `fontSizesPx` (FWIW … ;))

Change transition.speed.slow to 500ms

9cc3bd5

gatsby-inc/gatsby-interface#181

Move zIndices to theme-gatsbyjs-org

2b2a3c4

For clarity, see discussion in gatsby-inc/gatsby-interface#181

Too clever

79caddc

Order

2ef1ae1

Revert Refactor code color names

706346c

- backgroundInline -> bgInline - background -> bg

fk marked this pull request as ready for review February 7, 2020 16:02

fk requested review from a team as code owners February 7, 2020 16:02

gatsbybot and others added 3 commits February 7, 2020 16:11

Merge remote-tracking branch 'upstream/master' into topics/gatsby-des…

514732c

…ign-tokens-next

Bump agadoo, add hex2rgba

4596c9d

Fix code.bg/.bgInline keys for dark mode

efa03cb

fk changed the title ~~feat(gatsby-design-tokens): Next~~ feat(gatsby-design-tokens): v2 Feb 7, 2020

fk mentioned this pull request Feb 7, 2020

chore(www): Adjust for gatsby-design-tokens v2 #21276

Merged

fk added 2 commits February 8, 2020 00:47

Bump README

61a85ef

Bump README moar

8eb8b6c

sidharthachatterjee approved these changes Feb 10, 2020

View reviewed changes

sidharthachatterjee added the bot: merge on green Gatsbot will merge these PRs automatically when all tests passes label Feb 10, 2020

gatsbybot merged commit f754fc2 into master Feb 10, 2020

delete-merged-branch bot deleted the topics/gatsby-design-tokens-next branch February 10, 2020 14:48

fk mentioned this pull request Feb 11, 2020

[www][gatsby-design-tokens] Port tokens / consolidate/add theme-ui theme from www #19115

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(gatsby-design-tokens): v2 #21240

feat(gatsby-design-tokens): v2 #21240

fk commented Feb 6, 2020 •

edited

Loading

fk commented Feb 10, 2020

sidharthachatterjee left a comment

sidharthachatterjee commented Feb 10, 2020

fk commented Feb 10, 2020

fk commented Feb 10, 2020

fk commented Feb 10, 2020

Elanhant commented Feb 20, 2020

fk commented Feb 21, 2020

fk commented Feb 21, 2020 •

edited

Loading

Elanhant commented Feb 21, 2020

feat(gatsby-design-tokens): v2 #21240

feat(gatsby-design-tokens): v2 #21240

Conversation

fk commented Feb 6, 2020 • edited Loading

Description

Documentation / Changelog

Tokens

breakpoints

colors

fonts

fontSizes

fontWeights

lineHeights

radii

sizes

space

transition

zIndices

Themes

Related Issues

Infamous last words

fk commented Feb 10, 2020

sidharthachatterjee left a comment

Choose a reason for hiding this comment

sidharthachatterjee commented Feb 10, 2020

fk commented Feb 10, 2020

fk commented Feb 10, 2020

fk commented Feb 10, 2020

Elanhant commented Feb 20, 2020

fk commented Feb 21, 2020

fk commented Feb 21, 2020 • edited Loading

Elanhant commented Feb 21, 2020

fk commented Feb 6, 2020 •

edited

Loading

`breakpoints`

`colors`

`fonts`

`fontSizes`

`fontWeights`

`lineHeights`

`radii`

`sizes`

`space`

`transition`

`zIndices`

fk commented Feb 21, 2020 •

edited

Loading