HTML Best Practices

HTML best practices

When writing markup for Pugpig, we're run into a few things you should keep in mind. This page tries to document our best practices for Pugpig markup.

Issue Certain versions of Android don't show certain elements in the snapshots. Specially, the snapshot doesn't include fixed position elements or scrollable divs for API levels between HONEYCOMB and ICE_CREAM_SANDWICH inclusive, as documented here.

Solution Don't include fixed position elements or scrollable divs at snapshot time. Apply the required styles after snapshotting has completed.

Issue Certain versions of Android don't support scrolling overflow. Support for scrolling wasn't added until HONEYCOMB.

Solution Scroll using manually injected touch code. The application should inject any required code, because it will know if it's needed or not.

Issue You want to make your images tap to full-screen

Solution Read this



Issue You want phone numbers to not be styled by the webview

Solution Meta tag for disabling telephone number styling - <meta name=“format-detection” content=“telephone=no” />



Issue Android doesn't support font-face:local. When it sees the local attribute, the entire font-face is ignored. This makes it hard to embed fonts.

Solution The CSS must be rewritten on the fly. Usually this is done by the app. Fonts can be read from the Android asset directory using a specially constructed file URLs: file:///android_asset/path/to/font. Replace the local attribute with a standard url attribute.

Issue SVG fonts are slow.

Solution Don't use SVG fonts!

Issue Fonts not displaying at expected sizes on iPhone

Solution Set webkitTextSizeAdjust:100%; as a general style. You can read more here -

Issue You want to plug your mark-up into the font-resizing functionality of Pugpig

Solution iOS - Read this Android - see first issue in this section.



Issue Some pages are flashing when they load, or loading badly

Solution The first view of a page is actually a snapshot of the webview that is loading. Pugpig snapshots every page in your edition, in both orientations, which enables the smooth transition between pages. However if you have a dynamic page this can cause the snapshot and webview to become mismatched. In order to avoid this use the snapshot management functions.

Issue Having trouble with fixed position elements

Solution Positioned fixed is not a good idea, try to avoid it

Issue Having trouble with performance - flashing element

Solution Avoid transparency (margins, divs with no background color). Avoid overlapping divs. Try hardware acceleration in CSS -

Issue Having trouble with performance - flashing fonts

Solution iOS - Ensure your fonts are embedded in the app properly, and using the correct font-family names. More - LINK

Issue Javascript

Solution Defer as much JavaScript to be initialised by user interaction

WIP Front End Development Best Practices (to be formatted)

Useful Links



Browser Support - Compatibility tables for support of HTML5, CSS3, SVG and more in desktop and mobile browsers. - “you’ll find hype-free assessments of the major browsers’ CSS and JavaScript capabilities, as well as their adherence to theW3C standards.”


Responsive Design Testing - allows you to resize the browser viewport to test your responsive designs - similar to the previous link, Ish strays from the typical adaptive design route and instead promotes completely fluid layouts that do not rely on specific breakpoints


Articles - LukeW’s original article on why we should be building websites mobile first.


Browser Tips

Chrome 24 lets you use Source Maps with Sass in the Inspector sass –watch css:css –style expanded –debug-info


PugPig Specific Techniques


Avoid transparency (margins, divs with no background color)

Avoid overlapping divs

It is not advised, but using a CSS selector like so allows you to modify the page layout based on the font size that the user has selected: body[style*=“font-size: 112.5%”] It is not advisable as it is tighly coupled to the app container as these increments are not always the same.


Responsive Design Techniques

Responsive videos - container div with a height, set video to 100% height

HTML Best Practices



A DOCTYPE is one of the most essential pieces of any HTML document. It informs the browser (and other tools) which version of HTML you will be using. It will ensure that Standards mode is used to render the page and Internet Explorer will love you for it.


Validate your markup

Think you’re finished? Validate. Got a bug? Validate. Validated? Validate. Validating our HTML allows us to catch nasty errors before they cause problems further down the line. If you have an issue with your markup not displaying as expected it is quite possibly due to your HTML not being valid. Once you’ve got a valid HTML document, debugging becomes a far easier task. Info about automatically validating documents goes here


Avoid using ID’s in your markup

