Google Web Components Style Guide
- 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")
- Elements should contain a dash in their name (e.g
<tabs>), per the Custom Element specification,
- Google elements should be prefixed with “google” (e.g
- Where multiple words are required for the name, they should be separated with a dash (e.g
<google-streetviewpano>) for readability.
- Unless for private use, elements should use a unique name to avoid clashing with existing elements.
- 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
@requiredfor parameters that either have a default value or are required.
- Event names should have a prefix strongly related to the name of the element in use (e.g
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
- 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
- Use declarative event handlers over JS based (e.g. don't write
addEventListenerin your element code).
- 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
this.$.*within script to access the content of element children.
- Define constants outside of the
Polymer()constructor, wrapped in an anonymous self-executing function.
- If you need to define private or static variables, wrap your script using standard techniques like anonymous self-calling functions.
- Methods should be camel-cased where multiple verbs/words are in use (e.g
<seed-element>has a setup using Mocha and Chai that should be adapted to exercise your own element’s functionality. Examples of existing tests written by the Polymer team can be found in core-tests.
- Assets such as icons, graphics and other forms of media should live inside an
assetsdirectory. One example of an element that does this is yt-video.
- Assets should be optimized (e.g using tools such as ImageOptim) to minimize the size of resources package consumers need to download.
- Where possible, use
on-clickto benefit from additional help provided for touch screens
- Avoid using the
<select>and other potentially problematic native elements documented in the FAQ.
- Avoid excluding the outer
<template>when attempting to use a conditional or repeat template
- Avoid binding to native attributes that can cause issues. See the Polymer data-binding docs for more information.
- Be careful when placing content inside the
<shadow>element. This will not render.
Note, that this section is mostly relevant to Google engineers working on elements and follows current requirements around open-source projects.