From f8098d154f8254fc2c34d323992781ff6882e8a8 Mon Sep 17 00:00:00 2001 From: Casey Eickhoff Date: Thu, 10 Apr 2025 13:57:10 -0600 Subject: [PATCH 1/3] docs: field-label accessibility docs --- packages/field-label/README.md | 197 ++++++++++++++++++++++++++------- 1 file changed, 157 insertions(+), 40 deletions(-) diff --git a/packages/field-label/README.md b/packages/field-label/README.md index b56f7af1543..6698a570e5a 100644 --- a/packages/field-label/README.md +++ b/packages/field-label/README.md @@ -1,12 +1,11 @@ -## Description +## Overview -An `` 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 `` provides context to information that a user needs to input. Field labels are commonly used in forms to give users clear guidance about what information is required. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/field-label?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/field-label) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/field-label?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/field-label) -[![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/fDq5bpzNQJzUUyEq6ENR/src/index.ts) ``` yarn add @spectrum-web-components/field-label @@ -14,19 +13,46 @@ yarn add @spectrum-web-components/field-label Import the side effectful registration of `` 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 + +```html +Email address + +``` + +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 +Email address + +``` + +Field labels can also be used to label a group of related inputs: + +```html demo +Account type + + Admin + Member + Guest + +``` + +### Options + +#### Sizes + + Small @@ -77,34 +103,28 @@ import { FieldLabel } from '@spectrum-web-components/field-label'; -## Examples - -```html -Life Story - -Birthplace - - Choose a location: - Istanbul - London - Maputo - Melbuorne - New York - San Fransisco - Santiago - Tokyo - -``` +#### 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 `` element inline with surrounding elements and the `start` and `end` values outline the alignment of the label text in the width specified. -### Start + +Top (Default) + -Use `side-aligned="start"` to display the `` inline and to align the label text to the "start" of the flow of text: +```html demo +Country + +``` -```html + +Side (Start Aligned) + + +Using `side-aligned="start"` displays the `` inline and aligns the label text to the "start" of the flow of text: + +```html demo Life Story @@ -127,21 +147,23 @@ Use `side-aligned="start"` to display the `` inline and to align Istanbul London Maputo - Melbuorne + Melbourne New York - San Fransisco + San Francisco Santiago Tokyo ``` -### End + +Side (End Aligned) + -Use `side-aligned="end"` to display the `` inline and to align the label text to the "end" of the flow of text: +Using `side-aligned="end"` displays the `` inline and aligns the label text to the "end" of the flow of text: -```html +```html demo ` inline and to align t

- + Birthplace - + Choose a location: Istanbul London Maputo - Melbuorne + Melbourne New York - San Fransisco + San Francisco Santiago Tokyo ``` + + + + +#### Necessity Indicator + +Field labels can indicate whether an input is required or optional. By default, required fields are marked with an asterisk icon. + + +Required (Icon) + + +```html demo +Full name + +``` + + +Optional (Text) + + +```html demo + + Profile description (optional) + + +``` + + + + +### States + +#### Disabled + +When the associated input field is disabled, the field label should also be disabled. + +```html demo +Country + +``` + +### Behaviors + +#### Text Overflow + +When a field label is too long for the available horizontal space, it wraps to form another line. + +```html demo + + What you're hoping to learn from the seminar and any specific topics you'd + like covered + + +``` + +### 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. From dc4d42c90bb07cba9b9baded65739b370d8ab0db Mon Sep 17 00:00:00 2001 From: Casey Eickhoff Date: Fri, 11 Apr 2025 10:06:46 -0600 Subject: [PATCH 2/3] docs: address feedback --- packages/field-label/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/field-label/README.md b/packages/field-label/README.md index 6698a570e5a..e070dc955d9 100644 --- a/packages/field-label/README.md +++ b/packages/field-label/README.md @@ -1,11 +1,12 @@ ## Overview -An `` provides context to information that a user needs to input. Field labels are commonly used in forms to give users clear guidance about what information is required. +An `` 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 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/field-label?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/field-label) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/field-label?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/field-label) +[![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/fDq5bpzNQJzUUyEq6ENR/src/index.ts) ``` yarn add @spectrum-web-components/field-label @@ -122,7 +123,7 @@ Using the `side-aligned` attribute will display the `` element i Side (Start Aligned) -Using `side-aligned="start"` displays the `` inline and aligns the label text to the "start" of the flow of text: +Use `side-aligned="start"` to display the `` inline and to align the label text to the "start" of the flow of text: ```html demo @@ -159,7 +160,7 @@ Using `side-aligned="start"` displays the `` inline and aligns t Side (End Aligned) -Using `side-aligned="end"` displays the `` inline and aligns the label text to the "end" of the flow of text: +Use `side-aligned="end"` to display the `` inline and to align the label text to the "end" of the flow of text: ```html demo Date: Fri, 11 Apr 2025 12:09:34 -0600 Subject: [PATCH 3/3] docs: feedback --- packages/field-label/README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/packages/field-label/README.md b/packages/field-label/README.md index e070dc955d9..5d7cfbb7054 100644 --- a/packages/field-label/README.md +++ b/packages/field-label/README.md @@ -26,16 +26,11 @@ import { FieldLabel } from '@spectrum-web-components/field-label'; ### Anatomy -```html -Email address - -``` - 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 -Email address - +Email address + ``` Field labels can also be used to label a group of related inputs: @@ -58,10 +53,11 @@ Field labels can also be used to label a group of related inputs: ```html demo -Life Story +Life Story (Small) ``` @@ -70,10 +66,11 @@ Field labels can also be used to label a group of related inputs: ```html demo -Life Story +Life Story (Medium) ``` @@ -82,10 +79,11 @@ Field labels can also be used to label a group of related inputs: ```html demo -Life Story +Life Story (Large) ``` @@ -94,10 +92,13 @@ Field labels can also be used to label a group of related inputs: ```html demo -Life Story + + Life Story (Extra Large) + ```