Web Pattern Library

Github Repo

Menu


Global styles

Global components


Template Structure


Bag, Wishlist, & Checkout

Home / Login

Marketing Modules

Product Listing & Detail

Size & Fit Guides

Personalization

My Account / History

Static pages


JavaScript Helpers

Tech Notes

Source Code & Directory Structure

All source files can be accessed at the github repository for this project (permission required).

At the root, the site code is divided into 4 folders:

Device & Browser Testing Guidelines

Since browser support for web technologies vary greatly, we organize our support strategy into multiple grades that balances broad access and development effort. Since we're using progressive enhancemnt principles, the site should work in wide range of browsers. The grade A browsers below represents the full list we will be actively testing our templates against on a daily basis. The B and C grades are expected to have varying levels of experience and are not be the focus of our development.

A Grade Browsers: Fully Supported

These browsers represent the "fully supported" tier where we seek to make the site look and behave as close to the designs as possible. Only log rendering issues for this grade. These browsers tend to be kept up-to-date with regular software updates so we specify that we will primarily test the latest version of each, although usually the A grade experience extends for many versions back.

B Grade Browsers: Limited Support

These browsers have known limitations and rendering issues that we will not spend time to debug or add additional code for workarounds due to their age and low usage. The site will largely look and behave correctly but with reduced visual fidelity (minor layout misalignment or overlaps, may be missing custom fonts or animations, native UI elements instead of custom are all expected and should not be logged as issues)

  • Opera 14 and older - Presto browser has some layout bugginess and doesn't load custom fonts
  • iOS Safari (iOS 7 and older) - minor visual issues like native selects instead of custom styled versions
  • FirefoxOS (latest) – default browser renders well, may have sluggish performance
  • Kindle Fire (Android 4.x fork) – small rendering issues, slow performance
  • Blackberry 10 - should render the page well, but may be sluggish

C Grade Browsers: Unsupported

These are non-supported browsers and are expected to have a very degraded experience because they lack basic CSS and JS support. We aim to make the core shopping and checkout actions possible via minimal styles and native HTML features but there may be challenges to shoppers using these browsers.

  • Internet Explorer 6/7/8 – No media query support so these will render as a narrow mobile-first page with no JS enhancements or SVGs, may have small functional issues that hinder use
  • Opera Mini - lacks JS and has poor CSS support, expect some layout issues but the core shopping flow should work
  • Android 2.x - poor CSS support and slow JS could make some pages difficult to use
  • Blackberry - all older versions of BB (esp. 4/5) will have trouble rendering the pages, may be difficult to navigate

Coding Standards

Filament Group’s code deliverables adhere to the following principles:

Core principles

  • Separate markup from presentation and behavior to simplify site development and maintenance, and ensure consistent brand and experience across all site pages. Clean markup—free of inline styles and JavaScript event handlers—is key to presenting a usable experience to the widest range of users. Inline style and event references require that the user’s environment to be CSS- and JavaScript-enabled in order to interact with the page; if either is unavailable, the user may encounter formatting or script errors. Move styles and scripts to external files.
  • Use well-structured, semantic markup to ensure proper rendering and accessibility. Semantic markup describes the content it formats, and as a result is easy to read and maintain—not least because it takes the guesswork out of editing code. (For example, a <p> always denotes a paragraph.) More importantly, in the absence of CSS and JavaScript, cleanly written semantic markup will still form a readable experience, and be accessible to all users.
  • Leverage CSS3 as much as possible to create rich interfaces with minimal need for images or additional markup. Rounded corners, drop shadows, text shadows, and gradients are all widely supported on mobile and desktop browsers at this stage so these are safe to use.

Markup guidelines

We occasionally use HTML5 elements where useful (particularly HTML5 input types and data attributes) and make sure we’re up to speed on the W3C’s latest recommendations.

