Google Web Components Style Guide

This guide serves as an extension to the Google JavaScript Style Guide with additional style guidance around authoring Web Components, particuarly those in this element collection. It is targeted at Google engineers, but may be useful for others too :)

General conventions

• All elements should use seed-element as a starting point. This provides a clean base for authoring elements that are reusable. It includes a component page for documentation and a setup for unit-testing.
• Where possible try to follow the SRP (Single-responsibility principle) & first for elements you are authoring. “Do one thing and do it well”.
• Extend existing elements over re-implementing functionality yourself. Alternatively, reuse base components (e.g. <google-client-api>) in your own.
• Ensure your element, methods, events, attributes, and properties are well documented.
• Use @attribute, @property, @method, @event to document the API for your element.
• Ensure any styling hooks or accepted light DOM are documented in the element summary.
• Follow the Web Component best practices guide where possible.
• Ensure your elements are accessible from the get-go.
• In your bower.json, depend on a specific version of Polymer (e.g. "polymer": "Polymer/polymer#~0.4.0")

Naming

• Elements should contain a dash in their name (e.g <my-tabs> vs <tabs>), per the Custom Element specification,
• Google elements should be prefixed with “google” (e.g <google-sheets> vs <g-sheets>).
• Where multiple words are required for the name, they should be separated with a dash (e.g <google-street-view-pano> vs <google-streetviewpano>) for readability.
• Unless for private use, elements should use a unique name to avoid clashing with existing elements.

Attributes

• Published attributes should be camel-cased where multiple words are in use.
• Provide sensible default values as part of your API if values will be bound and displayed anywhere in your template. Default property values in attributes are null.
• Use @default and @required for parameters that either have a default value or are required.

Events

• Event names should have a prefix strongly related to the name of the element in use (e.g drive-upload-success vs upload-succeeded). This allows you to drop in multiple elements in the page without event namespacing clashing.
• It’s fine to simplify things a bit if your element name is complex, as long as the relationship is unambiguous (e.g., for a load event on a <google-client-api-loader> element, use google-client-api-load instead of google-client-api-loader-load).
• A unique event name should be fired for unique actions in your element that will be of interest to the outside world.
• Events should either end in verbs in the infinitive form (e.g. google-client-api-load) or nouns (e.g google-drive-upload-success).
• Use declarative event handlers over JS based (e.g. don't write addEventListener in your element code).

Variables

• Do not use $to prepend your own object properties and variables. Consider this style of naming reserved for use by Polymer and jQuery. Polymer allows you to use `$.within