[WIP] WSO 2020 Summer Redesign

[walnutdust]

WSO 2020 Summer Redesign

Last Updated June 23

This document contains helpful information, notes, and guidelines for updating the codebase moving forward. Please read through this document at least once before embarking on making any changes. This document will be periodically updated to provide more information.

Additional Information

Throughout this document, information in quotes (like this one) are meant only to provide additional background or thoughts, and may be safely skipped.

We will be using Elastic UI for React components, and SASS with CSS modules for additional styling.

The Figma file can be found here

Table of Contents

1. Getting Started
2. Project Structure
3. EUI
4. SASS
5. Design Flow
6. Guidelines
7. Troubleshooting

Getting Started

The design-update and respective design/<service> branches have been prepared with the necessary assets and libraries for this update. We will be using the design-update branch as the base branch for the design updates.

First, choose a service to work on:

1. Facebook - Taken by @japonte21
2. Factrak - Taken by @Conqueror1776
3. More to come...

Comment below, or PM me to choose a service to work on, and I will add your name above. From your command line, navigate to the wso-react folder, and perform the following commands, replacing <service> with the name of the service you are working on (e.g. facebook):

$ git pull
$ git checkout design/<service>
$ yarn
$ yarn start # Everything should run normally, as before.

See troubleshooting if there are errors.

Once everything is working as expected, navigate to src/index.js, and uncomment line 10 while commenting out line 11.

Before:

// import "./index.scss";
import "./components/i.scss";

After:

import "./index.scss";
// import "./components/i.scss";

This basically strips out all additional formatting from the old stylesheet - now it's up to us to create all the styles from scratch :) When working on your service, work within the white areas for now - i.e. someone else will be in charge of dealing with the navigation bar and footer.

Project Structure

├── src
│   ├── actions                  - Redux actions
│   ├── assets                   - Images, Icons, Logos, and more
│   ├── components               - React components
│   ├── constants                - Redux action names, "enums", and scheduler settings
│   ├── lib                      - Utility functions
│   ├── reducers                 - Redux reducers
│   ├── selectors                - Redux selectors
│   ├── store                    - Redux store set-up       
│   ├── tests                    - Redux/ React tests                       
│   ├── create-router.js         - Router set-up     
│   ├── index.js                 - Entrypoint into the code     
│   ├── index.scss               - Base SCSS styles
│   ├── router-permissions.js    - Router redirect if a user does not satisfy certain permissions
│   ├── routes.js                - What "wso.williams.edu/<>" routes are valid?
│   ├── serviceWorker.js         - Included in CRA. Not really relevant to us
│   ├── stateStorage.js          - Utility functions to save the state in `localStorage`             

Components are located in individual folders, by function, in src/components. Each component/view will have it's own individual folder, and it is where the style sheet folder should belong as well.

├── MyComponent
│   ├── index.jsx                       - JSX Component
│   ├── MyComponent.module.scss         - Stylesheet

EUI

Elastic UI is a React component library, and using component libraries allow us to easily iterate on designs while ensuring that the components are responsive, well-tested, and promote best accessibility practices.

Note that you don't have to use Elastic UI from start to end (e.g. there is no need to make every single component an Elastic UI component). Certain parts of design and layout might be easier dealt with by creating customized divs, and over time you'll learn to make the judgement call :)

SASS

To help out with additional styling, we will be using SASS (Synthetically Awesome Style Sheets), which is a superset of CSS and provides many additional useful features - a quick guide can be found here. SASS provides a cleaner syntax for CSS variables, nested syntax, and mixins, all of which help make it easier for us to create and adhere to a consistent theme.

You might also notice that some of the styling files have the file type .module.scss - this is a feature from CSS modules, which allow us to essentially import styles without the worry of conflicting with a different stylesheet. For example, If you have a .btn class in one stylesheet, and a .btn class in another stylesheets, when both of them are imported into your website, they are resolved in the order of imports, which can be confusing especially if they were important in separate files and it's up to the bundler/builder to decide how to place things together. This risk of confusion greatly increases with the project size, and people might accidentally create rules that ruins the styling in another part of the project.