All HTML markup loosely follows XHTML 1.0 rules for cleaner and more standardized code. (The HTML 5 DOCTYPE supports less rigorous markup than XHTML does, but we feel XHTML is a cleaner, more consistent format to follow.) So:

  • All tags are written in lowercase.
  • Tags are properly nested, and do not overlap:
    • correct: <p><a href="mypage.html">link text</a></p>
    • incorrect: <p><a href="mypage.html">link text</p></a>
  • All attributes are quoted with double quotes.
  • No spacer images, extra line breaks or non-breaking spaces are used for page formatting. With rare exceptions, inline styles are never used in page source.
  • Use the HTML5 doctype: <!DOCTYPE html> . The doctype identifies the set of syntax rules that apply to the page. Correct interpretation of the doctype depends on a couple of factors:
    • The doctype must be the first element on a page. There can be no preceding scripts, comment tags, or characters of any kind (including spaces).
    • Markup must be well-formed. Page markup must conform to identifiable HTML5 syntax rules for the browser to render the page in standards-compliant mode. Otherwise, the browser may render the page in an inconsistent way (also known as “quirks mode”) despite the doctype declaration.

CSS guidelines

  • Whenever possible CSS—not JavaScript—is used for interaction effects like navigation and link rollovers.
  • Relative font sizes are specified in the stylesheet with the unit em or rem to allow the user to set their own font size using browser controls, or to leverage custom controls we may provide in the interface.
  • Classes are used to identify groups of elements or components with the same purpose.
  • IDs are used to uniquely identify elements or components.
  • Class and ID names are written with dash separators, and derived from their element’s or component’s content or purpose, not from their appearance, which may change as the application is updated.
  • Place -o -prefixed CSS rules after -webkit rules because they are now implementing -webkit properties for many CSS rules.
  • We use { box-sizing: border-box } to apply a natural box layout model to all elements. Essentially, this uses the IE-style box model for all modern browsers that support this model so it’s now consistent and falls back when not understood in IE.
  • Follow Object-Oriented CSS (OOCSS) principles to re-use styles and be efficient. (For reference, see Nicole SUllivan’s OOCSS.)

JavaScript

In order to maintain clean code, JavaScript events are assigned to elements in an unobtrusive way, usually by event delegation. In general, we follow formatting conventions from Rick Waldron’s Principles of Writing Consistent, Idiomatic JavaScript.

Additionally JavaScript is organized using objects and restricting external event bindings to object method invocations with possible event manipulation. All direct DOM manipulation should take place inside an object method. We have the following example of a small checkbox/radio library.


$.fn.checkboxradio = function(){
  return this.each(function( index, element ){
    var cbr = new CheckboxRadio( element );

    cbr.$element.bind( "change init", function(){
      cbr.toggleCheck();
    });

    cbr.parent.bind( "click", function(){
      cbr.change();
    });
  });
};

Note that DOM manipulations and events triggered along with them are handled inside the methods of the CheckboxRadio object. It may be the case that some event specific functionality may/should live in these callbacks, but otherwise the object should contain most of the code.


var CheckboxRadio = function( element ){
  if( !element ){
    throw "Element required to initialize object";
  }

  this.$element = $( element );
  this.$parent = this.$element.parent();
};

CheckboxRadio.prototype.toggleCheck = function(){
  // ... DOM manipulation ...
};

CheckboxRadio.prototype.change = function( e ){
  // ... DOM manipulation ...
  // ... events triggered ...
};

The value of this approach is that it gives us a fighting chance at covering the CheckboxRadio methods with tests without adding a full integration suite. That is, one can simply include the object definition, instantiate, call methods, and tests the results on the test DOM fixtures.

Utilizing Images Responsively

In general, images should be referenced in a manner that ensures a device downloads as small an image as it needs for sharp display. Wherever possible, this codebase utilizes the standard srcset and sizes attributes to offer a variety of image source sizes that the browser can download and display depending on its screen size, pixel density, and even network conditions.

These attributes are supported well across many modern browsers, but some popular browsers do not support them so it is important to provide a reasonable fallback source via an img element's src attribute. Our recommendation for the dimensions of a fallback image source is to reference an image that matches the width that the image is displayed in the layout on a 1024x768 size viewport (at 1x resolution). This will ensure that browsers such as Internet Explorer 11, which has no support for these attributes, will still see a reasonably sharp image on an average size screen.

Examples

The product detail page’s product photos require some of the largest images displayed in any template on the site. The fallback size is 657 x 782px, and the srcset attribute offers a variety of sizes that may be more appropriate for supporting browsers to choose from.

