Show More
Commit Description:
metatags: improve display syntax and add deprecated tag.
Commit Description:
metatags: improve display syntax and add deprecated tag.
File last commit:
Show/Diff file:
Action:
docs/contributing/frontend.rst | 153 lines | 3.8 KiB | text/x-rst | RstLexer |

Code style and structure guide for frontend work

About: Outline of frontend development practices.

Templates

  • Indent with 4 spaces in general.

  • Embedded Python code follows the same conventions as in the backend.

    A common problem is missed spaces around operators.

Grunt

We use Grunt to compile our JavaScript and LESS files. This is done automatically when you start an instance. If you are changing these files, however, it is recommended to amend --reload to the runserver command, or use grunt watch - the Gruntfile is located in the base directory. For more info on Grunt, see http://gruntjs.com/

LESS CSS

Style

  • Use 4 spaces instead of tabs.
  • Avoid !important; it is very often an indicator for a problem.

Structure

It is important that we maintain consistency in the LESS files so that things scale properly. CSS is organized using LESS and then compiled into a CSS file to be used in production. Find the class you need to change and change it there. Do not add overriding styles at the end of the file. The LESS file will be minified; use plenty of spacing and comments for readability.

These will be kept in auxillary LESS files to be imported (in this order) at the top:

  • fonts.less (font-face declarations)
  • mixins (place all LESS mixins here)
  • helpers (basic classes for hiding mobile elements, centering, etc)
  • variables (theme-specific colors, spacing, and fonts which might change later)

Sections of the primary LESS file are as follows. Add comments describing layout and modules.

//--- BASE ------------------//
        Very basic, sitewide styles.

//--- LAYOUT ------------------//
        Essential layout, ex. containers and wrappers.
        Do not put type styles in here.

//--- MODULES ------------------//
        Reusable sections, such as sidebars and menus.

//--- THEME ------------------//
        Theme styles, typography, etc.

Formatting rules

  • Each rule should be indented on a separate line (this is helpful for diff checking).

  • Use a space after each colon and a semicolon after each last rule.

  • Put a blank line between each class.

  • Nested classes should be listed after the parent class' rules, separated with a blank line, and indented.

  • Using the below as a guide, place each rule in order of its effect on content, layout, sizing, and last listing minor style changes such as font color and backgrounds. Not every possible rule is listed here; when adding new ones, judge where it should go in the list based on that hierarchy.

    .class {
            content
            list-style-type
            position
            float
            top
            right
            bottom
            left
            height
            max-height
            min-height
            width
            max-width
            min-width
            margin
            padding
            indent
            vertical-align
            text-align
            border
            border-radius
            font-size
            line-height
            font
            font-style
            font-variant
            font-weight
            color
            text-shadow
            background
            background-color
            box-shadow
            background-url
            background-position
            background-repeat
            background-cover
            transitions
            cursor
            pointer-events
    
            .nested-class {
                    position
                    background-color
    
                    &:hover {
                            color
                    }
            }
    }