fix(www): Update README to include theme-ui (#18335)

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.