feat(www): Add brand guidelines, design tokens docs (humble beginning…

…s) (gatsbyjs#14360)

* Basic port of https://mutability.netlify.com/

A humble first shot at documenting our brand guidelines, providing a place for people to find our logo, and document the design tokens used to create our OSS website UI.

Prior work shipped to mutability.netlify.com used https://styled-system.com/ under the hood. I really enjoyed working with it, but using it for .org `www` of course should be thoroughly discussed. I’m including it here to facilitate a discussion, …and to ship things! ;-)

- consolidate prior work with existing .org `www` design tokens
  - add a breakpoint `xxs`, required to make styled-system’s https://styled-system.com/responsive-styles work
  - add rudimentary `colors.blackFade` and `colors.whiteFade`
  - extend `tokens/font-sizes`, now generated via a formula that outputs (device) pixel values; generated values are manually adjusted, then converted to `rem` in `utils/presets`
- update link to mutability.netlify.com on `/contributing/organize-a-gatsby-event` to point to `/guidelines/logo/`
- add an item „Logo & Assets“ to the global footer, linking to `/guidelines/logo/`
- add `presets.fontWeights`
- add `presets.borders`

The original PoC implementation also makes use of `react-spring` and `react-visibility-sensor` to add some „text highlighting“ animations, and uses `react-copy-to-clipboard` and the `color` package to facilitate UI behavior and various calculations for the „Color“ part of the guidelines.

I’m not opposed to remove the animations — they don’t add much — but might need some help in dropping the `color` lib if we want to get that dep out of the bundle. Noob alert! ;-)

Oh, `react-copy-to-clipboard` probably should go, too. Unfortunately we still didn’t settle on anything reusable.

—

Wether we go for `styled-system` or not, we should think about using `emotion`’s context/`emotion-theming` moving forward. No need to explicitly import stuff esp. now that refactoring things have settled down.
I recall @jxnblk saying there are treeshaking/bundle size benefits to not doing so, though.

—

Todo:

- fix/expand „Color“ data, content and UI
  - fix missing color swatches for black and white on the „Logo“ page
- add `letterSpacing`, `lineHeights`, `fontWeights` token documentation to „Typography“, tidy examples here and there
- add partner logo lockup guide to „Logo“
- give the copy a very close second look
- lots more in and out of scope for this PR :-P — will follow up on that

* @styled-system/should-forward-prop

* Content

* Remove <Annotation>, <Words>

* No need for custom badge

* Remove „Logo“ masthead background

* Rm Spectral

* Copy

* Callout styles

* Add radii

* teal -> orange

* Tidy

* Basic fixes for „Copy HEX“ tooltip

* Copy, hierarchy

* Bump styled-system to v4.2.4

* Wrap up `shadows`; no need to put in more work here right now

* Fix nav item active state

🙏 @jxnblk

* Betterer?! :P

* Fix „Logo“ <ColorSwatch>

* Expand „Color Blindness“ section

* Remove a bunch of „Purple“ color names

* Reorder footer links

* Nicer „Footnotes“ links

* Add Futura PT Bold, make it the default for <h1>

* Basic improvements to the color modal

* More whitespace in between content columns

* Various <h1> fixes, add+use tokens/font-weights

* Add first shot at partnership lockup

* Rm textRendering:optimizeLegibility, we do this globally already

* Let it breathe ;)

* Fix a couple more stray `fontWeight`s

* Buttons

* Fix buttons

* Mv placeholder.js -> image-placeholder.js

* Mv navigation.js -> nav.item.js

* Simpler

* Fix Pantone link text color

* Date

* Rinse

* Add letter-spacing docs, rm letterSpacings.mega

* Various cleanup

- fix avatar size
- nicer `fontTokens` join to improve readability of the generated `font-family` value
- modify `fonts.header`, no need to repeat the system font stack
- Typography
  - add „Line Heights“ docs
  - tidy examples
- Design Tokens
  - add reference to the System UI Theme Specification
  - add reference to styled-system
  - improve „Shadows & Elevation“ layout
  - add docs for „Fonts“, „Font Sizes“, „Line Heights“
- Color
  - minor copy improvements
  - fix color overview layout
  - add WCAG contrast radio „legend“

* Fix tab-ability of color copy button

* <th scope=„col“>

* Fix markup, DRY

* Fix keys

* Add color code to copy button label

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Update www/src/assets/guidelines/wordmark.svg

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Update www/src/assets/guidelines/clearspace.svg

Prevent SVGs from being focusable in IE

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Prevent SVGs from being focusable in IE

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Prevent SVGs from being focusable in IE

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Prevent SVG from being focusable in IE, add title

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Prevent SVG from being focusable in IE, add title

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Render main content as <main>

* Prevent SVG from being focusable in IE, add title

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Prevent SVG from being focusable in IE, add title

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Fix d'oh

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Update www/src/pages/guidelines/logo.js

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Mention design tokens in `www` README

* Copy d'oh

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

