HTML Formatting

When writing HTML either for demos, documentation, or in component shadow DOM, try to abide by these formatting guidelines.

Indentation

Our current lint rules specify two spaces for a single indent. So in these guidelines wherever a "unit" of indentation is mentioned, read "two spaces". In the future, if and when we switch to tabs, substitute "one tab".

Children

Children should be indented by one unit.

✅ DO

<div>
  <p>Indented by one unit</p>
</div>

❌ DON'T DO

<div>
    <p>Indented by two units</p>
</div>

<div>
<p>Not indented</p>
</div>

<div>
  <p>Indented by one space</p>
</div>

Attributes

Attributes should be indented by at least two units. This ensures they are visually distinct from children.

✅ DO

<button id="submit"
    type="submit"
    @click="${this.#onSubmit}">
  Indented by two units - attrs are distinct from children
</button>

❌ DON'T DO

<button id="submit"
  type="submit"
  @click="${this.#onSubmit}">
  Indented by one unit - attrs line up with children
</button>

Inline Attributes

Elements should have at least one attribute inline, and may have as many more as will fit within the max-length of the line.

✅ DO

<button id="submit" type="submit" @click="${this.#onSubmit}">
  All attrs fit on one line
</button>

✅ DO

<button id="submit"
    type="submit"
    @click="${this.#onSubmit}">
  First attr is inline
</button>

❌ DON'T DO

<button
    id="submit"
    type="submit"
    @click="${this.#onSubmit}">
  No attrs are inline
</button>

Columnar Attributes

Attributes may line up with the first inline attribute, so long as they are indented by as least two units. This is a matter of taste which can produce more beautiful and easier to understand templates.

✅ DO

<button id="submit"
        type="submit"
        @click="${this.#onSubmit}">
  attrs are columnar
</button>

❌ DON'T DO

<a id="link"
   href="/somewhere"
   @click="${this.#onSubmit}">
  Columnar attrs should be >= 2
</a>

Attribute Order

If the element has an id attribute, that must be the first attribute, and should be inline. This is because the ID uniquely identifies the element, and has impact on CSS specificity and assistive technology features. As such, when ID'ing an element, it should be done with care and explicit intention. Putting the ID first signals it's precedence over the other attributes and makes it easier for reviewers to find the element by ID.

Elements that have a class, type, or variant but no id may use that as the first attribute instead.

✅ DO

<button id="submit"
        type="submit"
        @click="${this.#onSubmit}">
  ID is first
</button>

❌ DON'T DO

<button type="submit"
        @click="${this.#onSubmit}"
        id="submit">
  ID is not first
</button>

Lit Bindings

lit bindings like ?booleans, .properties, and @events should go, in that order, after unprefixed attributes. Within each category, and with the exception of the first attribute, you may order attributes alphabetically.

✅ DO

<button id="submit"
        type="submit"
        data-freshness="fresh"
        ?disabled="${this.disabled}"
        .context="${this.context}"
        @click="${this.#onSubmit}"
        @focus="${this.#onFocus}">
  Order is mixed
</button>

❌ DON'T DO

<button id="submit"
        @click="${this.#onSubmit}"
        .context="${this.context}"
        @focus="${this.#onFocus}"
        ?disabled="${this.disabled}"
        type="submit"
        data-freshness="fresh">
  Order is mixed
</button>