Site Standards


To inform design and development and ensure that QA is done in regard to a common core Cantilever standard of quality, we have created this document to outline what we and our clients expect of a Cantilever product.

Different projects will have different requirements in various areas. An internal app, for instance, must be incredibly fast, but doesn’t require any SEO attention. A blog, meanwhile, doesn’t need much visual polish, but SEO is imperative. The documentation for each project should outline our and the client’s expectations within each category.

Requirements Matrix

All markup should be clean, semantic, and readable All media should include text fallbacks Interactive component states should be maintained using ARIA tags, not classes Avoid accessibility antipatterns like turning off focus states, disallowing text selection, JS-only rendering, etc. Ensure that design work is accessible (high contrast, sufficient text size)
Meet or exceed the requirements of our Accessibility checklist:
Meets or exceeds checklist criteria, including select AAA standards.
Ensure all user-facing pages load in under 3 seconds on prod, except for extreme circumstances.
Ensure that user-facing pages load in under 2 seconds on prod, except for special cases Avoid serving resources on a page that are not needed for that specific page. For example, do not load homepage-specific scripts on pages other than the homepage. Use Cloudflare or another CDN for frontend asset delivery Minify all static assets through Cloudflare or locally if using a separate CDN Avoid including any unused CSS rules in final stylesheets delivered to clients (cough tailwind cough) Implement basic backend caching. Use "defer" for scripts. Load non-required scripts (ex. Twitter Pixel) deliberately late in the pageload order so that they do not interrupt the user experience
Configure expires headers and etags Trim and minify markup Implement a Lazyload technique for iframes (Ensure this is not noticible for the user) Utilize hardware acceleration to ensure animations are smooth Implement other basic jank-free techniques
Implement advanced jank-free techniques Strategically load font files asynchronously (allow FOUC, or hide content) Implement an SVG sprite instead of serving them in markup Implement object caching or other pinpoint caching methods (be careful to avoid too much caching) Implement Cloudflare or other edge distribution for markup
Server setup is going to dictate much of these measures. This assumes we are using our own server. Strong passwords when passwords are used. SSH-only webserver access. Avoid using root users on webservers. Sanitize user input. HTTPS throughout the request chain Implement Cloudflare Ensure there is a plan in place to keep servers patched and safe over time (even if we are not going to do maintenance work) Avoid sending client passwords by email. Invite to 1pass. Implement two-factor auth all the time
Ensure basic firewall is in place (fail2ban) Hide system files below web root Avoid using 777 permissions Log and monitor login attempts
Disallow remote access to database Change admin passwords on a timed interval Implement server monitoring software to alert us of unauthorized requests
Do not use public DNS
Avoid all 'black hat' SEO practices, such as keyword stuffing, dark user patterns, unneccesary linking, redirecting legitimate site errors, domain spoofing, etc. All SERP identifiable pages should include: title tag, meta description, og:url, og:author, og:site-author, og:image Pages that should not be identifiable by SERP should use robots.txt exclusions to prevent them from being crawled. Core page content should always initially load with the DOM. Shadow DOM elements should never be relied on for SEO values. Do not use the "keywords" meta tag. All links, including those in content, use https protocol (when available) All images should use alt text and title tags. Clean, semantic markup Clear titles for all pages Meta descriptions for all pages Clear H1 on all pages Sitemap set up and submitted to webmaster tools Standard robots.txt for relevant backend system Robot-friendly backup content for JS-powered features Basic sitemap
Minimize javascript usage to what cannot be tackled in native HTML. Google delays the rendering reading of JS content, which has a big impact on JAMstack sites in particular, and unnessary javascript bloats the site load speeds and creates unneccesary burden on the user's browser. Avoid redirect chains. Try to provide the shortest (ideally 0) redirect paths from old content to new. Consider changes in URL structure carefully. Provide Alt text for all media content. Avoid duplicate content. Use relational links, canonical links, and simplify the sitemap to avoid this issue. Pagination URLs use canonical links, in addition to "prev" and "next" identifiers.
Nuanced sitemap including pinpoint priority values JSON page representation Strategic use of nofollow for pages we want to exclude
Avoid text spilling out of containers Avoid element collisions at awkward responsive sizes Avoid pixelated/stretched images Use SVG for icons and vector graphics
Ensure that webkit font smoothing is set to "antialiased", but not for reversed text Ensure consistency between colors used. Try not to use close but non-matching colors Ensure that retina screens receive higher-res imagery Ensure that hover and touch "down" states are present. Should be simple and helpful. Create smooth, simple transitions for animating elements
Add custom shadows to modify font hinting for particular cases
All files need to be organized logically into folders that represent different features or code types. Code must be straightforward and easy to follow. Code must include basic comments All code must be in version control and managed with the Git Flow methodology. Project should have a file with local installation instructions
Strong comment coverage across most frequently-used files All changes should be reviewed by another team member through an MR workflow CSS and JS should be linted automatically
Unit testing Automated CI
Auto-generating documentation
Specific browser required for client
Latest Chrome (Mac/Win), Latest FF (Mac/Win), Latest Edge (Win), Latest Safari (Mac), Latest iOS safari (iPhone SE, 350px screen-size, and above), Latest Android Chrome. Non-bleeding-edge versions of same browsers should be supported so long as they support all features used heavily by the site.
IE11, by specific request of the client
Other specialty browsers
Project should include a documented, straightforward build process that will run on most machines without many changes. Use standard tools that most people have. Build process should cover the basics of working on the site. Build process must take under 3 seconds to run on a standard machine.
Build process includes linting, deployment, or other helper functionality
Build process integrates automated testing
Build process uses custom-coded steps in a script or extension that perform advanced functionality required by the specific project
Images should be responsive, with at least three different size variants available for most images. Images must have alt text and should likely have title tags.
Images are lazy-loaded. Images are served in next-gen formats when supported by the browser. Images should be stored on external storage like S3 so they can be more easily shared between environments.
Images should be served with an advanced script such as Imgix.js to ensure that they are loaded at very precise sizes for each user’s machine.

Design Fidelity

For projects with design comps, we always expect that any final comps are obeyed. In all projects there are grey areas, since comps cannot be responsive, and cannot possibly display all application states, so frontend devs are expected to use good judgment in extending the design team’s intent throughout the full site experience. The exceptions are when:

  • There seems to be a mistake in the comp. In this case, clarify the mistake with the design team and proceed with the way it should be.
  • The design is inconsistent in some regard (ex. two blog posts have different font sizes), making it harder to modularize code. In this case, speak with the design team about your concern and validate with them that it’s okay to consolidate or modify styles before doing so.
  • The frontend team sees an opportunity to create a cleaner codebase or improved user experience by modifying the design. Sometimes in their zeal designers create impractical solutions that can be implemented much faster if tweaked. All team members should be able to "stop the assembly line" and flag concerns with one of our products. In this case, bring up the concern with the design team and project manager, and if a modification is sensible, we’ll do it.

Other than that, please pay very close attention to detail in frontend work. Comparing the comp to your frontend at the same screen size, any differences should stem from one of the above reasons.