* Fix color contrast

* Rm yellow background for „Scale“. A11y FTW!

* Bump color contrast

* Add basic <Helmet> stuff (title, html lang, canonical link, OG, Twitter site)

* Render as <ul>

* Add screenreader-only text describing the PMS link

* One more  focusable="false"

* Fix ecosystem card title font-weight

* Change `<div>` to `<section>` to allow `<h1>`

* Don’t show HEX color value when focussing copy button

* Fix copy button hover; minor UI fixes

* Full-width `font-sizes` tokens

* Small screen <3

* Add screenreader-only text that describes `space` and `border-radius` examples

* Change container tag to `section` to be able to use `<h1>`

* chore: format

* Add breakpoints+mediaQueries, colors, letterSpacings to „Design Tokens“

* Lowercase

* Add system font stack back to fonts.header

* Bring back focusable=„false“ via SVGO plugin

* Try

* chore: format

* Rm `data-image: icon`

* Lint

* Add zIndices, fontWeights, transitions

* Fix internal link

* Screenreader-only text for the „Colors“ design token examples

* Drop `color` dep

…in favor of `color-blend`, `wcag-contrast`, `hex-rgb`. Saves us a couple bytes of overhead.
Along the way:

- expand `blackFade`, `whiteFade`
- fix `blackFade` base color
- update "white or black text on colored background" examples in the color modal:
  - now all values from the `blackFade`/`whiteFade` that pass the WCAG color contrast ratio will be rendered (as opposed to a generic set of text colors ("High/medium emphasis", "Disabled") without any a11y information)
  - using `color-blend` to blend `rgba` values with the background color; scores very similar, but not exactly the same as on https://contrast-ratio.com/
- simplify the (very simple) inverted theme
- fix palette meta information
  - fix aliases

* Doc

* Clearer "Color" modal links

<3 @amberleyromo

* Last minute fixes

Thank you @amberleyromo for teaching me how to spell.

* Navigate to `/guidelines/logo/` when right-clicking Gatsby logo in header

I smell a11y issues TBH. Paging @marcysutton!
/cc @DSchau @KyleAMathews

* Bump to styled-system v5 🎉

* Rm `themed`

* Revert "Navigate to `/guidelines/logo/` when right-clicking Gatsby logo in header"

This reverts commit 3c47ad1.

* Use `themes.sizes.avatar` to define avatar dimensions

* Update Futura PT Bold font

- licensed for up to 2,000,000 page views
- added `font-display: swap`

* Rm link in footer

Let's go "dark deploy" (as discussed with @KyleAMathews)

* Change "WCAG Contrast Score" from <h4> to <h3>

* Add `aria-label` for color modal close button

* Add `title` to button that opens the modal

* Rm unused import

* Add `aria-label` to color swatch buttons

* Add HEX color value to swatch "copy" tooltip

* Lint

docs/contributing/organize-a-gatsby-event.md

@@ -26,7 +26,7 @@ There are several ways Gatsby may support your event:
 - The event must have at least half of the content focused on Gatsby or a Gatsby-related topic (such as JAMstack)
 - Both US and international events qualify for support
 - If you’re requesting the \$300 food credit, then you must submit a receipt for the expense
