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

* Fix colors.black/whiteFade

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

* Modify code colors to comply to WCAG 2.0 AA

* Add code colors copyButton, lineHighlightBackground, scrollbarTrack

* Refactor code color names

- bgInline -> backgroundInline
- bg -> background

* Remove sizes

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.

* Name font-weights

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

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

- 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

… ah well. TBD.

* Remove breakpoints.xxs

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.

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

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

* @todo -> TODO

* Add basic `theme-ui` theme

* Add gatsbyjs.org theme

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"`

* Fix that `watch` script stuff lol

* 🤒 Named exports, new exports

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

* Add `px` unit to radii scale values

Ref. gatsby-inc/gatsby-interface#181

* Tidy

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

* Default exports should honor the current main target (CSS)

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`

* Change `transition.speed.slow` to `500ms`

gatsby-inc/gatsby-interface#181

* Move `zIndices` to `theme-gatsbyjs-org`

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

* Too clever

* Order

* Revert Refactor code color names

- backgroundInline -> bgInline
- background -> bg

* Bump agadoo, add hex2rgba

* Fix `code.bg`/`.bgInline` keys for `dark` mode

* Bump README

* Bump README moar

Co-authored-by: GatsbyJS Bot <mathews.kyle+gatsbybot@gmail.com>

packages/gatsby-design-tokens/README.md

@@ -1,21 +1,36 @@
+<img src="https://user-images.githubusercontent.com/21834/74070062-35b91980-4a00-11ea-93a8-b77bde7b4c37.png" width="48" height="48" alt="rebeccapurple dot" />
+<br>
+<br>
+
 # gatsby-design-tokens
 
-Design tokens for Gatsby's design system.
+<a href="https://www.npmjs.org/package/gatsby-design-tokens">
+  <img src="https://img.shields.io/npm/v/gatsby-design-tokens.svg" alt="Current npm package version." />
+</a>
+<a href="https://npmcharts.com/compare/gatsby-design-tokens?minimal=true">
+  <img src="https://img.shields.io/npm/dm/gatsby-design-tokens.svg" alt="Downloads per month on npm." />
+</a>
+<a href="https://npmcharts.com/compare/gatsby-design-tokens?minimal=true">
+  <img src="https://img.shields.io/npm/dt/gatsby-design-tokens.svg" alt="Total downloads on npm." />
+</a>
 
-Design tokens originated at Salesforce—quoting the [Lightning Desing System Design Tokens documentation](https://www.lightningdesignsystem.com/design-tokens/):
+## Introduction
 
 > Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.
 
-Gatsby's design tokens are following the [System UI Theme Specification](https://system-ui.com/theme/).
-They are not fully complying to the design token abstraction and are (initially) primarily focused on CSS/JS development – i.e. a potential _output_ from design tokens.
+This quote from the [Lightning Desing System Design Tokens documentation](https://www.lightningdesignsystem.com/design-tokens/) accurately describes the tokens contained in this package — to be a bit more specific: `gatsby-design-tokens` offers _plain objects or arrays of values for related **CSS properties**_. Currently.
+
+Gatsby's design tokens are following the [System UI Theme Specification](https://system-ui.com/theme/) as well as the [Theme UI Theme Specification](https://theme-ui.com/theme-spec).
+
+### Project state and versioning
 
-They also are a work-in-progress but we _do_ follow the [Semantic Versioning](https://semver.org/) specification. As such:
+`gatsby-design-tokens` is a work-in-progress, but versions _do_ follow the [Semantic Versioning](https://semver.org/) specification:
 
-- Minor fixes to tokens will be released as patch versions
+- Minor fixes to tokens will be released as patch versions.
 - Major design changes will be released as minor versions
-- _Breaking_ public API changes will be released in a major versions only
+- _Breaking_ public API changes will be released in a major versions only.
 
-So to prevent your site from breaking due to a breaking change or looking dramatically different due to a minor version bump, we recommend the [~](https://docs.npmjs.com/misc/semver#tilde-ranges-123-12-1) comparator when using this package
+To prevent your site from breaking due to a breaking change or looking dramatically different due to a minor version bump, we recommend the [~](https://docs.npmjs.com/misc/semver#tilde-ranges-123-12-1) comparator when using this package.
 
 ## Installation
 
@@ -31,13 +46,112 @@ Using [Yarn](https://yarnpkg.com/):
 yarn add gatsby-design-tokens
 ```
 
