Conventions

Table of Contents

• CSS
  • Inspirations
  • CSS Measurement Units
  • Organizing CSS
    • SMACSS Methodology
    • Property Grouping
    • CSS Commenting
• JavaScript
  • Syntax Preferences
    • Array & Object Declaration
• React
  • Import Statement
    • Import Grouping
    • Import PropTypes
  • Typechecking

CSS

Inspirations

Get inspired from these CSS Guides:

• CSS Architecture
• Trello CSS Guide
• Scss-Styleguide with BEM, OOCSS & SMACSS
• Google HTML/CSS Style Guide
• Obsessive CSS Code Formatting: Organization, Comments, and Signatures
• Frontend Guidelines Questionnaire

CSS Measurement Units

We are using different CSS units for different purposes.

Purpose	Unit	Reason
Media Query	em	em's cross-browser compatibility in Media Query is better than rem's
Font Sizing	rem	By consistently using rem unit, any element in the application will automatically adjust based on a single source of truth, the font-size of the html element.
Box Sizing (Margin, Border, Padding, Content)	rem	Same as above
Box Sizing exceptions (e.g. Very thin border which doesn't need to adapt to font-size)	px	Even though most elements are expected to auto-adjust themselves, not all of them are. So some reasonable exceptions are acceptable.

Organizing CSS

Well, since React doesn't specifically endorse a single standard for styling, there is a vast amount of options for Styling in React.

SMACSS Methodology

Let's try to implement SMACSS to make our CSS more modular & understandable.

Property Grouping

Group CSS Properties based on CSS Reference in w3schools.com.

.Button {
  /* Color */
  color: #FFFFFF;
  /* Background & Borders */
  background-color: #673AB7;
  border: .125rem solid #673AB7;
  border-radius: .25rem;
  /* Basic Box */
  padding: .625rem 1rem;
  width: 100%;
  /* Text */
  text-align: center;
  /* Fonts */
  font-size: 1rem;
  /* Animation */
  transition: 0.1s;
}

.Button:focus {
  /* Basic UI */
  outline: 0;
}

CSS Commenting

There are 3 types of comments in CSS:

Type	Purpose	Convention	Example
Filename	To identify the CSS source files after bundled by Webpack	triple asterisks	/*** Filename.css ***/
Rules Category	Categorizing CSS Rules based on SMACSS Categorizing	double asterisks	/** Base **/
Properties Group	Grouping CSS properties based on our Property Grouping convention. This type of commenting might seems overwhelming & such a waste of time. But I believe that it could enhance our way of thinking in CSS, especially in our early learning phase.	single asterisk	/* Background & Border */

JavaScript

Syntax Preferences

Array & Object Declaration

Always provide a trailling comma at the last item of Array/Object declaration. While it is still a valid JavaScript syntax, we could gain an advantage from this. By consistently doing this, we won't find any 'meaningless' lines of Git diff (due to trailling comma changes) anymore.

var obj = {
  prop1: "val1",
  prop2: "val2",
  prop3: "val3",  // Always provide a trailling comma here
}

var arr = [
  "val1",
  "val2",
  "val3",         // Always provide a trailling comma here
]

JSON

React

Import Statement

Import Grouping

Import statements are divided into 2 sections:

1. Node Modules: Imported modules from npm
2. Application Modules: Developed modules in the application, including js, css, images, etc.

Both sections has to be separated with a single linebreak, such as this example:

import React from 'react';

import Module from './Module';
import style from './Module.css';

Import PropTypes

Always use T identifier as an alias for PropTypes for the sake of a concise propTypes definition.

import { PropTypes as T } from 'react';
⋮
ComponentName.propTypes = {
  text: T.string.isRequired,
  number: T.number,
  item: T.shape({
    id: T.string.isRequired,
    name: T.string.isRequired,
    ⋮
  })
  ⋮
}

Typechecking

Please refer to React's official documentation for Typechecking With PropTypes.

Principles

1. Be Strict: Check every single property according to what the Component expects.
2. Mandatory/Optional Checking: Use isRequired properly, based on the Component usages of the props.
3. Deep Checking: Exstensive use of array, arrayOf(), object, objectOf(), instanceOf(), and shape is highly encouraged.
4. Prefer Enumerables: If enumerables type is possible to be used for a particular props, oneOf() or oneOftype() is preferred than a generic object such as number, string, or object.
5. Define Default Prop Values wherever it is relevant.