Cloud Construct
Front-End Code Standards

1. Readability and ease of understanding code across all concerns
• HTML, CSS and JS. Always name objects/vars/files with clear, meaningful strings.
• Be verbose and comment a LOT—let minification in the build process shrink build output to performant.
• Drop TODO's liberally in all code.
• Sign comments whenever possible for reference/trail.
• Front-end source code should be UNDERSTANDABLE above all else. If you don't adhere to popular conventions for structure of code, at least create clear conventions in a project, and stick with them consistently across the project.
2. Organization of source files and build output into clear structure, that matches architecture of a web application or website architecture.
3. Adherence to the best practices outlined in this document, so that teams are sync'd and development is faster due to common practices.
4. Use of these basic principles across any technology stack—the basics are valid anywhere.

Assets

Location of calls to assets in markup, for page load performance: follow HTML5 boilerplate standards for placement of elements that call assets.

CDN of Assets

Delivery by CDN should always be utilized to speed loading of assets. Most Cloud projects have all assets delivered by CDN. Make a smart choice on whether popular libraries like jQuery and Bootstrap should be loaded separately via popular CDN, to try to take advantage of browser caching. This may be a moot point for some JS frameworks that are opinionated about how they bundle assets. Just be mindful of what is going on in your project.

Limit HTTP Requests

Always attempt to limit http request count for any given page, by making smart decisions

Utilize image sprites or inline, encoded images appropriately

We want to limit HTTP requests needed for calling in image files. For small images like icons or logos, consider inline base-64 encoded data URI's for images in CSS or markup. Or consider using an image sprite for consolidating many images required in an application interface or website pages. Just don't let a page have many separate calls to load images to the page unless there's a good reason, like programmatically injected images or large images, or images that you WANT to be returned in SE results.

• We should utilize sprites at the least, for anything that’s not content imagery—all icons, page design elements and concerns that are not actual content imagery should probably be served up as base64-encoded SVG or PNG data-uri's, inline in markup or in CSS.
• If icons abound, we are probably dealing with visual design based on an icon font, so include it once and then utilize it for icons all over the place (think FontAwesome, SymbolSet, Google Material Design icons).

Follow WCAG2 guidelines

We should always deliver code to meet WCAG 2 requirements for accessibility at Level A. Ideally we should strive to meet Level AA, as well, and Level AAA as project agreements allow.

This starts with the basics:

• Always write semantic markup that adheres to a meaningful document structure, and cut markup to only that which is truly needed in order to accomplish this goal and allow for correct visual styling. See best practices in the HTML section.
• Make all functionality available from a keyboard
• Tab order controlled
• Use controls (and vet third-party ones) with keyboard accessibility
• Prefer styling native controls over using JS-based adaptations, or use methods that retain native controls for machine-understandability while presenting visually different appearance.
• Leverage ARIA attributes to make generic elements have meaning as needed, and to allow accessibility of JS-based interactive, for screen readers. Look for ARIA in third-party tools leveraged for sites.
• Note ARIA's utilization as described in the WCAG guidelines.
• Validate markup to find those missing alt tags, etc...

• Write valid, semantic markup that conveys meaning
• Make sure the site is crawlable when necessary
• Make sure that Googlebot can “see” all the site's pages
• Make sure Googlebot can access all content and links completely
• Make sure Googlebot can access all of my page resources
• Basically, use robots.txt and sitemap.xml files per Google's recommendation, to tell the crawler what to do.

File Size

Appropriate compression-to-quality ratio to optimize file size, for delivery in less-than-ideal wireless networks circumstances—aim to make mobile experience fast.

Try to keep file sizes for images as low as possible given the above and balancing quality with speed. Think about trying to keep banner images in the 150-250KB range at 72dpi, unless you are optimizing for Retina/higher-density screens and/or large monitors.

Retina-Ready Images

client/project-specific utilization of Retina-ready images—we don't always do it, but if we do make sure you are following some accepted best practices for doing so. Start with Chris Coyier's advice: https://css-tricks.com/snippets/css/retina-display-media-query/

