-
Notifications
You must be signed in to change notification settings - Fork 39
Styleguide: General
Welcome to the edX General Front End Styleguide. This document is meant to be referenced alongside the following more detailed styleguides:
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).
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
| | ...
We adhere to the following conventions when naming:
- files should be named in all lowercase with
-separating legible words (e.g.main-rtl.scssorview-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)
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)
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
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
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.