From 08dc747b74eb96a03b0c39fe05bcc1e02e88af60 Mon Sep 17 00:00:00 2001
From: Florian Kissling <21834+fk@users.noreply.github.com>
Date: Tue, 8 Oct 2019 21:47:46 +0200
Subject: [PATCH] fix(www): Update README to include theme-ui (#18335)

---
 www/README.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/www/README.md b/www/README.md
index 20cebb98644c8..2a36b2b1a1ee8 100644
--- a/www/README.md
+++ b/www/README.md
@@ -50,6 +50,13 @@ GATSBY_SCREENSHOT_PLACEHOLDER=true
 
 For more information checkout [`gatsby-transformer-screenshot` docs](http://www.gatsbyjs.org/packages/gatsby-transformer-screenshot#placeholder-image).
 
-## Design tokens
+## `theme-ui`, CSS authoring, and dark mode
 
-Please make use of the design tokens available in `src/utils/presets` when adding or modifying component CSS styles. You can find a work-in-progress documentation of these tokens at https://www.gatsbyjs.org/guidelines/design-tokens/ (and on some of the sibling pages documenting color and typography).
+Since [#18027](https://github.com/gatsbyjs/gatsby/pull/18027), we are using [`theme-ui`](https://theme-ui.com/) (via [`gatsby-plugin-theme-ui`](https://www.gatsbyjs.org/packages/gatsby-plugin-theme-ui/?=gatsby-plugin-theme)) to handle theming, CSS authoring, and to provide a dark color mode.
+
+- Please use the [`sx` prop](https://theme-ui.com/sx-prop) and theme values to style elements and components wherever possible. The prop is "enabled" by adding `theme-ui`'s [JSX pragma](https://theme-ui.com/jsx-pragma).
+- It is still okay to directly import tokens, e.g. `mediaQueries` or `colors` directly from `www/src/gatsby-plugin-theme-ui` if it helps your specific use case — for example when global CSS is required, when passing theme values to other libraries or plugins, when authoring complex responsive styles, etc.
+- It also is perfectly fine to follow the [`theme-ui` approach for responsive styles](https://theme-ui.com/getting-started/#responsive-styles)!
+- If you need to add fields to the [theme](https://theme-ui.com/theme-spec), you can do so in (the work-in-progress) `www/src/gatsby-plugin-theme-ui`. As things settle down, we will eventually migrate changed and added role-based tokens to https://www.npmjs.com/package/gatsby-design-tokens.
+- Please keep the dark mode in mind when editing existing or adding new components.
+- Please bear with us while we adjust https://www.gatsbyjs.org/guidelines/design-tokens/ to document the `theme-ui` values next to the raw token values.