Skip to content

Commit db9f8b6

Browse files
caseyisonitcaseyisonit
authored
docs: field-label accessibility docs (#5364)
* docs: field-label accessibility docs * docs: address feedback * docs: feedback
1 parent 4e06533 commit db9f8b6

File tree

1 file changed

+160
-41
lines changed

1 file changed

+160
-41
lines changed

‎packages/field-label/README.md

+160-41
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
## Description
1+
## Overview
22

3-
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.
3+
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.
44

55
### Usage
66

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

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

17-
```
17+
```ts
1818
import '@spectrum-web-components/field-label/sp-field-label.js';
1919
```
2020

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

23-
```
23+
```ts
2424
import { FieldLabel } from '@spectrum-web-components/field-label';
2525
```
2626

27-
## Sizes
27+
### Anatomy
28+
29+
Field labels can be associated with form elements by using the `for` attribute, which should reference the `id` of the related input element.
30+
31+
```html demo
32+
<sp-field-label for="email">Email address</sp-field-label>
33+
<sp-textfield id="email" placeholder="[email protected]"></sp-textfield>
34+
```
35+
36+
Field labels can also be used to label a group of related inputs:
37+
38+
```html demo
39+
<sp-field-label for="account-type">Account type</sp-field-label>
40+
<sp-radio-group id="account-type">
41+
<sp-radio value="admin">Admin</sp-radio>
42+
<sp-radio value="member" checked>Member</sp-radio>
43+
<sp-radio value="guest">Guest</sp-radio>
44+
</sp-radio-group>
45+
```
46+
47+
### Options
2848

29-
<sp-tabs selected="m" auto label="Size Attribute Options">
49+
#### Sizes
50+
51+
<sp-tabs selected="m" auto label="Size attribute options">
3052
<sp-tab value="s">Small</sp-tab>
3153
<sp-tab-panel value="s">
3254

3355
```html demo
34-
<sp-field-label for="lifestory-0" size="s">Life Story</sp-field-label>
56+
<sp-field-label for="lifestory-0" size="s">Life Story (Small)</sp-field-label>
3557
<sp-textfield
3658
placeholder="Enter your life story"
3759
id="lifestory-0"
60+
size="s"
3861
></sp-textfield>
3962
```
4063

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

4568
```html demo
46-
<sp-field-label for="lifestory-1" size="m">Life Story</sp-field-label>
69+
<sp-field-label for="lifestory-1" size="m">Life Story (Medium)</sp-field-label>
4770
<sp-textfield
4871
placeholder="Enter your life story"
4972
id="lifestory-1"
73+
size="m"
5074
></sp-textfield>
5175
```
5276

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

5781
```html demo
58-
<sp-field-label for="lifestory-2" size="l">Life Story</sp-field-label>
82+
<sp-field-label for="lifestory-2" size="l">Life Story (Large)</sp-field-label>
5983
<sp-textfield
6084
placeholder="Enter your life story"
6185
id="lifestory-2"
86+
size="l"
6287
></sp-textfield>
6388
```
6489

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

6994
```html demo
70-
<sp-field-label for="lifestory-3" size="xl">Life Story</sp-field-label>
95+
<sp-field-label for="lifestory-3" size="xl">
96+
Life Story (Extra Large)
97+
</sp-field-label>
7198
<sp-textfield
7299
placeholder="Enter your life story"
73100
id="lifestory-3"
101+
size="xl"
74102
></sp-textfield>
75103
```
76104

77105
</sp-tab-panel>
78106
</sp-tabs>
79107

80-
## Examples
81-
82-
```html
83-
<sp-field-label for="lifestory">Life Story</sp-field-label>
84-
<sp-textfield placeholder="Enter your life story" id="lifestory"></sp-textfield>
85-
<sp-field-label for="birth-place">Birthplace</sp-field-label>
86-
<sp-picker id="birth-place">
87-
<span slot="label">Choose a location:</span>
88-
<sp-menu-item>Istanbul</sp-menu-item>
89-
<sp-menu-item>London</sp-menu-item>
90-
<sp-menu-item>Maputo</sp-menu-item>
91-
<sp-menu-item>Melbuorne</sp-menu-item>
92-
<sp-menu-item>New York</sp-menu-item>
93-
<sp-menu-item>San Fransisco</sp-menu-item>
94-
<sp-menu-item>Santiago</sp-menu-item>
95-
<sp-menu-item>Tokyo</sp-menu-item>
96-
</sp-picker>
97-
```
108+
#### Label Position
98109

99-
## Side Aligned
110+
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.
100111

101112
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.
102113

103-
### Start
114+
<sp-tabs selected="top" auto label="Label position options">
115+
<sp-tab value="top">Top (Default)</sp-tab>
116+
<sp-tab-panel value="top">
117+
118+
```html demo
119+
<sp-field-label for="country-top">Country</sp-field-label>
120+
<sp-textfield placeholder="Enter your country" id="country-top"></sp-textfield>
121+
```
122+
123+
</sp-tab-panel>
124+
<sp-tab value="side-start">Side (Start Aligned)</sp-tab>
125+
<sp-tab-panel value="side-start">
104126

105127
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:
106128

107-
```html
129+
```html demo
108130
<sp-field-label for="lifestory-1" side-aligned="start" style="width: 120px">
109131
Life Story
110132
</sp-field-label>
@@ -127,21 +149,23 @@ Use `side-aligned="start"` to display the `<sp-field-label>` inline and to align
127149
<sp-menu-item>Istanbul</sp-menu-item>
128150
<sp-menu-item>London</sp-menu-item>
129151
<sp-menu-item>Maputo</sp-menu-item>
130-
<sp-menu-item>Melbuorne</sp-menu-item>
152+
<sp-menu-item>Melbourne</sp-menu-item>
131153
<sp-menu-item>New York</sp-menu-item>
132-
<sp-menu-item>San Fransisco</sp-menu-item>
154+
<sp-menu-item>San Francisco</sp-menu-item>
133155
<sp-menu-item>Santiago</sp-menu-item>
134156
<sp-menu-item>Tokyo</sp-menu-item>
135157
</sp-picker>
136158
```
137159

138-
### End
160+
</sp-tab-panel>
161+
<sp-tab value="side-end">Side (End Aligned)</sp-tab>
162+
<sp-tab-panel value="side-end">
139163

140164
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:
141165

142-
```html
166+
```html demo
143167
<sp-field-label
144-
for="lifestory-1"
168+
for="lifestory-2"
145169
side-aligned="end"
146170
required
147171
style="width: 120px"
@@ -150,22 +174,117 @@ Use `side-aligned="end"` to display the `<sp-field-label>` inline and to align t
150174
</sp-field-label>
151175
<sp-textfield
152176
placeholder="Enter your life story"
153-
id="lifestory-1"
177+
id="lifestory-2"
154178
></sp-textfield>
155179
<br />
156180
<br />
157-
<sp-field-label for="birth-place-1" side-aligned="end" style="width: 120px">
181+
<sp-field-label for="birth-place-2" side-aligned="end" style="width: 120px">
158182
Birthplace
159183
</sp-field-label>
160-
<sp-picker id="birth-place-1">
184+
<sp-picker id="birth-place-2">
161185
<span slot="label">Choose a location:</span>
162186
<sp-menu-item>Istanbul</sp-menu-item>
163187
<sp-menu-item>London</sp-menu-item>
164188
<sp-menu-item>Maputo</sp-menu-item>
165-
<sp-menu-item>Melbuorne</sp-menu-item>
189+
<sp-menu-item>Melbourne</sp-menu-item>
166190
<sp-menu-item>New York</sp-menu-item>
167-
<sp-menu-item>San Fransisco</sp-menu-item>
191+
<sp-menu-item>San Francisco</sp-menu-item>
168192
<sp-menu-item>Santiago</sp-menu-item>
169193
<sp-menu-item>Tokyo</sp-menu-item>
170194
</sp-picker>
171195
```
196+
197+
</sp-tab-panel>
198+
</sp-tabs>
199+
200+
#### Necessity Indicator
201+
202+
Field labels can indicate whether an input is required or optional. By default, required fields are marked with an asterisk icon.
203+
204+
<sp-tabs selected="required" auto label="Necessity indicator options">
205+
<sp-tab value="required">Required (Icon)</sp-tab>
206+
<sp-tab-panel value="required">
207+
208+
```html demo
209+
<sp-field-label for="name-required" required>Full name</sp-field-label>
210+
<sp-textfield
211+
placeholder="Enter your full name"
212+
id="name-required"
213+
required
214+
></sp-textfield>
215+
```
216+
217+
</sp-tab-panel>
218+
<sp-tab value="optional">Optional (Text)</sp-tab>
219+
<sp-tab-panel value="optional">
220+
221+
```html demo
222+
<sp-field-label for="description-optional">
223+
Profile description (optional)
224+
</sp-field-label>
225+
<sp-textfield
226+
placeholder="Enter a description"
227+
id="description-optional"
228+
></sp-textfield>
229+
```
230+
231+
</sp-tab-panel>
232+
</sp-tabs>
233+
234+
### States
235+
236+
#### Disabled
237+
238+
When the associated input field is disabled, the field label should also be disabled.
239+
240+
```html demo
241+
<sp-field-label for="disabled-field" disabled>Country</sp-field-label>
242+
<sp-textfield
243+
placeholder="Enter your country"
244+
id="disabled-field"
245+
disabled
246+
></sp-textfield>
247+
```
248+
249+
### Behaviors
250+
251+
#### Text Overflow
252+
253+
When a field label is too long for the available horizontal space, it wraps to form another line.
254+
255+
```html demo
256+
<sp-field-label for="seminar-field" style="max-width: 200px">
257+
What you're hoping to learn from the seminar and any specific topics you'd
258+
like covered
259+
</sp-field-label>
260+
<sp-textfield
261+
placeholder="Enter your expectations"
262+
id="seminar-field"
263+
></sp-textfield>
264+
```
265+
266+
### Accessibility
267+
268+
#### Always include a label
269+
270+
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.
271+
272+
#### Ensure proper association
273+
274+
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.
275+
276+
#### Keep labels concise
277+
278+
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.
279+
280+
#### Use sentence case
281+
282+
Following Adobe's UX writing style, field labels should be written in sentence case unless they contain words that are branded terms.
283+
284+
#### Don't add a colon at the end of a field label
285+
286+
The design of the component already communicates the relationship between the label and the input field, so a colon is unnecessary.
287+
288+
#### Mark only required or only optional fields, not both
289+
290+
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.

0 commit comments

Comments
 (0)