The sizes attribute notes some sizes in which this image will be displayed at various viewport sizes, once the CSS has been applied. For example, it is displayed at 70em width when the window is wider than 75em, 60% of the viewport width when the viewport is between 48 and 75em, and 100% viewport width at all sizes smaller than that. This information helps the browser decide which source to fetch, depending on any factors it considers relevant (screen density, viewport size, network speed, user preferences about bandwidth, etc)


<img src="http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dwb68b84d6/images/2E0665.993.a.zoom.jpg?sw=657&sh=782"
  srcset="http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dwb68b84d6/images/2E0665.993.a.zoom.jpg?sw=400&sh=476 400w,
  http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dwb68b84d6/images/2E0665.993.a.zoom.jpg?sw=657&sh=782 657w,
  http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dw3b437538/images/2E0665.993.a.zoom.jpg?sw=980&sh=1166 980w,
  http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dw3b437538/images/2E0665.993.a.zoom.jpg?sw=1184&sh=1410 1184w,
  http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dw3b437538/images/2E0665.993.a.zoom.jpg?sw=1400&sh=1667 1400w,
  http://demandware.edgesuite.net/sits_pod33/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dw3b437538/images/2E0665.993.a.zoom.jpg?sw=1680&sh=2000 1680w"
  sizes="(min-width: 75em) 70em, (min-width: 48em) 60%, 100vw" alt="">

Accessibility Checklist

This project has goals of 508 and WCAG "AA" compliance. This is a checklist to follow while developing pages so that optimal accessibility is retained.

The following items are derived from the official Section 508 Checklist, the A11y Project , and WCAG 2.0.

Document Structure

  • Page title: page titles that describe topic or purpose
  • Skip Links: If repetitive navigation links are at the beginning of the source of the HTML page, can a user navigate via a link, the “skip link”, at the top of each page directly to the main content area?
    • Are these links tab-focusable and visible on focus for sighted keyboard users?
    • If a “skip link” is provided and it is hidden with CSS, is it available to users of assistive technology, e.g. not using the display:none method?
  • Headings: Are heading elements used to convey logical hierarchy and denote the beginning of each section of content?
  • Tab order: Is the tab order between elements logical and consistent with the normal and visual order of the page?
  • ARIA Landmarks ARIA Landmark Roles are helpful landmarks that can be used by AT to navigate a website.
    • header role="banner" - A region of the page that is site focused. Typically your global page header.
    • nav role="navigation": Contains navigational links.
    • main role="main": Focal content of document. Use only once.
    • article role="article": Represents an independent item of content. Use only once on outermost element of this type.
    • aside role="complementary": Supporting section related to the main content even when separated.
    • footer role="contentinfo": Contains information about the document (meta info, copyright, company info, etc).
    • form role="search": Add a search role to your primary search form.
  • Navigation Consisitency: navigation common to pages in a section should be located in a similar place in the document
  • Markup quality: In content implemented using markup languages, elements have complete start and end tags, elements are nested according to their specifications, elements do not contain duplicate attributes, and any IDs are unique, except where the specifications allow these features. (WCAG 2)

Non-text Content

  • Image Meaning and Alt text All image elements that convey meaning to the content should have proper alternative text descriptions in the HTML? This can be done by populating the alt attribute on the img tag, but that attribute can also be left intentionally blank if adjacent text explains the image's meaning adequately (thus preventing redundancy for assistive tech users). More on alt text
  • Image Maps: Generally, image maps should be avoided when at all possible. These tend to be problematic to cross-device access, even for sighted users.
  • Form buttons: An input element with a type of image should ideally not be used, but if it is, its value attribute should represent any visual meaning the image conveys.
  • Audio/Video: For any audio or video content, a full text transcript should be available in a convenient, adjacent location. Ideally, open or closed captions should be provided for all synchronized, live video or audio.
  • Multimedia Presentations: Equivalent alternatives for any multimedia presentation shall be synchronized with the presentation when possible, or at least provided as an alternate transcript if synchronization is not possible.
  • CAPTCHA: If CAPTCHA images are used to detect that a user is not a bot, an accessible alternative must be provided.
  • Decoration & Visual Formatting: Use of visual imagery for decorative purposes should not be presented to users of assistive technology.

