Move gatsby docs to Storybook (#2488)

* add mdx * fix build * test canvas format * url structure and static dir * fix static?
primer · Jul 12, 2023 · acc29de · acc29de
1 parent 9a580ff
commit acc29de
Show file tree

Hide file tree

Showing 99 changed files with 6,447 additions and 5,603 deletions.
diff --git a/docs/.storybook/main.js b/docs/.storybook/main.js
@@ -1,17 +1,22 @@
 module.exports = {
   stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
   addons: [
+    {
+      name: '@storybook/addon-essentials',
+      options: {
+        actions: false,
+        controls: false,
+        docs: true,
+        viewport: true,
+      },
+    },
     '@storybook/addon-a11y',
     '@storybook/addon-links',
-    '@storybook/addon-essentials',
     '@storybook/preset-scss',
-    '@whitespace/storybook-addon-html',
-    'storybook-addon-designs',
-    'storybook-color-picker',
-    'storybook-addon-variants/preset.js'
   ],
   framework: '@storybook/react',
   core: {
-    builder: 'webpack5'
-  }
+    builder: 'webpack5',
+  },
+  staticDirs: ['../src/stories/static'],
 }
diff --git a/docs/.storybook/preview-head.html b/docs/.storybook/preview-head.html
@@ -10,7 +10,6 @@
   .theme-wrap {
     display: grid;
     grid-template-columns: repeat(auto-fit, minmax(0, 1fr));
-    height: 100vh;
   }
 
   .theme-wrap .story-wrap {

diff --git a/docs/.storybook/preview.js b/docs/.storybook/preview.js
@@ -1,116 +1,114 @@
 import '../../src/docs.scss'
 import '../../src/index.scss'
 import '../../src/base/index.scss'
-import '../src/stories/helpers/storybook-styles.scss'
 // temporary import until primitives moves to core bundle
 // importing the index from /css didn't play nice with Storybook
-import '@primer/primitives/tokens-next-private/css/base/size/size.css';
-import '@primer/primitives/tokens-next-private/css/base/typography/typography.css';
-import '@primer/primitives/tokens-next-private/css/functional/size/border.css';
-import '@primer/primitives/tokens-next-private/css/functional/size/breakpoints.css';
-import '@primer/primitives/tokens-next-private/css/functional/size/size-coarse.css';
-import '@primer/primitives/tokens-next-private/css/functional/size/size-fine.css';
-import '@primer/primitives/tokens-next-private/css/functional/size/size.css';
-import '@primer/primitives/tokens-next-private/css/functional/size/viewport.css';
-import '@primer/primitives/tokens-next-private/css/functional/typography/typography.css';
-import renderToHTML from '../src/stories/helpers/code-snippet-html-helper'
+import '@primer/primitives/tokens-next-private/css/base/size/size.css'
+import '@primer/primitives/tokens-next-private/css/base/typography/typography.css'
+import '@primer/primitives/tokens-next-private/css/functional/size/border.css'
+import '@primer/primitives/tokens-next-private/css/functional/size/breakpoints.css'
+import '@primer/primitives/tokens-next-private/css/functional/size/size-coarse.css'
+import '@primer/primitives/tokens-next-private/css/functional/size/size-fine.css'
+import '@primer/primitives/tokens-next-private/css/functional/size/size.css'
+import '@primer/primitives/tokens-next-private/css/functional/size/viewport.css'
+import '@primer/primitives/tokens-next-private/css/functional/typography/typography.css'
 
 const customViewports = {
   minXS: {
     name: 'XS (min)',
     styles: {
       width: '320px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   medXS: {
     name: 'XS (med)',
     styles: {
       width: '375px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   maxXS: {
     name: 'XS (max)',
     styles: {
       width: '543px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   minSM: {
     name: 'SM (min)',
     styles: {
       width: '544px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   maxSM: {
     name: 'SM (max)',
     styles: {
       width: '767px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   minMD: {
     name: 'MD (min)',
     styles: {
       width: '768px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   maxMD: {
     name: 'MD (max)',
     styles: {
       width: '1011px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   minLG: {
     name: 'LG (min)',
     styles: {
       width: '1012px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   maxLG: {
     name: 'LG (max)',
     styles: {
       width: '1279px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   minXL: {
     name: 'XL (min)',
     styles: {
       width: '1280px',
-      height: '100%'
-    }
+      height: '100%',
+    },
   },
   medXL: {
     name: 'XL (med)',
     styles: {
       width: '1440px',
-      height: '100%'
-    }
-  }
+      height: '100%',
+    },
+  },
 }
 
 export const parameters = {
   actions: {argTypesRegex: '^on[A-Z].*'},
-  docs: {
-    transformSource: (src, storyContext) => renderToHTML(storyContext.storyFn)
-  },
+  // docs: {
+  //   transformSource: (src, storyContext) => renderToHTML(storyContext.storyFn),
+  // },
   controls: {
     matchers: {
       color: /(background|color)$/i,
-      date: /Date$/
+      date: /Date$/,
     },
-    expanded: true
+    expanded: true,
   },
 
   layout: 'padded',
   html: {
-    root: '#story' // target id for html tab (should be direct parent of <Story /> for easy copy/paste)
+    root: '#story', // target id for html tab (should be direct parent of <Story /> for easy copy/paste)
   },
   viewport: {viewports: customViewports},
   options: {
@@ -123,8 +121,8 @@ export const parameters = {
       }
       // sort as usual = alphabetical
       return -1
-    }
-  }
+    },
+  },
 }
 
 const themes = [
@@ -134,7 +132,7 @@ const themes = [
   'dark',
   'dark_dimmed',
   'dark_high_contrast',
-  'dark_colorblind'
+  'dark_colorblind',
 ]
 
 export const globalTypes = {
@@ -145,9 +143,9 @@ export const globalTypes = {
     toolbar: {
       icon: 'circlehollow',
       items: [...themes, 'all'],
-      showName: true
-    }
-  }
+      showName: true,
+    },
+  },
 }
 
 export const decorators = [
@@ -171,5 +169,5 @@ export const decorators = [
         })}
       </div>
     )
-  }
+  },
 ]
