Team SpeedWebsite Content Style Guide

Introduction

The following is a rough guideline on how to setup an accurate local build and make use of custom styles established in other projects built by Team Speed. Consult this HTML file's code-base for exact structure and commenting guidelines.

Who Should Use This Guide

The specific guidelines in this document are more specific to project development and content population. Other content contributors may benefit from specific sections.

A Few Notes on SmartEdit

Keep in mind SmartEdit doesn't function as a standard CMS (content management system) and you'll only be pushing portions of your HTML, as well as any <link> or <script> tags your content is reliant on. Please refer to smartedit-prepped.html to see how your HTML should be formatted when being dropped into SmartEdit.

At the time of this document's creation, the only languages supported by SmartEdit were HTML, CSS and JavaScript. Custom CSS and Javascript files are hosted on the Akamai server.

SmartEdit Best Practices

SmartEdit doesn't operate in the same manner as a traditional CMS. The following steps explain how to set up a new page and outline some best practices:

  1. All full-width, single-column pages use the Content page type and Content page template2 template.
  2. The Info tab can be a bit confusing. Here is what each field represents:
    • Name: What the page is called in the backend. Also appears in the site's breadcrumb navigation.
    • Page Label: The page URL. (Ex. /engagement-rings)
    • Page Title: Populates the page's HTML <title> tag.
    • Localized Content Page Description: Populates the page's meta description.
    • Localized Content Page Keywords: Populates the page's meta keywords. This field seems to get hung-up during the save process if the initial character count is high. Try inserting a few keywords at a time and saving each time.
  3. Switch the page to Advanced Edit.
  4. Add a Paragraph component to Section 1. This is located directly under the breadcrumb navigation. This is the only component that allows for HTML code entry.
    1. In the Paragraph Editor, select Source in the WYSIWYG. You can then paste your HTML in.
    2. Set Dimensions to type.dimensionvalue.one_cross_one.name.
    3. Set Position to the numerical order the component should appear.
    4. Choose a unique Name for your component.
  5. For best results, and to decrease the number of edits that need to be made for split-testing, consider breaking your build out into specific modules.
    • To create a new module, simply clone the one you just created and follow the steps listed above.
  6. Once the page is built, you'll need to sync the content to push it live. Keep in mind SmartEdit has no true staging environment. Once you hit sync, THE PAGE GOES LIVE. Use the local server and Akamai as needed for reviews. Don't sync content until a launch time has been set.
  7. The saving and syncing process can be slow, so wait and hard refresh as needed.

A Few Notes on the Akamai Server

For whatever reason, the Akamai server doesn't cycle automatically, so any and all files stored there will need to be replaced with a renamed file in the event of an edit.

Note: Auto-renaming and random query string generating scripts have been written to work around this, but have been ineffective. While annoying, manual renaming works. Consider uploading files once everything has been approved.

A Few Notes on the Main Container and Hero Section

All content on this page is wrapped in a <main> tag set to a max-width of 1920px – the largest statistically-relevant desktop screen resolution.

While the hero should always follow the design, keep in mind the shortest common desktop screen resolution is 768px. That makes the desktop fold about 700px tall. Please keep this in mind when designing, coding and testing responsively.

A Few Notes on CSS Naming Conventions