ID’s should only be used for JavaScript hooks rather than styling. Due to the specificity that an ID applies to a selector, they can be difficult to override using other selector combinations. The performance increase of using an ID is negligible. Another advantage of using this technique is that if we see an ID, we know straight away that its purpose is a hook for JavaScript.


JavaScript goes at the bottom

Loading JavaScript blocks the rendering of the page so all JavaScript should be placed at the bottom of the page. This will make the page appear to render faster even though the time required to finish running all of the scripts will not be different.


KISS (Keep it simple stupid)

Keep the number of DOM nodes (html tags) down to a bare minimum as per the Yahoo Best Practices for speeding up your website


HTML Styleguide


Lowercase properties, attributes and tags

Use lowercase for all attributes and tags e.g. <header class=”main-header”></header> not <HEADER class=”main-header”></header>


Always quote attributes

HTML5 does not require attribute values to be quoted, however if the value has a space in it does require the quotes therefore it makes sense to always quote them e.g. <header class=”main-header”></header> not <header class=main-header></header>


CSS/Sass Best Practices

Use lots of partials so everything is very modular and can be specifically imported into a pages main scss file

nth child

Media queries in sass

Mixin all the things

Hardware acceleration placeholder

Use a retina sass placeholder

Always compile with –style expanded except for when releasing, use –style compressed

Promote the SMACSS way of working, re read SMACSS to do this

Responsive Grid frameworks - Foundation (possibly conflicts with the SMACSS way)

Use a single sprite sheet for retina and a half sized version of the same sheet for normal resolution


Clearfix without using overflow hidden -

Normalize (a great reset) -

Simple CSS Transition tips

Creating shapes in CSS

Background attachment local

Rule of thumb is never style on something like, aside or article. Be more specific

Code smells

Dont use !important unless absolutely necessary, see Specificity Wars

Placeholders are awesome, use them. Mixins are for when you need parameters (they duplicate code unlike placeholders)

Create reusable selectors

We should really be using more vendor prefixes to simplify moving to new platforms, creating something for webkit shouldn’t be our only priority

SVG fonts are slow

Safari animation




Use a quick click

Dont use a jquery click event to trigger click events. Share events script that allows a click on desktop and a touchend on mobile. Discuss the fact that if the user scrolls whilst touching an element that this event is bound on, you need to cancel the event. Perhaps explain wasDragged method from WHICH.


Use event delegation

One cause for a page not feeling responsive is attaching too many event handlers to nodes on the page ( A way to avoid this is to use something called Event Delegation. Essentially what this means is the event is bound to the parent element of the element you want to fire events on, e.g. typically if we wanted to fire an event on every li using the following markup:

<ul id=”my-awesome-js-nav”> <li>Link 1</li> <li>Link 2</li> <li>Link 3</li> </ul>

Traditionally we would do something like the following, binding an event to every li element.

jQuery var links = $(‘#my-awesome-js-nav’).find(‘li’); links.on(‘click’, myAwesomeMethod);

Raw JS var links = document.querySelectorAll(‘#my-awesome-js-nav li’); links.addEventListener(‘click’, myAwesomeMethod);

Instead of doing this, we’re going to bind an event to the ul and then check that the element that was clicked was an li. jQuery has some sugar to let us do this very easily, without jQuery we need to do a little bit more work.

jQuery var nav = $(‘#my-awesome-js-nav’); nav.on(‘click’, ‘li’, myAwesomeMethod);

Raw JS

Concatenate and minify your scripts before releasing!

Share my ‘class’ implementation (maybe show it being used in Backbone)

Pub/Sub for communicating between modules

Unit tested modules that can be reused between projects

Push Jasmine as the unit testing framework

PhantomJS as headless webkit to run unit tests

Use a templating engine for handling HTML strings (if absolutely necessary as JavaScript is crap in webviews) - lodash being preferred

Avoid touching the DOM

No CSS in JavaScript, use classes to style things unless it must be dynamically set



Build Process

Automate all of the things, section about grunt / r.js / phantomjs

Things I need to look at:

Grunt - automate minifying, concatenation, sprite creation

Reusable modules (unit tested using jasmine)

Reusable mixins / placeholders / variables / sass templates

Example templates

Work out if I can load scripts asynchronously in a pugpig webview. If it is possible using requirejs it may effect my test runner choice


Test Runners

Testacular Buster


Unit testing frameworks

Buster Jasmine

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk