frontendguide.md

Digital Surgeons Front End Guide

Welcome to the Digital Surgeons front end guide! This is where we keep all of our guidelines for "front end" design and development, from more general core concepts to specific technical guidelines.

Table of Contents

• What Is Front End?
• Project Structure & Composition
  • Classing & Naming Conventions
• CSS
  • Purpose
  • Linting
  • Nesting
  • BEM
    • Block
    • Element
    • Modifier
    • Best Practices
  • IDs vs. Classes
  • Color Units
  • Vendor Prefixes
• Javascript
  • Conventions
  • Linting & Style
• Icons

## What Is Front End The [front end guild at 18F](https://github.com/18F/frontend) did a series of exercises to determine the fundamental differences between the front end design and front end engineer roles. It came up with the following recommendations on knowing the difference between the two disciplines:

Front end designers design, write, and implement the presentational code base for websites and applications. They should have a clear understanding of design fundamentals and systems, such as interface style guides, responsive design, grid systems, front end frameworks, and accessibility best practices. Front end designers should feel comfortable creating and implementing design systems using semantic HTML5, CSS/SASS and be able to assist in debugging this aspect of the code base.

Front end engineers architect, write, and implement the functional code base for websites and applications. They should have a clear understanding of client-side render and response, such as HTTP methods, API consumption, the browser loading/rendering pipeline, and accessibility best practices. Front end developers should feel comfortable developing and implementing client-side interactions and frameworks using semantic HTML5 and JavaScript, and should be able to help with debugging, testing, and performance optimization of the code base.

## Project Structure & Composition Our project structure is centered around the idea of components. A `components` folder houses individual folders for specific components, each containing the [javascript](#javascript) and [scss](#css) necessary for that component.

For example:

/
/components
/components/header/
/components/header/index.js
/components/header/styles.scss

The main Javascript file, as well as Javascript unrelated to specific components, is housed in the js folder, e.g. /js/app.js.

The main SCSS file, as well as SCSS unrelated to specific components, is housed in the scss folder, e.g. /scss/app.scss.

We recognize that frameworks have their own way of doing things, and oftentimes a project will require the advanced features and structure that frameworks offer. However this boilerplate is intended for baseline vanilla projects and is framework agnostic.

Always look to abstract components. Digital Surgeons has a very strong, very consistent style and the reuse of components across designs helps to improve this consistency at an implementation level.

### Classing & Naming Conventions A name like `.homepageNav` limits its use. Instead think about writing styles in such a way that they can be reused in other parts of the app. Instead of `.homepageNav`, try instead `.nav` or `.navBar`. Ask yourself if this component could be reused in another context (chances are it could!). ## CSS ### Purpose The purpose of the CSS coding styleguide is to create consistent CSS or preprocessor CSS code across Digital Surgeons projects. The styleguide should be treated as a guide — rules can be modified according to project needs. ### Linting Digital Surgeons adheres to a specific SASS styleguide and uses a linting tool to ensure code never differs from this styleguide. We've created a `.scss-lint.yml` file that specifics our linting rules. Please refer to [this file](https://github.com/digitalsurgeons/boilerplate/blob/redeux/.scss-lint.yml) to find out what they are.

Linting setup with ruby:

1. Ensure the .scss-lint.yml file is at the base of your repository.
2. Install the scss-lint gem with gem install scss_lint
3. Run the linter with npm run scss-lint

### Nesting

Nesting makes it harder to tell at a glance where css selector optimizations can be made. Avoid it unless it's being used as a convenience to extend the parent selector over targeting nested elements. For example:

.block {
  padding: 24px;

  &--mini {
    padding: 12px;
  }
}

Nesting can be really easily avoided by smart class naming (with the help of BEM) and avoiding bare tag selectors.

### BEM [BEM](https://en.bem.info/method/) (**B**lock, **E**lement, **M**odifier) structures CSS such that every entity is composed of (you guessed it) blocks, elements and modifiers. From Harry Roberts: >The point of BEM is to tell other developers more about what a piece of markup is doing from its name alone. By reading some HTML with some classes in, you can see how – if at all – the chunks are related; something might just be a component, something might be a child, or element, of that component, and something might be a variation or modifier of that component. #### Block Unique, meaningful names for a logical unit of style.

Use a camelCase name.

• Good: .videoMasthead
• Bad: .video-masthead

Avoid excessive shorthand.

• Good: .alertBox or .recentsIntro or .button
• Bad: .feature or .content or .btn

#### Element Styles that only apply to children of a block. Elements can also be blocks themselves. Class name is a concatenation of the block name, two underscores and the element name. Examples: - `.alertBox__close` - `.expandingSection__title` #### Modifier Override or extend the base styles of a block or element with modifier styles. Class name is a concatenation of the block (or element) name, two hyphens and the modifier name. Use it to change appearance, behavior or state. Examples: - `.alertBox--success` - `.expandingSection--expanded` #### Best practices

Don't @extend block modifiers with the block base.

• Good: <div class="myBlock myBlock--modifier">
• Bad: <div class="myBlock--modifier">

Don't create elements inside elements. If you find yourself needing this, consider converting your element into a block.

• Bad: .alertBox__close__button

Choose your modifiers wisely. These two rules have very different meaning:

.block--modifier .block__element { color: red; }
.block__element--modifier { color: red; }

### IDs vs. Classes

You should almost never need to use IDs. Broken behavior due to ID collisions are hard to track down and annoying. If you must select an ID, select it by its data attibute because data attributes have the same specificty as classes:

[id='someID'] {
  color: 'red';
}

### Color Units When implementing feature styles, you should only be using color variables. Yes, even for hex codes `#000` and `#fff`! ### Vendor Prefixes Digital Surgeons uses the [PostCSS](https://github.com/postcss/postcss) plugin called [autoprefixer](https://github.com/postcss/autoprefixer) to parse CSS and add vendor prefixes to CSS rules using values from [Can I Use](caniuse.com).

This CLI can be used to run autoprefixer on css files containing scss.

Write your CSS rules without vendor prefixes (in fact, forget about them entirely):

.article {
  display: flex;
}

---

## Javascript

Our JavaScript style is an extension of the "Recommended" ESLint ruleset, with a few select linting rules to keep our code clean and consistent.

### Conventions

Our code is written to follow ES2015 conventions, utilizing features like:

• Arrow Functions

• Template Strings

• Classes & Constructors

  E.g.

  class Polygon {
    constructor (height, width) {
      this.height = height
      this.width = width
    }
  
    get area () {
      return this.calcArea()
    }
  
    calcArea () {
      return this.height * this.width
    }
  }
  
  const square = new Polygon(10, 10)

• Super() as a way to reference parent classes, e.g.

  class Cat {
    constructor (name) {
      this.name = name
    }
  
    speak () {
      console.log(this.name + ' makes a noise.')
    }
  }
  
  class Lion extends Cat {
    speak () {
      super.speak()
      console.log(this.name + ' roars.')
    }
  }

### Linting & Style

Our linting rules are flexible to work with both server-side and client-side code. The rules we enforce are:

• 2 spaces – for indentation
• Single quotes for strings
• No semicolons
• No unused variables
• Space after keywords if (condition) { ... }
• Space after function name function name (arg) { ... }

As you might have noticed, these are the main rules of standardJS, however we are only using the rules relevant to our team, rather than all of the standard rules.

## Icons The build process takes a list of SVG files inside the icons directory and creates a single sprite file using `` elements. You can reference them inside your html like this: ``` ```