-## Usage
+## Tokens 🍒🍋🍏
 
-Find a work-in-progress list of design tokens in the design tokens documentation at [gatsbyjs.org/guidelines/design-tokens](https://www.gatsbyjs.org/guidelines/design-tokens/).
+All exports provide either plain objects or arrays of values for related CSS properties:
 
 ```js
 import {
   borders,
+  // [ 0, `1px solid`, `2px solid` ]
+  breakpoints,
+  // { xs:`400px`, sm:`550px`, …}
+  breakpointsArray,
+  // [ "400px", "550px", …]
+  colors,
+  // { primary:`#639`, blackFade: { 5: `rgba(…)`, 10: …}, …}
+  fonts,
+  // { body: `-apple-system, …, sans-serif`, monospace: {…} }
+  fontsLists,
+  // { body: [`-apple-system`, …, `sans-serif`], monospace: […] }
+  fontSizes,
+  // [ `0.75rem`, …, `5.75rem` ]
+  fontSizesPx,
+  // [ `12px`, …, `92px` ]
+  fontSizesRaw,
+  // [ 12, 14, 16, 18, 20, 24, 28, 32, …, 84, 92 ]
+  fontWeights,
+  // { body: 400, semiBold: 600, …, heading: 700 }
+  letterSpacings,
+  // { normal: "normal", tracked: "0.075em", tight: "-0.015em" }
+  lineHeights,
+  // { solid: 1, dense: 1.25, … }
+  mediaQueries,
+  // { xs: "@media (min-width: 400px)", …, xxl: "@media (min-width: 1600px)" }
+  radii,
+  // [ 0, "2px", "4px", "8px", "16px", "9999px", "100%" ]
+  shadows,
+  // { raised: `0px 1px 2px rgba(46,…)`, floating: `0px 2px 4px…` }
+  space,
+  // [ "0rem", "0.25rem", "0.5rem", …, "4.5rem"]
+  spacePx,
+  // [ "0px", "4px", "8px", …, "72px"]
+  spaceRaw,
+  // [ 0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72]
+  transition,
+  // transition = {
+  //   default: `250ms cubic-bezier(0.4, 0, 0.2, 1)`,
+  //   curve: { default: `cubic-bezier(0.4, 0, 0.2, 1)`, … },
+  //   speed: { faster: `50ms`, … },
+  // }
+} from "gatsby-design-tokens"
+```
+
+- `rem` values are based on a `font-size` of `16px` for the root element.
+- All tokens work in the context of [Theme UI's Theme Scales](https://theme-ui.com/theme-spec/#theme-scales), with the exception of `breakpoints`: Use `breakpointsArray` for `theme-ui` and its [responsive styles](https://theme-ui.com/getting-started/#responsive-styles) feature.
+
+Find a work-in-progress list of design tokens in the design tokens documentation at [gatsbyjs.org/guidelines/design-tokens](https://www.gatsbyjs.org/guidelines/design-tokens/).
+
+## `theme-ui` themes 🎨
+
+### `theme`
+
+A basic `theme-ui` theme composed of unmodified tokens, with one exception: `colors` are modified to provide the basic set of variables described in https://theme-ui.com/theme-spec#color.
+
+TBD: Adopt the `theme-ui` definitions for the basic `colors` tokens.
+
+```js
+import { theme } from "gatsby-design-tokens/dist/theme"
+
+// when used with `gatsby-plugin-theme-ui`, export the theme
+// as default from `src/gatsby-plugin-theme-ui/index.js`
+export { theme as default } from "gatsby-design-tokens/dist/theme"
+
+// in case you need theme tokens outside of the `emotion` context
+import {
+  breakpoints,
+  colors,
+  fonts,
+  fontSizes,
+  fontWeights,
+  letterSpacings,
+  lineHeights,
+  mediaQueries,
+  radii,
+  shadows
+  space,
+  transition,
+} from "gatsby-design-tokens/dist/theme
+```
+
+### `theme-gatsbyjs-org`
+
+The theme currently in use on gatsbyjs.org via `gatsby-plugin-theme-ui`:
+
+- Extends the base theme's `colors` with a couple .org-specific things, and provides a `dark` mode (ref. https://theme-ui.com/color-modes).
+- Adds .org-specific `sizes` and `zIndices`.
+- Adds a couple of `variants`.
+- Uses `hex2rgba` to create rgba colors.
+
+```js
+import { theme } from "gatsby-design-tokens/dist/theme-gatsbyjs-org"
+
+// when used with `gatsby-plugin-theme-ui`, export the theme
+// as default from `src/gatsby-plugin-theme-ui/index.js`
+export { theme as default } from "gatsby-design-tokens/dist/theme-gatsbyjs-org"
+
+// in case you need theme tokens outside of the `emotion` context
+import {
   breakpoints,
   colors,
   fonts,
@@ -52,5 +166,80 @@ import {
   space,
   transition,
   zIndices,
-} from "gatsby-design-tokens"
+} from "gatsby-design-tokens/dist/theme-gatsbyjs-org"
+```
+
+## Local development
+
+The Gatsby monorepo, which hosts this package, also contains the source for gatsbyjs.org, aka `www` — where `theme-gatsbyjs-org` is in use. Using a little helper called `gatsby-dev` we can develop and test both of them locally.
+
+### 1. Clone the `gatsby` monorepo and set it up for local dev
+
+Follow the [official guide](https://www.gatsbyjs.org/contributing/setting-up-your-local-dev-environment/#fork-clone-and-branch-the-repository) to clone/fork and set up the Gatsby monorepo. This will roughly look like this:
+
+```bash
+# clone the repo/your fork
+git clone https://github.com/gatsbyjs/gatsby.git
+cd gatsby
+
+# set up the repo,install dependencies for `packages`, and build the latter
+yarn run bootstrap
+
+# make sure tests are passing
+yarn test
+
+# create a new feature branch
+git checkout -b topics/new-feature-name
 ```
+
+#### Install `gatsby-dev-cli` to ease testing your local changes to `packages`
+
+Assuming `gatsby-cli` [is installed](https://www.gatsbyjs.org/contributing/setting-up-your-local-dev-environment/#gatsby-functional-changes), let's install [`gatsby-dev-cli`](<(https://www.npmjs.com/package/gatsby-dev-cli)>) with
+
+```bash
+yarn global add gatsby-dev-cli
+```
+
+`gatsby-dev-cli` needs to know where your local Gatsby repository lives; navigate to its root folder, get the absolute path to it via `pwd`, and tell `gatsby-dev-cli` about it with
+
+```bash
+gatsby-dev --set-path-to-repo /path-to-local-gatsby/gatsby
+```
+
+### 2. Get `www` running on `localhost`
+
+```bash
+cd /path-to-local-gatsby/gatsby/www
+
+yarn # to install dependencies
+```
+
+Follow the [README instructions](https://github.com/gatsbyjs/gatsby/blob/master/www/README.md) to [add a .env.development file](https://github.com/gatsbyjs/gatsby/blob/master/www/README.md#environment-variables) in `www`, and add `GATSBY_SCREENSHOT_PLACEHOLDER=true` to
+
+> […] skip downloading screenshots and generating responsive images for all screenshots and replace them with a placeholder image
+
+Run `yarn develop`, which thanks to the previous step shouldn't take ~40 minutes but way less. Hopefully you should be able to browse a local version of gatsbyjs.org after this. Let's leave `yarn develop` running!
+
+### 3. Rebuild `gatsby-design-tokens` when it changes, and use `gatsby-dev` to copy the changed-and-compiled package over to `www/node_modules`
+
+- Open a new terminal window, go to the root of your local `gatsby` repo, and run `yarn run watch` to watch for changes in `packages`, and recompile the modified package.
+  - To watch only certain packages, use `yarn run watch --scope=gatsby-design-tokens` or `--scope={gatsby,gatsby-cli}`.
+- Last, in another new terminal window, go to `gatsby/www`, and run `gatsby-dev --packages=gatsby-design-tokens` to copy the latest local version of the `gatsby-design-tokens` package over to `www/node_modules`.
+  - Alternatively pass an array to watch multiple packages, or use plain `gatsby-dev` to copy the latest versions of all local packages that are used in your project's `package.json`.
+
+### 4. Finally!
+
+Let's try if everything is running and watching and recompiling!
+Let's open `packages/gatsby-design-tokens/src/fonts.js`, and replace
+
+```js
+const header = [Futura PT, ...system]
+```
+
+with
+
+```js
+const header = system
+```
+
+and you should see `Futura PT` turning into `system-ui` within a few moments on your `localhost:8000`.

packages/gatsby-design-tokens/package.json

@@ -17,11 +17,17 @@
     "./dist/**/*"
   ],
   "scripts": {
-    "build": "(microbundle build --sourcemap=false -f es,cjs && agadoo dist/index.esm.js) || node -e \"console.log('\\nMicrobundle failed, make sure you\\'re using node version 10.16 or higher\\n');process.exit(1)\"",
+    "build": "npm run build:tokens && npm run build:theme && npm run build:theme-gatsbyjs-org",
     "prepare": "cross-env NODE_ENV=production npm run build",
-    "watch": "microbundle watch --sourcemap=false -f es,cjs"
+    "watch": "microbundle watch {src/index.js,src/theme.js,src/theme-gatsbyjs-org.js} --sourcemap=false -f es,cjs",
+    "build:tokens": "(microbundle build --sourcemap=false -f es,cjs && agadoo dist/index.esm.js) || node -e \"console.log('\\nMicrobundle failed, make sure you\\'re using node version 10.16 or higher\\n');process.exit(1)\"",
+    "build:theme": "(microbundle build src/theme.js -o dist/theme.js --sourcemap=false -f es,cjs) || node -e \"console.log('\\nMicrobundle failed, make sure you\\'re using node version 10.16 or higher\\n');process.exit(1)\"",
+    "build:theme-gatsbyjs-org": "(microbundle build src/theme-gatsbyjs-org.js -o dist/theme-gatsbyjs-org.js --sourcemap=false -f es,cjs) || node -e \"console.log('\\nMicrobundle failed, make sure you\\'re using node version 10.16 or higher\\n');process.exit(1)\""
   },
   "homepage": "https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-design-tokens#readme",
+  "dependencies": {
+    "hex2rgba": "^0.0.1"
+  },
   "devDependencies": {
     "agadoo": "^1.1.0",
     "cross-env": "^5.2.1",

packages/gatsby-design-tokens/src/borders.js

@@ -1 +1 @@
-export default [0, `1px solid`, `2px solid`]
+export const borders = [0, `1px solid`, `2px solid`]

packages/gatsby-design-tokens/src/breakpoints.js

@@ -1,9 +1,17 @@
-export default {
-  xxs: 0, // needed for styled-system
+const b = {
   xs: `400px`,
   sm: `550px`,
   md: `750px`,
   lg: `1000px`,
   xl: `1200px`,
   xxl: `1600px`,
 }
+
+export const breakpoints = b
+
+const bp = []
+for (const b in breakpoints) {
+  bp.push(breakpoints[b])
+}
+
+export const breakpointsArray = bp

packages/gatsby-design-tokens/src/colors.js

@@ -4,7 +4,7 @@ import preval from "preval.macro"
 // using syntaxes like const x = { ...var } adds side-effects to the export
 // preval precompiles it so we just return a single object.
 
-export default preval`
+export const colors = preval`
   const palette = {
     purple: {
       90: '#362066',
@@ -132,23 +132,33 @@ export default preval`
     warning: palette.red[70],
     // semi-transparent colors
     blackFade: {
-      80: 'rgba(' + blackRGB + ', 0.85)',
+      90: 'rgba(' + blackRGB + ', 0.9)',
+      80: 'rgba(' + blackRGB + ', 0.8)',
       70: 'rgba(' + blackRGB + ', 0.7)',
       60: 'rgba(' + blackRGB + ', 0.6)',
       50: 'rgba(' + blackRGB + ', 0.5)',
+      40: 'rgba(' + blackRGB + ', 0.4)',
       30: 'rgba(' + blackRGB + ', 0.3)',
+      20: 'rgba(' + blackRGB + ', 0.2)',
       10: 'rgba(' + blackRGB + ', 0.1)',
+      5: 'rgba(' + blackRGB + ', 0.05)',
     },
     whiteFade: {
-      80: 'rgba(' + whiteRGB + ', 0.85)',
+      90: 'rgba(' + whiteRGB + ', 0.9)',
+      80: 'rgba(' + whiteRGB + ', 0.8)',
       70: 'rgba(' + whiteRGB + ', 0.7)',
       60: 'rgba(' + whiteRGB + ', 0.6)',
       50: 'rgba(' + whiteRGB + ', 0.5)',
+      40: 'rgba(' + whiteRGB + ', 0.4)',
       30: 'rgba(' + whiteRGB + ', 0.3)',
+      20: 'rgba(' + whiteRGB + ', 0.2)',
       10: 'rgba(' + whiteRGB + ', 0.1)',
+      5: 'rgba(' + whiteRGB + ', 0.05)',
     },
     // role-based tokens
     // this is merely a humble start, lots to do here
