Best way to markup the Lightning Design System Input Field

Question

I was going through the documentation for using the Lightning Design System in Visualforce pages and I noticed what seems to be an inconsistency with how they markup the Input fields.

In the official documentation when they list the Input Field by itself they use the following example.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="sample1">Text Input</label>
  <div class="slds-form-element__control">
    <input id="sample1" class="slds-input" type="text" placeholder="Placeholder Text" />
  </div>
</div>

Which uses an outer div to hold a Label and an inner div (which is a sibling of the Label) that holds the Input Field.

However later on when using a Compound Form the example provided has the Label wrap the Input Field as well as a span

  <label class="slds-form-element__control slds-size--1-of-2">
    <span class="slds-form-element__helper">Latitude</span>
    <input class="slds-input" type="text" />
  </label>

I've tried both forms outside of a Compound Form and they appear the same. Putting both forms inside the Compound Form makes the first example display oddly.

Is it better to use the second form in all instances or should the markup be different depending on how it's used?

Answer 1

The component overview in the docs supports using the slds-form-element__label element.

The Github repo for the winter-16 release suggests that the __helper element is just styling the input to font-size small, whereas the __label element sets spacing as well and also supports the use of a required modifier.

This makes me think that the second form IS indeed just for compound forums. There's a lot to be desired in docs for this situation.