Skip to content

docs: field-label accessibility docs #5364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 13, 2025
Merged

docs: field-label accessibility docs #5364

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f8098d1
docs: field-label accessibility docs
caseyisonit Apr 10, 2025
dc4d42c
docs: address feedback
caseyisonit Apr 11, 2025
e4f0995
docs: feedback
caseyisonit Apr 11, 2025
b97e92f
Merge branch 'main' into caseyisonit/SWC-380-field-label-docs
caseyisonit Apr 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 160 additions & 41 deletions packages/field-label/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Description
## Overview

An `<sp-field-label>` provides accessible labelling for form elements. Use the `for` attribute to outline the `id` of an element in the same DOM tree to which it should associate itself.
An `<sp-field-label>` provides accessible labelling for form elements. Use the `for` attribute to outline the `id` of an element in the same DOM tree to which it should associate itself. Field labels give context to information that a user needs to input and are commonly used in forms to provide users with clear guidance about what information is required.

### Usage

Expand All @@ -14,27 +14,50 @@ yarn add @spectrum-web-components/field-label

Import the side effectful registration of `<sp-field-label>` via:

```
```ts
import '@spectrum-web-components/field-label/sp-field-label.js';
```

When looking to leverage the `FieldLabel` base class as a type and/or for extension purposes, do so via:

```
```ts
import { FieldLabel } from '@spectrum-web-components/field-label';
```

## Sizes
### Anatomy

Field labels can be associated with form elements by using the `for` attribute, which should reference the `id` of the related input element.

```html demo
<sp-field-label for="email">Email address</sp-field-label>
<sp-textfield id="email" placeholder="[email protected]"></sp-textfield>
```

Field labels can also be used to label a group of related inputs:

```html demo
<sp-field-label for="account-type">Account type</sp-field-label>
<sp-radio-group id="account-type">
<sp-radio value="admin">Admin</sp-radio>
<sp-radio value="member" checked>Member</sp-radio>
<sp-radio value="guest">Guest</sp-radio>
</sp-radio-group>
```

### Options

<sp-tabs selected="m" auto label="Size Attribute Options">
#### Sizes

<sp-tabs selected="m" auto label="Size attribute options">
<sp-tab value="s">Small</sp-tab>
<sp-tab-panel value="s">

```html demo
<sp-field-label for="lifestory-0" size="s">Life Story</sp-field-label>
<sp-field-label for="lifestory-0" size="s">Life Story (Small)</sp-field-label>
<sp-textfield
placeholder="Enter your life story"
id="lifestory-0"
size="s"
></sp-textfield>
```

Expand All @@ -43,10 +66,11 @@ import { FieldLabel } from '@spectrum-web-components/field-label';
<sp-tab-panel value="m">

```html demo
<sp-field-label for="lifestory-1" size="m">Life Story</sp-field-label>
<sp-field-label for="lifestory-1" size="m">Life Story (Medium)</sp-field-label>
<sp-textfield
placeholder="Enter your life story"
id="lifestory-1"
size="m"
></sp-textfield>
```

Expand All @@ -55,10 +79,11 @@ import { FieldLabel } from '@spectrum-web-components/field-label';
<sp-tab-panel value="l">

```html demo
<sp-field-label for="lifestory-2" size="l">Life Story</sp-field-label>
<sp-field-label for="lifestory-2" size="l">Life Story (Large)</sp-field-label>
<sp-textfield
placeholder="Enter your life story"
id="lifestory-2"
size="l"
></sp-textfield>
```

Expand All @@ -67,44 +92,41 @@ import { FieldLabel } from '@spectrum-web-components/field-label';
<sp-tab-panel value="xl">

```html demo
<sp-field-label for="lifestory-3" size="xl">Life Story</sp-field-label>
<sp-field-label for="lifestory-3" size="xl">
Life Story (Extra Large)
</sp-field-label>
<sp-textfield
placeholder="Enter your life story"
id="lifestory-3"
size="xl"
></sp-textfield>
```

</sp-tab-panel>
</sp-tabs>

## Examples

```html
<sp-field-label for="lifestory">Life Story</sp-field-label>
<sp-textfield placeholder="Enter your life story" id="lifestory"></sp-textfield>
<sp-field-label for="birth-place">Birthplace</sp-field-label>
<sp-picker id="birth-place">
<span slot="label">Choose a location:</span>
<sp-menu-item>Istanbul</sp-menu-item>
<sp-menu-item>London</sp-menu-item>
<sp-menu-item>Maputo</sp-menu-item>
<sp-menu-item>Melbuorne</sp-menu-item>
<sp-menu-item>New York</sp-menu-item>
<sp-menu-item>San Fransisco</sp-menu-item>
<sp-menu-item>Santiago</sp-menu-item>
<sp-menu-item>Tokyo</sp-menu-item>
</sp-picker>
```
#### Label Position

## Side Aligned
Field labels can be positioned either on top of an input (default) or to the side of an input. The top position is recommended for most cases as it works better with long text, localization, and responsive layouts.

Using the `side-aligned` attribute will display the `<sp-field-label>` element inline with surrounding elements and the `start` and `end` values outline the alignment of the label text in the width specified.

### Start
<sp-tabs selected="top" auto label="Label position options">
<sp-tab value="top">Top (Default)</sp-tab>
<sp-tab-panel value="top">

