add: docs for storybook (#9120)

* add: docs for storybook

* Update visual-testing-with-storybook.md

docs/docs/visual-testing-with-storybook.md

@@ -0,0 +1,108 @@
+---
+title: Visual Testing with Storybook
+---
+
+Knowing your components look as intended in every permutation is not only a great way to test them visually, but also provides "living documentation" for them. This makes it easier for teams to:
+
+1) know what components are available to them in a given project and 
+2) what props those components accept and what all of the states of that component are. 
+
+As your project grows over time having this information available will be invaluable. This is the function of the Storybook library. Storybook is a UI development environment for your UI components. With it, you can visualize different states of your UI components and develop them interactively.
+
+## Setting up your environment
+
+In order to set up Storybook you will need to install a few dependencies and then do some custom configuration to make Storybook work with your Gatsby environment. The first thing is to get the Storybook CLI installed if you don't have it already.
+
+```sh
+npm install -g @storybook/cli
+```
+
+Once the CLI is installed, the next step is to run the `getstorybook` command that is now available from the root directory of your Gatsby project.
+
+```sh
+cd my-awesome-gatsby-project
+getstorybook
+```
+
+The `getstorybook` command will then bootstrap the basic config necessary to run Storybook for a React project. However, since this is for a Gatsby project, we need to update the default Storybook configuration a bit so that we don't get errors when trying to use Gatsby specific components inside of the stories.
+
+To update your Storybook config open `.storybook/config.js` and add the following before the `configure` method at the bottom of the file.
+
+```js
+// Gatsby's Link overrides:
+// Gatsby defines a global called ___loader to prevent its method calls from creating console errors we override it here
+global.___loader = {
+  enqueue: () => {},
+  hovering: () => {},
+}
+
+// Gatsby internal mocking to prevent unnecessary errors in storybook testing environment
+global.__PATH_PREFIX__ = ""
+
+// This is to utilized to override the window.___navigate method Gatsby defines and uses to report what path a Link would be taking us to if it wasn't inside a storybook
+window.___navigate = pathname => {
+  action("NavigateTo:")(pathname)
+}
+```
+
+Next we need up make some adjustments to Storybook's default `webpack` configuration so that we can tranpile Gatsby source files, as well as ensure we have all the necessary `babel` plugins we need to transpile Gatsby components.
+
+Create a new file called `webpack.config.js` in the `.storybook` folder created by the Storybook CLI. Then place the following in that file.
+
+```js
+module.exports = (baseConfig, env, defaultConfig) => {
+  // Transpile Gatsby module because Gastby includes un-transpiled ES6 code.
+  defaultConfig.module.rules[0].exclude = [/node_modules\/(?!(gatsby)\/)/]
+
+  // use installed babel-loader which is v8.0-beta (which is meant to work with @babel/core@7)
+  defaultConfig.module.rules[0].use[0].loader = require.resolve("babel-loader")
+
+  // use @babel/preset-react for JSX and env (instead of staged presets)
+  defaultConfig.module.rules[0].use[0].options.presets = [
+    require.resolve("@babel/preset-react"),
+    require.resolve("@babel/preset-env"),
+  ]
+
+  // use @babel/plugin-proposal-class-properties for class arrow functions
+  defaultConfig.module.rules[0].use[0].options.plugins = [
+    require.resolve("@babel/plugin-proposal-class-properties"),
+  ]
+
+  return defaultConfig
+}
+```
+
+Once you have this configured you should run Storybook to ensure it can start up properly and you can see the default stories installed by the CLI. To run storybook:
+
+```sh
+npm run storybook
+```
+
+Storybook CLI adds this command to your `package.json` for you so you shouldn't have to anything other than run the command. If Storybook builds successfully you should be able to navigate to `http://localhost:6006` and see the default stories supplied by the Storybook CLI.
+
+## Writing stories
+
+A full guide to writing stories is beyond the scope of this guide, but we'll take a look at creating a story.
+
+First, create the story file. Storybook looks for all files with a `.story.js` extension and loads them into Storybook for you. Generally you will want your stories near where the component is defined, however since this Gatsby, if you want stories for your pages, you will have to create those files outside of the `pages` directory.
+
+> A good solution is to create a `__stories__` directory next to your `pages` directory and put any page stories in there.
+
+```js:title=src/components/example.story.js
+import React from "react"
+import { storiesOf } from "@storybook/react"
+
+storiesOf(`Dashboard/Header`, module).add(`default`, () => (
+  <div style={{ padding: `16px`, backgroundColor: `#eeeeee` }}>
+    <h1 style={{ color: "rebeccapurple" }}>Hello from Storybook and Gatsby!</h1>
+  </div>
+))
+```
+
+This is a very simple story without much going on, but honestly, nothing else really changes as related to Gastby. If you want to learn more about how Storybook works and what you can do with it, check out some of the resources listed below.
+
+## Other resources
+
+- For more information on Storybook, visit
+  [the Storybook site](https://storybook.js.org/).
+- Get started with a [Jest and Storybook starter](https://github.com/Mathspy/gatsby-storybook-jest-starter)

www/src/data/sidebars/doc-links.yaml

@@ -169,6 +169,8 @@
           link: /docs/testing-css-in-js/
         - title: Testing React components
           link: /docs/testing-react-components/
+        - title: Visual testing with Storybook
+          link: /docs/visual-testing-with-storybook/
     - title: Debugging
       link: /docs/debugging/
       items: