Add additional best practices to guide

Author: robertlong

.eslintrc.js

@@ -1,3 +1,4 @@
+// https://eslint.org/
 module.exports = {
   parser: "babel-eslint",
   env: {
@@ -11,19 +12,26 @@ module.exports = {
     NAF: true
   },
   plugins: ["prettier", "react", "react-hooks", "@calm/react-intl"],
+
+  // https://eslint.org/docs/rules/
   rules: {
+    // https://github.com/prettier/eslint-plugin-prettier
     "prettier/prettier": "error",
+
     "prefer-const": "error",
     "no-use-before-define": "error",
     "no-var": "error",
     "no-throw-literal": "error",
     // Light console usage is useful but remove debug logs before merging to master.
     "no-console": "off",
+
+    // https://www.npmjs.com/package/eslint-plugin-react-hooks
     "react-hooks/rules-of-hooks": "error",
     "react-hooks/exhaustive-deps": "warn",
-    // TODO: Move to throwing lint errors for react-intl once migration is complete
+
+    // https://github.com/calm/eslint-plugin-react-intl
     "@calm/react-intl/missing-formatted-message": [
-      "warn",
+      "error",
       {
         noTrailingWhitespace: true,
         ignoreLinks: true,
@@ -33,7 +41,7 @@ module.exports = {
       }
     ],
     "@calm/react-intl/missing-attribute": [
-      "warn",
+      "error",
       {
         noTrailingWhitespace: true,
         noSpreadOperator: true,
@@ -43,7 +51,12 @@ module.exports = {
         requireDefaultMessage: true
       }
     ],
-    "@calm/react-intl/missing-values": "warn"
+    "@calm/react-intl/missing-values": "error"
   },
-  extends: ["prettier", "plugin:react/recommended", "eslint:recommended"]
+  extends: [
+    // https://github.com/prettier/eslint-config-prettier
+    "prettier",
+    "plugin:react/recommended",
+    "eslint:recommended"
+  ]
 };

doc/best-practices.md

@@ -1,7 +1,29 @@
 # Hubs Frontend Development Best Practices
 
+The Hubs UI is built with React, CSS Modules, and a number of other libraries. This guide is intended to get you up to speed with how we on the Hubs team write frontend code.
+
+## Javascript Style
+
+We use [Prettier](https://prettier.io/) for code formatting and a series of [ESLint](https://eslint.org/) rules for linting.
+
+Currently the only modification we have made to the default prettier config is a 120 character line width. We as a team decided that 80 characters was not enough despite the Prettier team's [strong suggestion](https://prettier.io/docs/en/options.html#print-width).
+
+You can look at our [.eslintrc.js](../.eslintrc.js) file for our linting rules. Documentation for the various rules are linked in that file.
+
 ## React
 
+Hubs underwent a major redesign in 2020 and was transitioned from React class based components to React hooks in the process. There may still be some legacy code that uses class based components, but we intend to use hooks for all evergreen code.
+
+### React Resources
+- [Official React Docs](https://reactjs.org/docs/getting-started.html)
+
+### Hooks
+
+If you are new to React hooks we recommend the following guides to get started:
+- [Official React Docs on Hooks](https://reactjs.org/docs/hooks-intro.html)
+- [Thinking in React Hooks](https://wattenberger.com/blog/react-hooks)
+
+
 ### File / Folder Structure
 
 - Keep files relatively small
@@ -33,4 +55,55 @@
   - Wiring business logic to presentational components should be done in container components
     - Container components can depend on presentational components, hooks with business logic, and other container components.
     - Container components shouldn't contain html elements or their own stylesheets
--
+
+## CSS / CSS Modules
+
+Hubs uses [CSS Modules](https://github.com/css-modules/css-modules) and [SASS](https://sass-lang.com/) for styles.
+
+You should avoid global class names whenever possible and instead rely on imported classes from css modules in your code.
+
+SASS mixins, functions, etc. should generally be avoided whenever possible. They add complexity to stylesheets that makes them harder to read and understand.
+
+You should avoid nested SASS rules when possible. One major reason for using them is for [selector specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity). Another would be for programatically changing a single parent class that affects multiple child classes. Overuse of nested selectors bloats our stylesheets and should be avoided.
+
+We use "t-shirt size" class suffixes for utility classes. Follow this pattern whenever you need to specify programatic sizes.
+
+Ex.
+```css
+.button-2xs {}
+.button-xs {}
+.button-sm {}
+.button-md {}
+.button-lg {}
+.button-xl {}
+.button-2xl {}
+```
+
+All CSS colors and fonts should be defined in [theme.scss](../src/react-components/styles/theme.scss). These variables are configurable in Hubs Cloud instances. In some rare cases, you may want to explicitly enforce a color that cannot be configured (Ex. black/white text for an overlay).
+
+Theme variables are imported using the `@use` keyword. This must be the first line in your `.scss` file. All variables will be namespaced with the filename. For `theme.scss` this would be `theme.$my-variable`.
+
+Ex.
+
+```scss
+@use '../styles/theme';
+/* rest of the styles */
+```
+
+CSS styles should be written with mobile-first media queries. This means the styles in the bare class should represent those on the smallest screen and media queries should be used for styles that are different on larger screens.
+
+Ex.
+```scss
+:local(.sidebar) {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  background-color: theme.$white;
+  pointer-events: auto;
+
+  @media(min-width: theme.$breakpoint-lg) and (min-height: theme.$breakpoint-vr) {
+    border-left: 1px solid theme.$lightgrey;
+  }
+}
+```