```html demo
<sp-field-label for="country-top">Country</sp-field-label>
<sp-textfield placeholder="Enter your country" id="country-top"></sp-textfield>
```

</sp-tab-panel>
<sp-tab value="side-start">Side (Start Aligned)</sp-tab>
<sp-tab-panel value="side-start">

Use `side-aligned="start"` to display the `<sp-field-label>` inline and to align the label text to the "start" of the flow of text:

```html
```html demo
<sp-field-label for="lifestory-1" side-aligned="start" style="width: 120px">
Life Story
</sp-field-label>
Expand All @@ -127,21 +149,23 @@ Use `side-aligned="start"` to display the `<sp-field-label>` inline and to align
<sp-menu-item>Istanbul</sp-menu-item>
<sp-menu-item>London</sp-menu-item>
<sp-menu-item>Maputo</sp-menu-item>
<sp-menu-item>Melbuorne</sp-menu-item>
<sp-menu-item>Melbourne</sp-menu-item>
<sp-menu-item>New York</sp-menu-item>
<sp-menu-item>San Fransisco</sp-menu-item>
<sp-menu-item>San Francisco</sp-menu-item>
<sp-menu-item>Santiago</sp-menu-item>
<sp-menu-item>Tokyo</sp-menu-item>
</sp-picker>
```

### End
</sp-tab-panel>
<sp-tab value="side-end">Side (End Aligned)</sp-tab>
<sp-tab-panel value="side-end">

Use `side-aligned="end"` to display the `<sp-field-label>` inline and to align the label text to the "end" of the flow of text:

```html
```html demo
<sp-field-label
for="lifestory-1"
for="lifestory-2"
side-aligned="end"
required
style="width: 120px"
Expand All @@ -150,22 +174,117 @@ Use `side-aligned="end"` to display the `<sp-field-label>` inline and to align t
</sp-field-label>
<sp-textfield
placeholder="Enter your life story"
id="lifestory-1"
id="lifestory-2"
></sp-textfield>
<br />
<br />
<sp-field-label for="birth-place-1" side-aligned="end" style="width: 120px">
<sp-field-label for="birth-place-2" side-aligned="end" style="width: 120px">
Birthplace
</sp-field-label>
<sp-picker id="birth-place-1">
<sp-picker id="birth-place-2">
<span slot="label">Choose a location:</span>
<sp-menu-item>Istanbul</sp-menu-item>
<sp-menu-item>London</sp-menu-item>
<sp-menu-item>Maputo</sp-menu-item>
<sp-menu-item>Melbuorne</sp-menu-item>
<sp-menu-item>Melbourne</sp-menu-item>
<sp-menu-item>New York</sp-menu-item>
<sp-menu-item>San Fransisco</sp-menu-item>
<sp-menu-item>San Francisco</sp-menu-item>
<sp-menu-item>Santiago</sp-menu-item>
<sp-menu-item>Tokyo</sp-menu-item>
</sp-picker>
```

</sp-tab-panel>
</sp-tabs>

#### Necessity Indicator

Field labels can indicate whether an input is required or optional. By default, required fields are marked with an asterisk icon.

<sp-tabs selected="required" auto label="Necessity indicator options">
<sp-tab value="required">Required (Icon)</sp-tab>
<sp-tab-panel value="required">

```html demo
<sp-field-label for="name-required" required>Full name</sp-field-label>
<sp-textfield
placeholder="Enter your full name"
id="name-required"
required
></sp-textfield>
```

</sp-tab-panel>
<sp-tab value="optional">Optional (Text)</sp-tab>
<sp-tab-panel value="optional">

```html demo
<sp-field-label for="description-optional">
Profile description (optional)
</sp-field-label>
<sp-textfield
placeholder="Enter a description"
id="description-optional"
></sp-textfield>
```

</sp-tab-panel>
</sp-tabs>

### States

#### Disabled

When the associated input field is disabled, the field label should also be disabled.

```html demo
<sp-field-label for="disabled-field" disabled>Country</sp-field-label>
<sp-textfield
placeholder="Enter your country"
id="disabled-field"
disabled
></sp-textfield>
```

### Behaviors

#### Text Overflow

When a field label is too long for the available horizontal space, it wraps to form another line.

```html demo
<sp-field-label for="seminar-field" style="max-width: 200px">
What you're hoping to learn from the seminar and any specific topics you'd
like covered
</sp-field-label>
<sp-textfield
placeholder="Enter your expectations"
id="seminar-field"
></sp-textfield>
```

### Accessibility

#### Always include a label

Every input should have a label. An input without a label is ambiguous and not accessible. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be visually hidden but should still include an `aria-label` in HTML.

#### Ensure proper association

The `for` attribute of the field label should match the `id` attribute of the associated input element to ensure proper association for screen readers and other assistive technologies.

#### Keep labels concise

Use a short, descriptive label (1-3 words) for the information that users need to provide. Supplementary information or requirements should be shown in help text below the field, not in the label.

#### Use sentence case

Following Adobe's UX writing style, field labels should be written in sentence case unless they contain words that are branded terms.

#### Don't add a colon at the end of a field label

The design of the component already communicates the relationship between the label and the input field, so a colon is unnecessary.

#### Mark only required or only optional fields, not both

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. This reduces visual noise and makes the form easier to understand.
Loading