diff --git a/docs/package.json b/docs/package.json
@@ -57,10 +57,6 @@
     "@storybook/manager-webpack5": "^6.5.9",
     "@storybook/preset-scss": "^1.0.3",
     "@storybook/react": "6.5.0",
-    "@whitespace/storybook-addon-html": "^5.0.0",
-    "babel-loader": "^8.2.5",
-    "storybook-addon-designs": "6.2.1",
-    "storybook-addon-variants": "^0.0.5",
-    "storybook-color-picker": "2.3.1"
+    "babel-loader": "^8.2.5"
   }
 }
diff --git a/docs/script/build-storybook b/docs/script/build-storybook
@@ -8,7 +8,7 @@ else
 fi
 
 # Build storybook inside docs
-./node_modules/.bin/build-storybook -o public/storybook -s public/static
+./node_modules/.bin/build-storybook -o public/storybook public/static
 
 # Remove manager-head after build to not interfere with dev builds
 rm .storybook/manager-head.html
diff --git a/docs/src/stories/Contributing.stories.mdx b/docs/src/stories/Contributing.stories.mdx
@@ -0,0 +1,47 @@
+import {Meta} from '@storybook/addon-docs'
+
+<Meta title="Contributing" />
+
+While this contributing guide is for GitHub employees, all contributions from the community are welcome.
+
+## Adding new utilities
+
+Utilities do one thing well and one thing only. These styles are immutable and therefore often use the `!important` tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions:
+
+- How does this new utility fit within our existing set of utilities? If it is an addition to an existing set then it should follow the same naming convention.
+- Is it for a property that would likely need to be changed at different breakpoints? If so it may need responsive options.
+- If this style is part of a family of properties, do we need to consider adding the full set? Reasons for adding a full set could be that the other property values are often used, or that there would be a need to switch the property on and off (such as display or visibility).
+- Does introducing this new utility cause any clashes or potential confusion with the use of existing utilities? If so, what steps can we take to avoid those issues.
+- Does the utility have a connection with a set of variables? If so do the corresponding variables need to be updated?
+
+## Step-by-step instructions for adding new styles
+
+### Step 1: Open an issue
+
+It's usually better to open an issue before investing time in spiking out a new pattern. This gives the design systems team a heads up and allows other designers to share thoughts. Here's an outline of what's helpful to include in a new style issue:
+
+1. What the pattern is, and how it's being used on GitHub.com. Post screenshots and/or URLs whenever possible. If you need help identifying where the pattern is used, call that out in the issue.
+2. Why you think a new pattern is needed (this should answer the relevant questions above).
+3. If you intend to work on these new styles yourself, let us know what your timeline and next steps are. If you need help and this is a dependency for shipping another project, please make that clear here and what the timeline is.
+
+### Step 2: Design and build the new styles
+
+- When you're ready, spike out a branch and build out your new utility according to the style guide principles, ensuring you follow our naming convention for each of the styles.
+- Refactor parts of the product where you think those new styles could be used to test they work for each use case. This does not mean for every instance, but enough of the key use cases to be sure the styles are flexible enough. To avoid blowing out your initial pull request we recommend you do larger amounts of refactoring in an additional branch.
+- When you're ready for review, change your pull request from "Draft" to "Ready for review"
+
+## Storybook
+
+We use [Storybook](https://storybook.js.org/) to document and test our CSS. You can run Storybook locally by running `yarn storybook` and visiting the localhost server that is automatically started.
+
+Stories are written with React for better compatibility with Storybook. Each utility should have a story that demonstrates its use. Stories are located in the `stories` directory.
+
+### Versioning
+
+Primer CSS follows [semantic versioning](http://semver.org/) conventions. This helps others know when a change is a patch, minor, or breaking change.
+
+To understand what choice to make, you'll need to understand semver and know if one of the changes shown is a major, minor, or patch. Semver is confusing at first, so we recommend reviewing [semver](http://semver.org/) and/or asking the team by [opening an issue](#step-1-open-an-issue).
+
+[semantic versioning]: https://semver.org
+[script/test-deprecations.js]: https://github.com/primer/css/tree/main/script/test-deprecations.js
+[deprecations.js]: https://github.com/primer/css/tree/main/deprecations.js