CSS modules under the hood

In essence, CSS modules take the ruleset and hash them, and append create class names which are therefore "unique". For example, if you had a .btn class in Button.module.scss, this might be turned into .Button_A35SD3_btn. There's nothing stopping you in theory from doing this on your own, but why do it when the computer can do it for you?

Or, as the joke goes, "Two CSS rules walk into a bar. A bar stool in a completely different bar falls over."

SCSS Modules are used like this,

// MyComponent.module.scss
@import "../../theme.scss" // Allows you to use the variables in our base theme, more on that later

.myComponent {
  fontSize: $f-2;

  button {
    paddingTop: $px-1;
  }
}

// index.jsx
import styles from './MyComponent.module.scss';

// To use styles from MyComponent.module.scss:
<div className={styles.myComponent}>

As with the normal import syntax, it can also be done like:

// index.jsx
import {myComponent} from './MyComponent.module.scss';

// To use styles from MyComponent.module.scss:
<div className={myComponent}>

although you will have to be more careful when you use this method to avoid name conflicts.

Design Flow

Once you have chosen a project, you should be referencing the respective Figma file in your designs, and sticking to it where possible!

To help you with this, here are some tips:

1. Figure out the element hierarchy. What elements should belong together? What should be the child of what?
2. Figure out which components should use Elastic UI. Elastic UI has a very comprehensive set of components, so it might be helpful to start by figuring out what components you might want to use Elastic UI for, and it often helps in creating a quick first draft of the layout.
3. Code from outside in. It's helpful to start by laying everything out roughly where they should be before jumping in and fixing the minor details.
4. Use SCSS variables where possible In collaboration with our UI/UX designer, I have created common color and pixel variables in src/components/theme.scss. The figma designs should be based on these values, so use these variables wherever possible.
5. Elastic UI design can be overriden with our SCSS classes - important!

As always, feel free to use me as a resource or to bounce ideas off of me if it is helpful :)

Guidelines

Here are some guidelines when modifying the repository and keep things in good health. Not all of the code is held up to these standards, but with your effort we can make the code base healthier and easier for everyone to use!

1. Sort imports when they get too messy - Common sections include React Imports, Component/Stylesheet imports, Redux/store imports, Routing imports, External Imports. In each of these section, sort them by external imports -> internal imports, and then by alphabetical order.
2. Use alphabetical order for destructuring
3. Write code so good it does not need to be commented - Code should speak for itself where possible.
4. Avoid nested ternaries

FAQ

1. The current code looks bad.

Re-write it. Mercilessly. Most of the code was done fresh out of learning React, and the code quality is inconsistent in some spots. Clarify with me if you have any doubts, but otherwise believe that you should be in a good spot to know when code looks good or bad :)

Troubleshooting

1. git pull does not allow me to pull the branches.

error: cannot lock ref 'refs/remotes/origin/design/facebook': 'refs/remotes/origin/design' exists; cannot create 'refs/remotes/origin/design/facebook'
From github.com:WilliamsStudentsOnline/wso-react
 ! [new branch]      design/facebook -> origin/design/facebook  (unable to update local ref)
error: cannot lock ref 'refs/remotes/origin/design/factrak': 'refs/remotes/origin/design' exists; cannot create 'refs/remotes/origin/design/factrak'
 ! [new branch]      design/factrak  -> origin/design/factrak  (unable to update local ref)
error: some local refs could not be updated; 

This error is caused by conflicting branch names. Simply run git remote prune origin.

2. git checkout design/<service> does not allow me to check out the correct branch

fatal: cannot lock ref 'refs/heads/design/facebook': 'refs/heads/design' exists; cannot create 'refs/heads/design/facebook'

3. Running yarn start gives me a "Cannot find module 'xxx'" error
   Remove node_modules and reinstall the packages!

$ rm -rf node_modules
$ yarn
$ yarn start

This error is caused by having a branch called design in your local repository. Simply run git branch -D design.

[walnutdust]

Should close #20, #7