Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The Gold Standard Checklist for Web Components
This is a working draft of a checklist to define a "gold standard" for web components that aspire to be as predictable, flexible, reliable, and useful as the standard HTML elements. The fundamental premise of this list is that it should not only be possible to attain that standard; people creating web components for general consumption should aim to meet that standard. These items are focused on designing good components; there are many other good principles for designing good user interfaces at the page or application level which are not listed here.
This list attempts to enumerate criteria for a component to meet that gold standard. This is currently just an early rough draft. If you see something that can be improved or corrected, please file an issue or submit a pull request against this wiki.
✓ Expressed Dependencies — Does the component import or otherwise load all of its own dependencies?
✓ Load Order Independence — Can you load the component at any point?
✓ Relative Paths — Are all paths relative to required resources (images, etc.) relative to the component source?
✓ Plain Tag — Can you instantiate the component with just a plain tag (
✓ Parent/Child Independence — Can you use the component inside any type of parent element, or with any type of child elements?
✓ Meaningful Structure — Does the component's DOM structure reflect the meaningful relationship between elements, such that those relationships are clear to a user relying on an assistive device? Accessibility
✓ Local Effects — Does the component limit its effects to itself (or a designated target element)?
✓ Detached Instantiation — Can the component be instantiated without being part of the document?
✓ Detachment — If the component is detached, does it stop listening to page events, and generally suspend non-essential tasks?
✓ Reattachment — Can a detached component be added back to the page?
✓ Children Visible — If the component is visible and given an initial set of children, are those children visible without any attributes, methods, event handlers, or styles required?
✓ Content Assignment — Can you place a
<slot> element inside a component instance and have the component treat the assigned content as if it were directly inside the component?
✓ Content Changes — Will the component respond to runtime changes in its content (including distributed content)?
✓ Child Independence — Can you use the component with a wide range of child element types?
✓ Auxiliary Content — Does the component permit the use of child elements that perform auxiliary functions?
✓ Back-End Independence — Can the component retrieve its content from a variety of a back-end services?
✓ Presentable — If the component is instantiated with no explicit styling, is it reasonably attractive, such that someone could feel comfortable presenting it as is?
✓ Generic Styling — Generally speaking, is the component’s default appearance straightforward and subdued?
✓ Informational Animation — Does the component’s default styling only use animation to communicate visually what is happening, rather than for purely artistic effects?
✓ Default Font — By default, does the component use the inherited font face, size, style, and weight?
✓ Default Colors — By default, does the component make use of the inherited forecolor and backcolor?
✓ Size to Content — Does the component automatically size itself to contain its content by default?
✓ Stretch to Fit — If you stretch the component (e.g., with absolute positioning or CSS flex), do its elements appropriately stretch as well?
✓ Automatic Positioning — Does the component automatically calculate positions for its elements?
✓ Child Positioning — Can child elements be positioned relative to their container within the component?
✓ Responsive — Does the component scale well to standard mobile, tablet, and desktop screen sizes?
✓ Style Recalc — Can you apply styles to a component instance even after it’s attached to the document?
✓ Size Recalc — If the component manually positions any subelements relative to its own size, does it appropriately recalc these positions when its own size changes?
✓ Member Order Independence — Can you set or invoke the component’s attributes, properties, and methods in any order?
✓ Member Combinations — Can you generally use all the component’s attributes, properties, and methods in any combination?
✓ Member Stability — If you change a component property or contents, then immediately get that property or contents, do you generally get the same result back?
✓ Required Properties — Does the component avoid requiring properties to be set unless absolutely necessary?
✓ Exposed Methods — Can you programmatically trigger all of the component’s key functionality through methods, rather than relying on user interaction?
✓ Exposed Events — Does the component raise events for all key points in its use?
✓ Property Change Events — Does the component raise property change events when — and only when — properties change in response to internal component activity?
✓ Documented API — Does the component document its public API?
✓ Computational Performance — Generally speaking, does the component perform its core functions reasonably quickly?
✓ Network Performance — If the component uses the network, does it do so efficiently?
✓ Render Performance — Is the component quick to get pixels on the screen when first loading and when updating?
✓ Vector Graphics — Where possible and appropriate, are the component’s graphics in a scalable vector form?
✓ Progress Feedback — For long operations, can the component provide appropriate feedback?
✓ Localizable Strings — Can text presented by the component be replaced for use in other languages?
✓ Date+Time Format — If the component accepts or renders dates and/or times, can you change the date/time format?
✓ Currency Format — If the component accepts or renders currency amounts, can you change the currency format?
✓ Right-to-Left — Can the component be configured to flip its presentation for use in right-to-left languages like Arabic and Hebrew?
✓ Base Class — If the component is a special case of another component, does it appropriately subclass from (or at least compose an instance of) that base class?
✓ Composition — Does the component appropriately delegate responsibilities to existing standard components when possible?
✓ Subclassable — Is the component subclassable?
✓ Overridable Methods — Does the component provide internal methods for key functionality, such that a subclass can override those methods to refine their behavior?
✓ Purpose Statement — Does the component’s header comment begin with a short (ideally, single sentence) statement of the component’s purpose?
✓ Code Style Guide — Does the source code comply with a standard source code style guide?
✓ Open License — If the component presents itself as open source, has it been assigned a standard form of a common open source license?
✓ Clean Console — Does the component avoid writing to the debug console unless specifically requested to do so?
✓ Prefixed Name — Does the component have a name prefixed with a project name, element collection name, organization, or something with semantic meaning?
The checklist items marked with the person icon are particularly important for universal accessibility. These items not only allow users with disabilities (visual, motor, etc.) to use all aspects of an application, but also benefit the general user population in a variety of common situations: where a keyboard is preferred, where it is difficult to read the display, where it is too loud to hear audio, etc.
Given the relatively new appearance of web components, there are a number of Web Component Limitations that may prevent a component from acting as perfectly as a standard HTML element. One goal of the Gold Standard effort is to draw such limitations to the attention of browser vendors so that these might be addressed in future standards work.
Oversight of the Gold Standard Checklist for Web Components is provided by Component Kitchen. Component Kitchen is a member of the Elix project, which is dedicated to creating general-purpose web components that meet the Gold Standard.