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.
This quote from the Lightning Design System Design Tokens documentation 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 as well as the Theme UI Theme Specification.
gatsby-design-tokens
is a work-in-progress, but versions do follow the Semantic Versioning specification:
- 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 major versions only.
To prevent your site from breaking due to a breaking change or looking dramatically different due to a minor version bump, we recommend the ~ comparator when using this package.
Using npm:
npm install gatsby-design-tokens --save
Using Yarn:
yarn add gatsby-design-tokens
All exports provide either plain objects or arrays of values for related CSS properties:
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 afont-size
of16px
for the root element.- All tokens work in the context of Theme UI's Theme Scales, with the exception of
breakpoints
: UsebreakpointsArray
fortheme-ui
and its responsive styles feature.
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.
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
The theme currently in use on gatsbyjs.com via gatsby-plugin-theme-ui
:
- Extends the base theme's
colors
with a couple .org-specific things, and provides adark
mode (ref. https://theme-ui.com/color-modes). - Adds .org-specific
sizes
andzIndices
. - Adds a couple of
variants
. - Uses
hex2rgba
to create rgba colors.
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,
fontSizes,
fontWeights,
letterSpacings,
lineHeights,
mediaQueries,
radii,
shadows,
sizes,
space,
transition,
zIndices,
} from "gatsby-design-tokens/dist/theme-gatsbyjs-org"
The Gatsby monorepo, which hosts this package, also contains the source for gatsbyjs.com, 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.
Follow the official guide to clone/fork and set up the Gatsby monorepo. This will roughly look like this:
# 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
Assuming gatsby-cli
is installed, let's install gatsby-dev-cli
with
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
gatsby-dev --set-path-to-repo /path-to-local-gatsby/gatsby
cd /path-to-local-gatsby/gatsby/www
yarn # to install dependencies
Follow the README instructions to add a .env.development file 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.com 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 runyarn run watch
to watch for changes inpackages
, and recompile the modified package.- To watch only certain packages, use
yarn run watch --scope=gatsby-design-tokens
or--scope={gatsby,gatsby-cli}
.
- To watch only certain packages, use
- Last, in another new terminal window, go to
gatsby/www
, and rungatsby-dev --packages=gatsby-design-tokens
to copy the latest local version of thegatsby-design-tokens
package over towww/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'spackage.json
.
- Alternatively pass an array to watch multiple packages, or use plain
Let's try if everything is running and watching and recompiling!
Let's open packages/gatsby-design-tokens/src/fonts.js
, and replace
const header = [Futura PT, ...system]
with
const header = system
and you should see Futura PT
turning into system-ui
within a few moments on your http://localhost:8000
.