-- The event must be in harmony with the [Gatsby Code of Conduct](/contributing/code-of-conduct/) and follow the [Gatsby brand guidelines](https://mutability.netlify.com/logo/)
+- The event must be in harmony with the [Gatsby Code of Conduct](/contributing/code-of-conduct/) and follow the [Gatsby brand guidelines](/guidelines/logo/)
 
 ## How do you qualify for Gatsby support?
 

svgo.yml

@@ -1,8 +1,11 @@
 plugins:
+  - addAttributesToSVGElement:
+      attributes:
+        - focusable: false
   - collapseGroups: true
   - removeDesc: true
   - removeScriptElement: true
   - removeStyleElement: true
-  - removeTitle: true
+  - removeTitle: false
   - removeUselessDefs: true
   - removeViewBox: false

www/README.md

@@ -49,3 +49,7 @@ GATSBY_SCREENSHOT_PLACEHOLDER=true
 ```
 
 For more information checkout [`gatsby-transformer-screenshot` docs](http://www.gatsbyjs.org/packages/gatsby-transformer-screenshot#placeholder-image).
+
+## Design tokens
+
+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).

www/gatsby-config.js

@@ -86,6 +86,13 @@ module.exports = {
         path: `${__dirname}/src/data/ecosystem/`,
       },
     },
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `guidelines`,
+        path: `${__dirname}/src/data/guidelines/`,
+      },
+    },
     `gatsby-transformer-gatsby-api-calls`,
     {
       resolve: `gatsby-plugin-typography`,

www/package.json

@@ -5,16 +5,21 @@
   "author": "Kyle Mathews <mathews.kyle@gmail.com>",
   "dependencies": {
     "@emotion/core": "^10.0.7",
-    "@emotion/styled": "^10.0.7",
+    "@emotion/styled": "^10.0.12",
     "@mdx-js/mdx": "^1.0.14",
     "@mdx-js/react": "^1.0.6",
     "@reach/skip-nav": "^0.1.1",
     "@reach/visually-hidden": "^0.1.2",
+    "@styled-system/prop-types": "^5.0.5",
+    "@styled-system/should-forward-prop": "^5.0.5",
+    "@styled-system/theme-get": "^5.0.5",
     "@xstate/react": "^0.2.1",
     "axios": "^0.19.0",
     "bluebird": "^3.5.1",
+    "color-blend": "^2.0.4",
     "dotenv": "^6.0.0",
     "email-validator": "^1.1.1",
+    "emotion-theming": "^10.0.10",
     "fuse.js": "^3.2.0",
     "gatsby": "^2.9.1",
     "gatsby-image": "^2.0.5",
@@ -62,6 +67,7 @@
     "git-rev-sync": "^1.12.0",
     "graphql-request": "1.6.0",
     "gray-percentage": "^2.0.0",
+    "hex-rgb": "^4.1.0",
     "hex2rgba": "^0.0.1",
     "lodash-es": "^4.17.11",
     "mitt": "^1.1.3",
@@ -70,7 +76,9 @@
     "prismjs": "^1.14.0",
     "qs": "^6.5.2",
     "query-string": "^6.1.0",
+    "range": "^0.0.3",
     "react": "^16.8.6",
+    "react-copy-to-clipboard": "^5.0.1",
     "react-dom": "^16.8.6",
     "react-helmet": "^5.2.0",
     "react-highcharts": "^16.0.2",
@@ -82,8 +90,10 @@
     "remove-markdown": "^0.3.0",
     "slash": "^1.0.0",
     "slugify": "^1.3.0",
+    "styled-system": "^5.0.5",
     "typography": "^1.0.0-alpha.4",
     "typography-plugin-code": "^1.0.0-alpha.0",
+    "wcag-contrast": "^2.1.1",
     "xstate": "^4.5.0",
     "zipkin": "^0.14.2",
     "zipkin-javascript-opentracing": "^2.0.0",

www/src/components/diagram.js

@@ -13,6 +13,7 @@ import {
   lineHeights,
   fontSizes,
   fonts,
+  fontWeights,
 } from "../utils/presets"
 import logo from "../monogram.svg"
 import { GraphQLIcon, ReactJSIcon } from "../assets/logos"
@@ -252,6 +253,7 @@ const Diagram = () => (
       >
         <h1
           css={{
+            fontWeight: fontWeights[1],
             marginTop: 0,
             marginBottom: space[6],
             [mediaQueries.md]: {

www/src/components/ecosystem/ecosystem-section.js

@@ -15,6 +15,7 @@ import {
   shadows,
   mediaQueries,
   fontSizes,
+  fontWeights,
 } from "../../utils/presets"
 
 const EcosystemSectionRoot = styled(`section`)`
@@ -63,6 +64,7 @@ const Title = styled(`h1`)`
   color: ${colors.gatsby};
   display: flex;
   font-size: ${fontSizes[4]};
+  font-weight: ${fontWeights[1]};
   line-height: ${lineHeights.solid};
   margin: 0;
   margin-bottom: ${space[1]};

www/src/components/guidelines/avatar.js

@@ -0,0 +1,16 @@
+import styled from "@emotion/styled"
+
+import { Box } from "./system"
+
+const Avatar = styled(Box)()
+
+Avatar.defaultProps = {
+  bg: `grey.10`,
+  borderRadius: 6,
+  flex: `0 0 auto`,
+  height: `avatar`,
+  lineHeight: `solid`,
+  width: `avatar`,
+}
+
+export default Avatar

www/src/components/guidelines/badge.js

@@ -0,0 +1,47 @@
+import React from "react"
+import styled from "@emotion/styled"
+import { border, typography, compose } from "styled-system"
+import propTypes from "@styled-system/prop-types"
+
+import { Flex } from "./system"
+
+const styleProps = compose(
+  border,
+  typography
+)
+
+const BadgeBase = styled(Flex)(
+  {
+    display: `inline-flex`,
+    position: `relative`,
+    textTransform: `uppercase`,
+  },
+  styleProps
+)
+
+BadgeBase.propTypes = {
+  ...propTypes.border,
+  ...propTypes.typography,
+}
+
+BadgeBase.defaultProps = {
+  alignItems: `center`,
+  bg: `yellow.10`,
+  border: 1,
+  borderColor: `yellow.10`,
+  borderRadius: 5,
+  color: `yellow.90`,
+  fontFamily: `system`,
+  fontSize: 0,
+  fontWeight: 0,
+  letterSpacing: `tracked`,
+  lineHeight: `solid`,
+  py: 1,
+  px: 2,
+}
+
+const Badge = ({ children, ...rest }) => (
+  <BadgeBase {...rest}>{children}</BadgeBase>
+)
+
+export default Badge