Styleguide: General

General

Welcome to the edX General Front End Styleguide. This document is meant to be referenced alongside the following more detailed styleguides:

• Sass & CSS Styleguide
• HTML Styleguide
• Accessibility Styleguide

---

In general, edX styling should adhere to:

• four (4) spaces indents, no tabs;
• files should be named in all lowercase with - separating legible words (e.g. footer-global.html)
• prefix any partial or included file (a file that should not render on its own) with an underscore (e.g. _system-alerts.scss).

---

File Organization

Per application, we adhere to the following Front-End directory structure, with the assumption that we are working in a Django environment with Django templates and with Sass):

Note: Certain directories not pertaining to the scope of this Front End Development guide have been omitted for legibility.

[application-name]
...
├── static
|   └── vendor                       // vendor packages
|   └── vendor-extensions            // customizations to vendor packages
|   └── css
|   |   └── main.css                 // compiled css
|   ...
|   └── images
|   |   └── *.*                      // rendered in DOM/content images
|   |   └── bg-*.*                   // style-based background images
|   |   └── logo-*.*                 // logos/branding/official images
|   |   └── ico-*.*                  // style-based icon-based images
|   ...
|   └── js
|   ...
|   └── sass
|   |   └── base                     // set up, variables, and reset
|   |   └── components               // atomic, elemental, and molecular-level UI
|   |   └── layouts                  // grid, canned layouts, layout-based rules
|   |   └── shame                    // browser/UI hacks, and poorly-scoped overrides
|   |   └── utilities                // variables, helpers, shame + developer-based overrides
|   |   └── views                    // page/view specifics
|   |   └── main.scss                // main application compile
└── templates
|   └── ...                          // HTML-based templates
└── themes
|   └── [theme-name]                 // individual theme
|   |   └── static                   // individual theme overrides to static files
|   |   |   └── css
|   |   |   └── images
|   |   |   └── js
|   |   |   └── sass
|   |   |   └── vendor
|   |   |   └── vendor-extensions
|   |   └── templates                // individual theme overrides to template files
|   |    ...

File Naming

We adhere to the following conventions when naming:

• files should be named in all lowercase with - separating legible words (e.g. main-rtl.scss or view-courseware-notes.html);
• all files that are not called/rendered direcly should be prefixed with an underscore for easier understanding (e.g. _header-primary.html)
• all theme-based assets are contained within a [theme-name] directory who's static and template structure mirrors the major directories within the application;
• images that are not used directly in the content should be prefixed with their appropriate purpose (bg = background, ico = icon/symbol, logo = brand/logo)

---

Vendor Files

When possible, we do not:

• edit a vendor file directly or change a vendor's source code
• change a vendor file's name
• split specific vendor files that are bundled together (this means customizing folder paths when referencing vendor files)

Known/Chosen Vendor Files

We use the following Front End Development centric utilities and vendors to help render our UI:

• Bourbon (docs) - A set of utilities for writing SCSS
• Neat (docs) - A responsive-friendly grid framework based upon Bourbon.
• normalize - A common and basic CSS reset that makes cross-browser/agent rendering more consistent.
• JQuery - Basic utility for DOM manipulation and UI behavior
• Font Awesome - Vector-based icon font library

I don't recommend Font Awesome as a permanent solution to our vendor library as it contains hundreds of icons we don't and likely never will use. This takes up space. Instead, I propose we create a custom font with only the icons we need (that's manageable via a .json file) to save weight and load times. I've done this before with fontello.com (CR)

Other Front End Centric vendor packages used currently in the edx-platorm include:

• JQuery UI - Used for existing platform features (drag and drop, calendar/date pickers)
• AnnotatorJS - Used for LMS Student Notes

---

Git Etiquette

Never check production-ready files into a codebase's repository including:

• Sass sourcemaps
• compiled CSS files
• compressed assets (CSS and JavaScript files)
• local editor/project management files
• local cache-based files

All of these files should be added to either your local global .gitignore file or better yet the edX project's .gitignore file.