Color and Contrast

  • Color Meaning: Particularly in infographics, information conveyed by color should be also conveyed by context, markup, graphic coding, contrast, or other means.
  • Contrast: Particularly for variations in text, such as link colors and text that overlays imagery, does a contrast ratio of at least 4.5:1 exist? Is a correct contrast ratio maintained when images are not available and alt text is shown?
  • Links: Are links distinguished from surrounding text with sufficient color contrast and is additional differentiation provided when the link receives focus, e.g. it becomes underlined?
  • Logos & Branding: These elements have no minimum contrast requirement.
  • Flickering: Page elements should not blink or flicker at an unhealthy rate, e.g. less than three flashes per second

User Preference

  • CSS Disabled: When CSS is disabled, is the document reasonably useful? Is all content accessible? Do form controls still work? Does it follow an order and hierarchy that is usable?
  • JavaScript Disabled: When JavaScript is disabled, is the document reasonably useful? Is all content accessible? Do form controls still work? Does it follow an order and hierarchy that is usable?
  • Text Resizing: Text should be able to be resized natively in the browser up to 200 percent without loss of content or functionality

Markup Semantics

  • Tables: Table elements should not be used for visual layout, and only be used for tabular content.
    • The summary attribute and thead and tbody elements should be used to clarify the table meaning and structure if needed
    • Every table should make use of th elements for headings of rows and columns.
  • Lang Attribute: Declaring a language attribute on the html element enables a screen reader to read out the text with correct pronunciation: <html lang="en">
  • Link Purpose: The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context
  • Consistency in function: Components that have the same functionality within a set of Web pages are identified consistently

Form Elements

  • Form usability: Are all cues for filling out the form available to users of assistive technology, e.g. mandatory fields, help boxes, error messages?
  • Fieldsets: Are logically-related groups of form elements identified with appropriate fieldset and legend elements? Or a descriptive ARIA role?
  • Placeholder Input text: placeholder attributes should be used to display example entry text, and not as a label for the input.
  • Form Errors: Do form error messages identify the error(s) to the user and describe them to the user in text?
  • Form Inputs: Form inputs should be properly associated with a label, either using a for attribute that references the input's id attribute value, or by placing the input inside the label.
  • Visible focus: Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible
  • Error Correction: Forms that cause legal or financial transactions to occur must either be reversible, checked for errors prior to submission, or confirmable prior to submission.

Device Interactivity

  • Keyboard Accessible: All content should be accessible to keyboard-only users.
  • Input Modes: Is content that is enabled via mouse pointer hover or click also available to other input mechanisms like keyboard tab focus and spacebar?
    • Is this content accessible to touch screens as well?
    • Are all controls usable to mouse, keyboard, and touch screen users? Even on devices that support one or many of these modes (eg, a touch screen device such as Android that also has a rollerball joystick).
  • Interactive Elements: Elements meant to receive user input should be naturally keyboard or mouse focusable, even if JavaScript is used to apply their behavior. For example, to apply click interactivity, choose a button or a element rather than a div, as they are naturally focusable and clickable.
  • Visually-hidden Content: Sometimes it makes sense to hide content and selectively display it when appropriate.
    • display:none is not exposed to the accessability tree. See how different methods of hiding things are supported. When using display:none, no other attributes are required. When elements are hidden but not set to display:none (for instance, hiding an element by turning off its height and opacity, to support css transition of states), add the html5 attribute of hidden. That tells screen readers that it is hidden, is semantic, and more terse than aria-hidden=true. When hiding elements via opacity and height, also add html5 hidden. Caveat: when using Filament’s shoestring functions (e.g. collapsible), those are already accessible, so leave as is.
  • Input variation: Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.

Time Limitations

  • Page expiration: If an authentication session expires, can the user re-authenticate and continue the activity without losing any data from the current page?
  • Shifting Content: Sometimes page content is changed based on events unrelated to the user, such as advancing carousel slides on a timer. Does the user have control over the timing of content changes?

External Content

  • iFrames: Ideally, iframe elements should be avoided. If they are needed, they should have a title attribute that adequately describes their purpose.

Misc

  • Page findability: More than one way is available to locate a Web page within a set of Web pages except where the Web Page is the result of, or a step in, a process.

Accessibility Tools

The following tools are helpful in maintaining accessibility during development: