Frontend Guidelines

Best Practices

Write good code: Review these Frontend Guidelines to get a sense of the best practices and get a feel for how the code is structured. Play close attention to the Cross-Email Client Guidelines which will help you develop the most bullet-proof email as possible.

Don't write inline CSS: During development, don't torture yourself by using inlined CSS. Be sure you process it in an inliner right before you test the email though, as some email clients only accept inlined CSS.

Use well supported CSS: Wherever possible, use CSS that's well supported across email clients, particularly the ones that are in our Email Client Support chart. Campaign Monitor has a great chart that displays the CSS support across email clients.

Make it accessible: Be mindful of providing the Accessibility affordances.

Review the Cross-Email Client Guidelines: We have Cross-Email Client Guidelines that set you up for success. Refer to the Email Client Support chart to identify the top clients we support.

Upload images wisely: Ideally, upload images to the ESP that's housing the email. Alternatively, if you're using Mandrill or otherwise need a space to store images, you can upload them to S3. Ask Engineering for access or assistence. Use https for images to avoid any mixed content warnings.

Validate HTML: Use the process described below to validate the HTML. When working with often complicated email code full of nested tables, it's easy to forget a closing tag which can really mess up your layout in some email clients. Pass it through this tool to check for errors.

Compress the code: Use the process described below to compress the HTML and CSS. In an effort to get email size as small as possible, compress the HTML. Smaller emails mean they load faster and avoid being clipped by email clients when they surpass file size maximums (Gmail's max is 102KB). Luckily, image sizes aren't included in this- only the text, full URLs, and HTML is counted.

Test it: Use the process described below to check for broken links and other errors. Also, test it across email clients. Developing emails that render well across email clients is a tricky beast. Luckily, our templates have been thoroughly tested to ensure you're being set up for success. That being said, as emails are being tweaked there's always the chance that it could look amiss in a given browser on a certain OS. The goal with testing is to catch these before emails are sent out so that we can confidently send high quality, high performing, on-brand emails. Email on Acid is a handy tool for testing emails across email clients. Use the profile named "Treehouse Email Client Matrix" to test the email against the email clients defined in our Email Client Support chart.

Using the Template Builder

Setup

Directory Structure

  • email-style-guide/
    • src/: This is where all source code is stored. Add new templates and styles here.
      • sass/: This is where the Sass files for the email style guide classes are kept.
      • templates/: This is where the source code for the templates are kept.
    • dist/: This is where all code is built. "dist" is short for distribution. Running yarn build will generate CSS and HTML templates in this directory.
      • css/: Processed CSS gets output here.
      • templates/: Processed template code gets output here. This is where you snag the production ready code that's already compressed, inlined, and validated.
    • docs/: The docs directory is where the Bounce documentation is stored.
      • src/: This is where the Sass and JS that supports the Bounce documentation lives.
      • assets/: This is where all the style-guide documentation assets are stored. Running yarn build will generate CSS and JavaScript in this directory.
      • templates/: Running yarn build will output templates to docs/templates as well for previewing. In general you shouldn't add new templates here but instead add them under the src directory. If added here, they'll get overwritten in the build process.

Building Assets + Docs

Running yarn serve will automatically build assets when they change. To build everthing, use:

$ yarn build

Creating Templates

  • Add it: Add new templates to src/templates
  • Build it: Build email templates with: $ yarn build
  • Preview it: After you've added a template, you can preview it with Jekyll.
    • Start the server if you haven't done so already: $ yarn serve
    • Say you just added a template in: src/templates/b2b/newsletter-08-2017.html. Now open: http://localhost:4000/email-style-guide/templates/b2b/newsletter-08-2017.html and you should see a preview there.

Testing

While email client testing must be done in a tool such as Email on Acid, the build process does include some quality assurance checks. We use HTMLProofer to check the documentation site + templates for broken links, missing images, invalid html, etc. We currently run these HTMLProofer checks:

  • HtmlCheck: Checks to see whether your HTML markup is valid.
  • ImageCheck: Checks to see whether all your images have alt tags, whether your internal image references are not broken, whether external images are showing, and whether your images are HTTP
  • LinkCheck: Checks to see whether your internal links are working, whether your internal hash references (#linkToMe) are working, whether external links are working, whether your links are HTTPS, and whether CORS/SRI is enabled
  • ScriptCheck: Checks to see whether your internal script references are working, whether external scripts are loading, and whether CORS/SRI is enabled

To run it, make sure you have the dependencies by running $ bin/setup then run $ yarn build && yarn test. To test individual templates, run $ bin/test src/templates/example.html.

Tips for ensuring consistent rendering across email clients

  • Preventing Date Styling Overrides: Some email clients force dates to be blue, which can at best create an inconsistent link styling and at worse make the text illegable on colored backgrounds. The CSS below is included into the templates and prevents this re-styling from happening on specific email clients.
    • For iOS devices: a[x-apple-data-detectors=true] { color: inherit !important; text-decoration: inherit !important; } a[x-apple-data-detectors=true] { color: inherit !important; text-decoration: inherit !important; }
    • For Outlook.com: * [office365] .outlook-link span { color: #ffffff !important; border-bottom-width:0 !important; border-bottom-style:none !important; } .contextualExtensionHighlight, .ms-font-color-themePrimary, .ms-border-color-themePrimary { border-bottom-width:0 !important; border-bottom-style:none !important; }