Styleguide: General

General

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

• General Front End Styleguide
• Accessibility Styleguide
• HTML Styleguide
• Forms Styleguide
• Sass & CSS Styleguide
• JavaScript Styleguide

---

In general, edX styling should adhere to:

• four (4) spaces for indentation (no tabs);
• HTML files should be named in all lowercase with _ separating legible words (e.g. footer_global.html)
• Sass/CSS files should be named in all lowercase with - separating legible words (e.g. courseware-main.scss)
• 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.

Note: Currently in our edX-related Projects and Applications compiled CSS files are often not checked into git repositories and are generated at run/build time of the application.

Note: Theming overrides and customization are currently being architected to be outside of our core application repos. While their structure needs to mimmic that of the applications they relate to, they can be managed separately and referenced from configuration.

[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
• Susy (docs) - A responsive-friendly grid-math framework.
• Breakpoint (docs) - A breakpoint/media query management tool.
• normalize - A common and basic CSS reset that makes cross-browser/agent rendering more consistent.
• JQuery - Basic utility for DOM manipulation and UI behavior

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.