HTML Style Guide

Camel case ID and other attribute values

Use camel case for the values of attributes such as IDs and data test subject selectors.

<button
  id="veryImportantButton"
  data-test-subj="clickMeButton"
>
  Click me
</button>

The only exception is in cases where you're dynamically creating the value, and you need to use hyphens as delimiters:

<button
  ng-repeat="button in buttons"
  id="{{ 'veryImportantButton-' + button.id }}"
  data-test-subj="{{ 'clickMeButton-' + button.id }}"
>
  {{ button.label }}
</button>

Capitalization in HTML and CSS should always match

It's important that when you write CSS selectors using classes, IDs, and attributes (keeping in mind that we should never use IDs and attributes in our selectors), that the capitalization in the CSS matches that used in the HTML. HTML and CSS follow different case sensitivity rules, and we can avoid subtle gotchas by ensuring we use the same capitalization in both of them.

Multiple attribute values

When an element has multiple attributes, each attribute including the first should be on its own line with a single indent. This makes the attributes easier to scan and compare across similar elements.

The closing bracket should be on its own line. This allows attributes to be shuffled and edited without having to move the bracket around. It also makes it easier to scan vertically and match opening and closing brackets. This format is inspired by the positioning of the opening and closing parentheses in Pug/Jade.

<div
  attribute1="value1"
  attribute2="value2"
  attribute3="value3"
>
  Hello
</div>

If the element doesn't have children, add the closing tag on the same line as the opening tag's closing bracket.

<div
  attribute1="value1"
  attribute2="value2"
  attribute3="value3"
></div>

Nested elements belong on multiple lines

Putting nested elements on multiple lines makes it easy to scan and identify tags, attributes, and text nodes, and to distinguish elements from one another. This is especially useful if there are multiple similar elements which appear sequentially in the markup.

Do

<div>
  <span>
    hi
  </span>
</div>

Don't

<div><span>hi</span></div>

Accessibility

Don't use the `title` attribute

The title has no clear role within the accessibility standards. See the HTML5 spec for more information.

To provide supplementary, descriptive information about a form control, button, link, or other element, use a tooltip component instead.

Additional reading:

Tooltips

Elements which act as tooltips should have the role="tooltip" attribute and an ID to which the described element can point to with the aria-describedby attribute. For example:

<div
  class="kuiTooltip"
  role="tooltip"
  id="visualizationsTooltip"
>
  Visualizations help you make sense of your data.
</div>

<button aria-describedby="visualizationsTooltip">
 Visualizations
</button>

Prefer `button` and `a` when making interactive elements keyboard-accessible

If something is meant to be clickable, favor using a button or a tag before over the kui-accessible-click directive or KuiKeyboardAccessible component. These tools are useful as they augment non-clickable elements with onkeypress and onkeyup handlers, allowing non-clickable elements to become keyboard accessible. However, button and a tags provide this functionality natively.

Use `tabindex` to make elements tabbable

When added to the tab order, elements become focusable via non-sticky-mode keyboard navigation. To add an element to the tab order, you must add an id attribute as well as a tabindex attribute.

You should only use tabindex="0" to add an element to the tab flow or tabindex="-1" to remove an otherwise focusable element from the focus flow (use with care). You should never use a value greater than 0, since tabindex is a global counter for the whole webpage and not scoped to parent elements, so you would need to manage a globally meaningful order across all elements in the whole source code.

4.5 KiB Raw Blame History