The basic elements below make use of a simple naming convention to avoid conflicts with CSS frameworks such as Bootstrap, or in this use case, an altered version of Bootstrap for which there is no existing documentation. This is why most classes in this framework are prefixed by custom. If you need to add additional overrides (provided they aren't obvious enough), please use the suggested prefix and make notations in your code for reference.

Sample Build Location

An example of a full local build can be found on the server here: Speed > 05 Kay Engagement > DEVELOP.

Reference index.html as a guide on how to set up a file for local testing. Reference smartedit-prepped.html to see how your HTML should be formatted before working in SmartEdit.

Note: After pushing a project live, please save a copy of your local build on the server in a DEVELOP folder.

Files Used For Local Testing

The following stylesheets and scripts are needed to create local builds that will transition to SmartEdit without issue:

Note: This guide is making use of Jared site files.

Page <head>

  1. [BRAND]-style-min.css (The site-specific hacked bootstrap file)
  2. External Font Site Reference (Loads site-specific Web fonts)
  3. [BRAND]-style-secondary.css (Has a handful of site-specific font rules)
  4. External Font Awesome 4.7 Reference (Loads Font Awesome 4.7 [Font Awesome Cheatsheet])
  5. style.css (Page-specific desktop styles)
  6. style-largescreens.css (1024px and greater media queries)
  7. style-mediumscreens.css (1024px to 600px media queries)
  8. style-smallscreens.css (600px and less media queries)

Note: There's a Webpack task runner to compile custom CSS if desired.

Page <script> (Placed after closing <main> tag)

  1. [BRAND]-bootstrap.js (The site-specific bootstrap JS file)
  2. Extrernal jQuery Reference (Needs to be called in SmartEdit if using jQuery)
  3. [PAGE]-functions.js (Custom jQuery/JavaScript)

Note: There is no Babel JavaScript compiler built into the Webpack file.

A Few Notes on the Webpack Task Runner

Webpack is used to compile and minify CSS files. This accomplishes a few different goals:

  • Eliminates the need to dump all CSS into SmartEdit, thereby making the code base cleaner
  • Reduces the number of server requests made by bundling files
  • Reduces the file size of the outputted CSS file through minification

If you're not familiar with creating or using task runners, don't worry – this isn't a necessary step. If you'd like to use the task runner, here is a quick step-by-step process.

Note: This is a very high-level list of instructions. There are plenty of quick tutorials online to explain steps you're not familiar with.

  1. Create a dist folder in your project. This is where the minified file will output.
  2. Create a js folder, then copy and paste the app.js file from a past project into this folder. It tells the task runner which files need to be compiled.
  3. Copy the package.json and webpack.config.js files from a past project, and put them in the same location as your index.html file.
  4. Open the terminal, navigate to folder containing the files listed in the previous step and run npm install. This will load in all the dependencies listed in package.json. (This step assumes you've installed Node.js on your machine.)
  5. Use npm run compile to start the task. It will watch for file changes and run each time you save.
  6. Check the dist folder for styles.min.css. Any issues during the bundling process will be logged in the terminal.

Main Subpage Styles and Guidelines (This is also an h2)

This a sample paragraph with a hyperlink. This is bold text. If you're making use of custom Web fonts, there are different weights for italicized text and bold italicized. To ensure accuracy in font rendering, consult the font-specific stylesheets listed above to find the exact font-family used on the site.

A horizontal rule is below.


Image Styles and Guidelines (This is also an h3)

Subpage PlaceholderThis is a paragraph with an image aligned to the right. Aligned images should be no wider than 40 percent of the parent container (Ex. If the parent container has a width of 1000px, an aligned image should never be wider than 400px).

There are a few different classes you can use for images. As an example, this image also has the custom-img-align-right, custom-img-style-border, custom-img-style-circle, custom-img-style-shadow and custom-mobile-kill classes.

  • custom-img-align-left: Floats the image to the left.
  • custom-img-align-right: Floats the image to the right.
  • custom-img-align-center: Centers an image.
  • custom-img-style-border: Adds a border you specify in the stylesheet to the image.
  • custom-img-style-circle: Rounds the image. For best results, use an image with an equal width and height.
  • custom-img-style-shadow: Adds a slight drop shadow you specify in the stylesheet to the image.
  • custom-img-style-kill: Removes any unique styling applied by other classes outside of the ones listed above.
  • custom-mobile-kill: Removes the image at a screen size of 700px.

Note: If a floated image doesn't have the mobile-kill class, it will take on the align-center properties at 700px.

To properly clear a floated image, you can add an empty div after all the floated content with a class of custom-clear. This method is a failsafe.

Below is an example of an standard subpage button. All standard buttons need to be wrapped in a div with a class of custom-btn-container. Buttons requires two classes on them: custom-btn and custom-btn-[COLOR].

[COLOR] is a placeholder. You can create as many color classes as you need for your project. The example below is has a secondary class of custom-btn-purple.

* This is sample disclaimer text. You just need to add the class "disclaimer" to the element you have text in.

List Examples

This is a sample paragraph.

  • This is an unordered list.
  • List items and other elements have been tested for worst-case scenarios.
  • Below is a nested unordered list.
    • Nested ordered list item.

This is a sample paragraph.

  1. This is an ordered list.
  2. List items and other elements have been tested for worst-case scenarios.
  3. Below is a nested ordered list.
    1. Nested ordered list item.

Using Accordion Menus

An accordion menu is below. It's possible to have more than one accordion system on a page by grouping each set inside of a div with the class accordion-container. Each set is comprised of two items – a trigger with the class of expand and an element with the class expanded-content. Please inspect the code to see the exact structure, or refer to the file in the GitHub repo.

Note: Each accordion trigger has an ADA-accessible description on the arrow icon.

Sample Accordion

This is an h4 with the class 'content-hero'

Use the class content-hero in situations where you need a header to have no margin or padding.

Using Multiple Accordions

To have multiple accordions on the same page, make sure each group of accordion items is inside of a div


If you want the first accordion item open, add the class expanded to the first heading. This is an example where that class is in place. It will only work on the first heading.

Sample Accordion With List

This is a sample accordion with a list inside of it.

  • This is an unordered list.
  • This is an unordered list.
  • This is an unordered list.

Sample Accordion With Image

Subpage Accordion PlaceholderThis is a sample accordion with a floated image inside of it. This particular image has the mobile-kill class, which we typically use on images that enhance, but aren't crucial to the text content.

Images aligned in accordions should be no wider than 40 percent of the expanded-content div.

Typically, these images hurt readability on devices as they break the flow between headers and text content.

This is also an example where a div with the class custom-clear follows the floated content. Otherwise, the image would break through the bottom of this container.

Embedding Responsive Videos

Embedded external videos use Vimeo and YouTube's "modest branding." To use responsive videos properly, follow these steps:

  1. The embed link used for a video should be formatted like this: https://www.youtube.com/embed/XQu8TTBmGhA (YouTube) or https://player.vimeo.com/video/87110435 (Vimeo)
  2. The bold portion of the link above is the video's unique code. This is the only part of the link above you need to replace if copying and pasting in a new video.
  3. All videos are in an iframe, which need to be placed in a div with the class of custom-video.

A fully-coded example is below. It's best to simply copy and paste the code and change the bolded section of the link above. You can find the unique code in the URL of the YouTube video's page.

SEO Best Practices

The following are some general guidelines to consider when creating SEO-friendly Web content.

General Content & Copy

  • Create User Profiles/Personas: Producing content to attract a general audience generally results in traffic from users who don't relate to the campaign. Personalized messaging tends to convert at a much higher clip, resulting in a higher-ranking page.
  • Create Keyword-heavy Content: Keywords refer to specific combinations of terms and phrases your users will likely input into search engines to find your page.
    • These are divided into short (usually one word) and long-tail (usually more than one).
    • Certain HTML tags have more weight than others. Make sure all heading tags (<h1> and <h2> tags, specifically) and <a> tags are keyword-rich.
    • A marketing team should be able to provide this data, but if not, try using Ubersuggest to do some lower-level keyword research.
  • Link Building: This will end up falling more into the developer's hands at the end of the day, but always strive to create internal links within content when possible. This not only helps the ranking of the pages you're linking to, but helps your page rank better as a referrer.
  • Content Length Matters: Keep in mind Web pages with longer, high-quality content get better search rankings because users tend to get information from a single reliable source. Pages need to have at least 300 words of live copy on them to be considered relevant.
  • Avoid Jargon: There's a point where something can be too clever. If a user doesn't immediately understand something, they're likely to leave the page. When someone leaves your page after a single-viewing session (meaning they don't progress to a conversion point), they bounce. A page's bounce rate is an important statistical metric that factors into page ranking. If the campaign is reliant on a user moving deeper within the site, then you want to strive for as low a bounce rate as possible.

Design & Development

  • Don't Make The User Think: This may be the Web's golden rule, and applies to every phase of Web design and development. Every experience is meant to drive a user somewhere, and they want to get there as quickly as possible. Here are a few questions to ask yourself to remove any subjectivity regarding functional elements and user experience.
    • Will the user understand what do in a split second?
    • Does this get the user to a conversion point in as few steps/clicks as possible?
  • Clean Code & Semantic Markup: Pages built in proper semantic order always rank better. The location and number of certain tags also play a role:
    • Pages should have one <h1> and it should be placed as high as possible in the markup.
    • Pages should have no more than six <h2> tags.
    • Since heading tags have SEO value, they shouldn't be placed in blocks of content used on other pages to avoid duplicate content penalties. If a call-to-action has a heading in the design, consider using a <span> instead.