+    // TODO TBD gatsby-interface now has TONES, IMO worth to discuss
+    // moving them here
     ui: {
       background: palette.grey[5],
       hover: palette.purple[5],
@@ -177,18 +187,21 @@ export default preval`
       bg: "#fdfaf6",
       border: "#faede5",
       text: "#866c5b",
-      remove: "#e45c5c",
-      add: "#4a9c59",
-      selector: "#b3568b",
-      tag: "#4084a1",
-      keyword: "#538eb6",
-      comment: "#6f8f39",
+      remove: palette.red[70],
+      add: palette.green[80],
+      selector: "#b94185",
+      tag: "#137886",
+      keyword: "#096fb3",
+      comment: "#527713",
       punctuation: "#53450e",
-      regex: "#d88489",
+      regex: "#dc0437",
       cssString: "#a2466c",
       invisibles: "#e0d7d1",
       scrollbarThumb: "#f4d1c6",
       lineHighlightBorder: "#f1beb6",
+      copyButton: palette.grey[60],
+      lineHighlightBackground: "#fbf0ea",
+      scrollbarTrack: "#faede5",
     },
   }
 `

packages/gatsby-design-tokens/src/font-sizes.js

@@ -1,7 +1,6 @@
 import preval from "preval.macro"
 
-// scale
-export default preval`
+const fs = preval`
   let scale = [8]
 
   for (var i = 0; i < 18; i++) {
@@ -11,5 +10,12 @@ export default preval`
   // get rid of 8 and 10px font sizes
   scale.splice(0, 2)
 
-  module.exports = scale
+  const scalePx = scale.map(t => t + "px")
+  const scaleRem = scale.map(t => t / 16 + "rem")
+
+  module.exports = { scale, scalePx, scaleRem }
 `
+
+export const fontSizes = fs.scaleRem
+export const fontSizesPx = fs.scalePx
+export const fontSizesRaw = fs.scale

packages/gatsby-design-tokens/src/font-weights.js

@@ -1 +1,7 @@
-export default [400, 700, 800]
+export const fontWeights = {
+  body: 400,
+  semiBold: 600,
+  bold: 700,
+  extraBold: 800,
+  heading: 700,
+}