Utilize image sprites or inline, encoded images appropriately

We want to limit HTTP requests needed for calling in image files. For small images like icons or logos, consider inline base-64 encoded data URI's for images in CSS or markup. Or consider using an image sprite for consolidating many images required in an application interface or website pages. Just don't let a page have many separate calls to load images to the page unless there's a good reason, like programmatically injected images or large images, or images that you WANT to be returned in SE results.

• Write valid HTML5 and try to validate it if any doubt—great way to catch required attributes omitted or other issues that could adversely affect page crawlability/ranking or accessibility. *can test here: https://validator.w3.org/#validate_by_uri
• Indentation - Use of 4 space tabs not 2, for readability and standard formatting
• Semantic, well-structured HTML5 markup (see the Semantic Markup area
• Pay attention to both what elements are being used and whether they match the W3C's spec'd purpose
• Take full advantage of semantic HTML5 elements (section, article, aside, definition lists, and ordered/unordered lists, menu, nav, header, footer, etc...) to create a structured document, easily navigable by humans of any physical capability and robots as well (test with “HTML5 Outliner” browser add-on - https://chrome.google.com/webstore/detail/html5-outliner/afoibpobokebhgfnknfndkgemglggomo?hl=en)
• Minimalist — use as few elements as possible to accomplish a layout, always default to placing and positioning actual semantic elements instead of wrapper divs, etc, unless a rare design ask makes that impossible.
• ID's vs class attributes for referencing DOM elements is the fastest way, by far, to look up a single element for attaching interactive behaviors, so consider that when you're writing an element to be addressed by JS scripting outside of a SPA like Angular or the like.
• Write classnames to elements you know will be addressed with CSS using BEM syntax (see the UI Styling area)

Definition

Semantic markup is HTML code that leverages defined element types and meaningful structure, in order to present an HTML Document that is understandable in structure and content without visual decoration. It is a well-structured, hierarchical document of well-labeled content and/or tools.

1. Semantic markup requires that HTML elements be used according to their intended purpose.
2. Semantic markup requires the separation of content and presentation.

When writing semantic markup, we use HTML tags to tell browsers something about the contents of the element. In semantic markup, tags are no longer just a way to get content to show up on a web page in a human-readable format. The tags themselves become a way to tell a machine (whether a browser, a computer, a smartphone, or another smart device) something about the meaning of the content. To write semantic markup, we must use HTML tags correctly so that our markup is both human-readable and machine-readable.

From https://html.com/semantic-markup/

Semantic HTML Elements

A semantic element clearly describes its content to human and machine visitors, and developers alike.

Examples of non-semantic elements: <div> and <span>—tell nothing about their content.

Examples of semantic elements: <form>, <table>, <article>, <aside>, <details>, <figcaption>, <figure>, <footer>, <header>, <main>, <mark>, <menu>, <nav>, <section>, <summary>, <time>, <dl>, <ul>, <ol>, etc.—much more revealing of their purpose.

• Bootstrap — we almost always use it, but make a smart decision. we don't HAVE to use it. (Current version - 4)
• Limit framework assets to custom builds that only include the exact modules needed.
• Start this way at the scaffolding of a project by beginning with a minimal build of bootstrap jquery, etc, then BUILD on it as is required during the unfolding of the front-end build.
• Better to start clean and build than try to weed out what is not needed after a kitchen-sink start.
• Always think about utilizing frameworks to speed development, but temper if wise with performance concerns.

• Again, readability and understandability
• Attention to selector complexity — keep selectors light via BEM conventions and limiting nesting in SASS to ensure light selectors in the browser
• ALWAYS utilize BEM basics for creating CSS classes
• Always target CLASSES and not object ID's for styling
• Use an “order-by-type” methodology as follows (order of the actual properties within the grouping isn't as important)
• Layout Properties (position, float, clear, display, overflow, z-index)
• Box Model Properties (width, height, margin, padding)
• Visual Properties (color, background, border, box-shadow)
• Typography Properties (font-size, font-family, text-align, text-transform)
• Misc Properties (cursor, animations)

code snippet

CSS/SCSS/LESS

.selector {
    // Layout Properties
    position:
    float:
    display:
    overflow(y, x):
    z-index:
    top:
    left:
    bottom:
    right:
    clear:
    flex(basis, direction, flow, grow, shrink, wrap):
    align(content, items, self):
    justify-content:
    order:
    columns:
                                                
    // Box Model Properties
    width(max, min):
    height(max, min):
    margin(top, right, bottom, left):
    padding(top, right, bottom, left):
                                                
    // Visual Properties
    color:
    background(image, size, position, color):
    border(top, right, bottom, left, width, style, color):
    border-radius(top, right, bottom, left):
    border-spacing:
    border-collapse:
    box-shadow:
    visibility:
    vertical-align:
                                            
    // Type Properties
    font-size:
    font-family:
    font-weight:
    font-style:
    text-align:
    text-transform:
    text-shadow:
    text-decoration:
    line-height:
    letter-spacing:
    white-space:
    word-wrap:
    word-break:
    word-spacing:
    list-style-type:
                                                
    // Misc Properties
    cursor:
    @keyframes:
    animation:
    animation-delay:
    animation-direction:
    animation-duration:
    animation-name:
    transform(origin, style):
    transition(property, duration, timing-function, delay):
    content:
    outline(color, offset, style, width):
    pointer-events:
}
                                

SASS or LESS, our go-to CSS pre-processors

We prefer SASS or LESS for their compatability with standard CSS syntax, and ease of use.

Be Mindful of Output

Some operations that may lead to conveniences in your SASS source code cause bloat in CSS output. When you use mixins or nest rules deeply, you can end up with bloat that could be eliminated by utilizing BEM naming conventions, keeping nesting of selectors light, and by using classes to decorate similar elements directly, instead of including mixins as sub-rules of rule definitions in the source code to share styling across many elements. Sometimes you have to have redundant output, but be mindful of what your SCSS is spitting out.

Vendor Prefixes

We should use auto-prefixer as a rule, to handle deprecation of vendor prefixes.

Inline Styling

Don't ever do it unless you have a dynamic UI component adding styles to an element on the fly that CAN'T be put into a dynamically added rule that resides fully in a stylesheet

Comments

Use of comments to separate Sections and Parts—again, understandability and verbose commenting as an overarching theme

For one-off interactive functionality outside of a framework like Angular, jQuery is super useful. But some things to keep in mind:

• Go easy on the creation of jquery objects, each $(...) brings a lot of overhead with it. Create an object related to your widget and then use jQuery's find or children methods to select child elements of that object and deal with them.
• If you can, just use vanilla javascript to grab your elements and change their properties directly without jQuery. For a lot of things it is not at all harder.

We should be architecting all of our code concerns in as modular fashion as possible. Best practices for modular application development should be followed in our use of SASS and templates.

• Keep CSS modularized into rules-per-area, or rules-per-component. Locating these small files either with their template concerns or in a mirrored structure to that of the templates makes things easy to deal with. A well-organized structure of well-titled directories with small, modularized CSS concerns and related templates inside is an example of a useful structure that we should leverage.
• Modular concerns should live in a single location in the architecture and be namespaced/encapsulated from conflict with outside concerns—both for CSS and JS concerns.

• Gulp is our jam
• Take a look at the source code for this standards doc, and see how gulp builds it and serves it up, really easily.
• Learn enough gulp to be able to spin up a server and compile a simple architecture of CSS, JS and HTML into output to the browser—super useful for crafting living style guides, things like this. Exploring layouts and techniques.

Cloud Construct is a Boston-based web design and development firm that builds web applications, designs responsive and mobile-optimized websites, and creates software solutions that enable companies to do more, faster.

Design

We align user requirements and business objectives into user experience and visual design, and create compelling design across all digital interfaces.

Architect

Whether working on a new site or updating an existing one, our approach is to build smart the first time, with a structure that supports growth and future enhancements with ease.

Build

The development team draws on years of experience and stays up-to-date on the latest technologies. Our expertise is in engineering site features and functionality, and in creating structures that will provide long-term stability and security.