Skip to content

UI / UX

Code writing and review guidelines

  • 4 spaces (not tabs) should be used for code indentation.
  • Semantic HTML5 markup was used.
  • Index of HTML5 elements where you can check how it is used correctly
  • How <h1> should be used in HTML5 (e.g. inside <section>)
  • Mobile-first approach was used.
  • Project-wide media query breakpoints were used.

  • If font-size is set on an element the line-height is also set.

    If the designer set a weird one (obviously too large or too small) because the text in the designs is in one line, then it should be set to 1.2 without any units. This is important because all of the text should also looks good in multiple lines.

  • Letter spacing is set by design and converted correctly from the Photoshop to CSS units.
    Convert Photoshop letter spacing to CSS em/px

  • When possible padding is used instead of the margin (margins can collapse).
  • For vertical spacing of the elements inside of the module/section the same property is used on all elements (e.g. padding-bottom) so that if an element is removed from the module the module should still look ok.
  • For styling the element the CSS classes are used instead of the element names (tags) so that there is no extra work if we ever need to change a tag to a <a> tag or an <h2> to a <p>. There are some exceptions for the elements that are often repeated and is unknown how many of them will exist on the live site with the CMS (e.g. .dropdown-menu > li > a in the Bootstrap’s dropdown menu or <p>’s inside the
    container).
  • IDs should not be used in the CSS so that there are no issues with the CSS specificity.
  • CSS selectors with huge specificity (e.g. deep nesting in Less/Sass) should not be used.

    When possible the new unique class should be added to the HTML element and its should not be nested in the Less/Sass file.

The exception is when we have to override an existing style from a 3rd party library.

  • !important should not be used. The exceptions are .is-state classes (e.g. .is-active) when the state needs to override the style of a more complex CSS selector.
    You won’t normally have two states that tend to affect the same set of styles applied to the same module, so specificity conflicts from using !important should be few and far between. Rather than overriding Bootstrap’s CSS rules with !important just change the default values with Less/Sass variables: http://getbootstrap.com/customize/#less-variables
  • Time written in the CSS should be in seconds and without the leading zero (e.g. transition: color .4s).
  • Prefixes should not be written in the CSS file when the project uses the Autoprefixer.
  • Properties in the shorthand border property should be written in “1px solid #000” order. The same goes for the box-shadow (color property last).
  • If there are no separate styles defined for :focus and :active states then they should have the same styles as :hover (e.g. to override the default Bootstrap module :focus state).
  • SUIT CSS naming conventions are used. Example:
<section class="vp-Message">
  <header class="vp-Message-header">
    <h1 class="vp-Message-heading">Final message title here</h1>
    <h2 class="vp-Message-subheading">Additional message</h1>
  </header>
  <div class="vp-Message-body">
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
  </div>
  <footer class="vp-Message-footer">
    <a class="vp-Button vp-Button--business" href="javascript:;">Try it free for business</a>
    <a class="vp-Button vp-Button--home" href="javascript:;">Try it free for home</a>
  </footer>
</section>
  • Use either descendant of modifier class, not both. It's harder to read.
  • Modifier class should be on the component and not the descendant (e.g. .vp-Resources--dataSheet .vp-Resources-header {}). When this is not possible with the current component a new sub-component should be added (e.g. .vp-ResourcesBox.vp-ResourcesBox--dataSheet .vp-ResourcesBox-header {})
  • Relative paths should be used (e.g. path/to/file and not /path/to/file) because we don’t know if the project will be hosted on the server's root folder or in a sub-folder.
  • When the Bootstrap’s Collapse component is used (or in general when the height() of the element dynamically changed) there should be no margin or padding on the element that is collapsing because that will cause a glitchy transition. The spacing should be added to the descendant elements.
    The spacing can also be mimicked with added a :before or :after on the element with something like {height: 29px; display: block; content: ''; visibility: hidden;}

  • For the inline list the display:flex (IE10+) should be used on the <ul> to avoid display:inline-block bug.

    Any other solution from the link is also permitted but then the list should be checked in multiple browsers if the gaps between the items are matching.

  • When using css transitions all the properties that will be transitioned should be listed rather than using the "all" value.

  • Touch areas (e.g. for close "X" icon) should be at least 48px wide (the absolute minimum is 32px). Code example how to do this for a smaller icon:

a {
  position:relative;
  &:after {
    content:'';
    position:absolute;
    top:-10px; bottom:-10px;
    left:-10px; right:-10px;
  }
}
TODO - Cleanup and integrate 
## Development instructions
We use gulp automation tool. It handles:

* browsersync
* less autocompile
* js and css minification
* js concatenation
* copying js, css, images from `/markup` to `/wordpress` folder

Check out `gulpfile.js` in root folder for more info.

### FrontEnd
If you need to make change of styles, add or change design graphics or change javascript code ALWAYS make the change in `/markup` folder first and use gulp task: `gulp build` to copy the changes to `/wordpress` folder. (CSS has to changed via the less files in markup/less folder as the build process uses them as the source from which to build)

#### Making markup changes (changes to HTML, CSS and JS that is used on the site!)
```sh
# 1. Run `serve` task and start making changes
$ gulp serve

# 2. If you made a CSS change run `gulp css-min` for subpages and/or `gulp home-css-min` for homepage
$ gulp css-min
$ gulp home-css-min

# 3. If you made a JS change run `gulp js-min` for subpages and/or `gulp home-js-min` for homepage
$ gulp js-min
$ gulp home-js-min

# 4. Once done run build task to build and copy all the changes to `/wordpress` folder
$ gulp build

### BackEnd
For changes on wordpress end (theme `.php` files or wordpress administration css, js files) you do not need to make any changes in `/markup` folder first.