Styleguide - HelixDesignSystem/helix-ui GitHub Wiki

Contribution standards and conventions

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

CSS Standards

Read the CSS Styleguide

HTML Standards

Read the HTML Styleguide

JavaScript Standards

Read the JavaScript Styleguide

Documentation Standards

Read the Documentation Styleguide

⚠️ **GitHub.com Fallback** ⚠️