Styleguide

Contribution standards and conventions

Common Standards
CSS Standards
HTML Standards
JavaScript Standards
Documentation Standards

Common Standards

Use Spaces, Not Tabs

For consistency, use spaces instead of tabs for indentation.

Line Length

Preferred	Maximum
80 chars	120 chars

80 characters or less is preferred
120 characters is absolute maximum line length
URLs are the only exception to this rule

Entity Naming Conventions

We must prefix all Element and CSS definitions with hx or HX to avoid namespace conflicts and to ensure maximum compatibility with 3rd party libraries.

	Format	Example
Element Name	`hx-kebab-case`	`hx-checkbox`, `hx-icon`, etc.
Element Class	`HXUpperCamelElement`	`HXCheckboxElement`, `HXIconElement`, etc.
CSS Class	`.hxLowerCamelCase`	`.hxSuccess`, `.hxSpan-12`, etc.
Custom Event (public)*	`lowereventname`	`open`, `dismiss`, `panelchange`, etc.
Custom Event (private)*	`hxlowereventname`	`hxchange`, `hxdirty`, `hxtouch`, etc.

* TODO: should ALL custom events be hx prefixed?

Custom Element Names

Based on observation, consumers find it more natural to type <hx-parent-child> rather than <hx-parentchild>.

Strive to name custom elements after applicable ARIA roles, if possible.
- e.g. <hx-tab-list> is named after the tablist ARIA role.
Avoid abbreviations
- e.g., <hx-foobar-control> is preferred over <hx-foobar-ctrl>

Recommended:

<hx-parent>
  <hx-parent-child>...</hx-parent-child>
</hx-parent>

Avoid:

<hx-parent>
  <hx-parentchild>...</hx-parentchild>
</hx-parent>

Filename Conventions

All custom element assets should conform to the following file structure.

.
└ hx-{element-name}/  # e.g., hx-accordion/, hx-accordion-panel/, etc.
  ├ _shadow.html  # Shadow Markup
  ├ _shadow.scss  # Shadow Styles
  ├ index.js      # HXElementName class def
  └ index.spec.js # HXElementName unit tests