Skip to content

Commit

Permalink
Merge pull request #72 from studio24/feature/update-form-docs
Browse files Browse the repository at this point in the history
fix: update documentation about forms and errors
  • Loading branch information
NicolaSaunders authored Jul 5, 2024
2 parents 433f183 + aca5b64 commit 1925083
Show file tree
Hide file tree
Showing 5 changed files with 27 additions and 32 deletions.
6 changes: 0 additions & 6 deletions assets-src/styles/sass/35-forms/_forms.scss
Original file line number Diff line number Diff line change
Expand Up @@ -96,12 +96,6 @@ label,
}


.required {
color: $neutral-70;
font-weight: normal;
}


input, optgroup, {
line-height: 1.15;
}
Expand Down
31 changes: 17 additions & 14 deletions web/amplify/fundamentals/form-errors.html
Original file line number Diff line number Diff line change
Expand Up @@ -97,15 +97,6 @@
</nav>
<div><!-- Empty div used to create gutter (IE doesn't support grid-gap) --></div>
<div class="content">
<div class="component component--text">
<h1>Form error messages</h1>
<p>To notify a user of an error with their form submission:</p>
<ol>
<li>Prefix the word “Error:” to the document’s <code>title</code>. It’s the first thing announced by screen readers when the page loads.</li>
<li>Place an error summary at the top of the page</li>
<li>Add an error message to each problematic input</li>
</ol>
</div>
<div class="component">
<div class="l-box note note--error" role="alert" aria-labelledby="error-summary-title" tabindex="-1" data-component="error-summary">
<h2 id="error-summary-title" class="note__heading">There is a problem</h2>
Expand Down Expand Up @@ -145,8 +136,24 @@ <h2 id="error-summary-title" class="note__heading">There is a problem</h2>
</li>
</ul>
</div>
</div>

<h1>Page title</h1>
<div class="component component--text">
<h1>Form error messages</h1>
<p>To notify a user of an error with their form submission:</p>
<ol>
<li>Prefix the word “Error:” to the document’s <code>title</code>. It’s the first thing announced by screen readers when the page loads.</li>
<li>Place an error summary at the top of the page</li>
<li>Add an error message to each problematic input</li>
</ol>
</div>
<div class="component component--text">
<h2>Error summary considerations</h2>
<p>The error summary should be at the top of the <code>main</code> element. If the page includes <a href="../core-components/breadcrumbs.html">breadcrumbs</a> or a back link, place it after these, but before the <code>h1</code>. The error summary must contain the heading ‘There is a problem’.</p>
<p>Keyboard focus needs to move to the error summary, hence the addition of <code>tabindex="-1"</code>. JavaScript is included to shift focus if an error summary is present.</p>
<p>Each item in the summary list should link to the field with the validation error. Use the same wording for the error in both the error summary and the problematic field.</p>
</div>
<div class="component">
<h2>Example form showcasing error messages</h2>
<form novalidate>
<div class="field-group">
Expand Down Expand Up @@ -398,10 +405,6 @@ <h3 class="field-legend">Other input types</h3>
</form>
</div>
<div class="component component--text">
<h2>Error summary considerations</h2>
<p>The error summary should be at the top of the <code>main</code> element. If the page includes breadcrumbs or a back link, place it after these, but before the <code>h1</code>. The error summary must contain the heading ‘There is a problem’.</p>
<p>Keyboard focus needs to move to the error summary, hence the addition of <code>tabindex="-1"</code>. JavaScript is included to shift focus if an error summary is present.</p>
<p>Each item in the summary list must link to the field with the validation error. Use the same wording for the error in both the error summary and the problematic field.</p>
<h2>Error message considerations</h2>
<p>In the event of a validation error, the error message should explain what went wrong and how to fix it. Keep the wording clear and concise.</p>
<p>To help screen reader users, the error message includes a visually hidden ‘Error:’ before the error message.</p>
Expand Down
15 changes: 9 additions & 6 deletions web/amplify/fundamentals/forms.html
Original file line number Diff line number Diff line change
Expand Up @@ -105,16 +105,19 @@ <h1>Forms</h1>
<h2>Top tips</h2>
<ul>
<li>Every <code>input</code> needs a <code>label</code>. Do not wrap inputs in labels, put labels above the input.</li>
<li>Do not use the <code>placeholder</code> attribute on <code>input</code> fields.</li>
<li><a href="https://adamsilver.io/blog/the-problem-with-placeholders-and-what-to-do-instead/">Placeholders are problematic</a>, so avoid using the <code>placeholder</code> attribute, especially for providing any meaningful instructions. Do not use it to replace a label.</li>
<li>Use <a href="#fixed-width-inputs">fixed width inputs</a> for content that has a specific, known length. Postcode inputs should be postcode-sized, telephone number inputs should be telephone number-sized.</li>
<li>Make form fields look like form fields: apply a border and make sure they are empty to begin with. A minimum height of 44 pixels makes them easy to tap on touch screen devices.</li>
<li>Make sure any <code>button</code> looks like a button. Align them to the left edge of the last input (the right edge for right-to-left languages) where users naturally look for them. Use a verb for button text because the user is doing something, and relate it to what they are doing - avoid generic ‘Submit’ buttons.</li>
<li>Make form fields look like form fields: apply a border and make sure that fields are empty to begin with. A minimum height of 44 pixels makes them easy to tap on touch screen devices.</li>
<li>Make sure any <code>button</code> looks like a button. Align them to the left edge of the last input (the right edge for right-to-left languages) where users naturally look for them. Use a <a href="https://www.merriam-webster.com/grammar/what-is-a-verb">verb</a> for button text because the user is doing something, and relate it to what they are doing - avoid generic ‘Submit’ buttons.</li>
<li><a href="https://www.youtube.com/watch?v=CUkMCQR4TpY">The <code>select</code> element should be a last resort</a> as they’re really hard to use. Try radio buttons instead. If there’s a long list of options, use JavaScript to enhance the <code>select</code> into an <a href="../advanced-components/accessible-autocomplete.html">accessible auto-complete field</a> (not to be confused with the <code>autocomplete</code> attribute).</li>
<li>If you have to use a <code>select</code>, don't submit a form when its value changes. Select boxes that submit the form automatically when the user selects an option cause problems for keyboard and screen reader users.</li>
<li>If you have to use a <code>select</code> and selecting an option will result in a <a href="https://www.w3.org/WAI/WCAG22/Understanding/on-input#dfn-changes-of-context">change of context</a> (e.g. a page reload/refresh causing a change in focus), that change must be triggered by an accompanying confirmatory button, not by the change to the <code>select</code> value. Note that <code>select</code> works very differently outside the MacOS environment - using the arrow keys in Windows automatically switches between options, while on MacOS it first brings up the list of options.</li>
</ul>
<h3>Required fields</h3>
<p>It is best practice to only ask questions that are strictly necessary.</p>
<p>In the event that a form contains both optional and required fields, to clearly identify the required fields to all users add <code>span class="required"&gt;(Required)&lt;/span</code> within the <code>label</code>.</p>
<p>Well-designed forms usually avoid optional fields (one way is with <a href="https://adamsilver.io/blog/how-to-avoid-optional-form-fields-with-branching-questions/">branching questions</a>). This means optional fields should be rare, and we want to highlight them to people:</p>
<ul>
<li>Add the <code>required</code> attribute to mandatory input fields (or <code>aria-required="true"</code> if for some reason you have to use a non-native element as an input).</li>
<li><a href="https://adamsilver.io/blog/how-to-highlight-required-and-optional-form-fields/">Highlight optional fields only</a>, by adding (optional) to the end of the visible <code>label</code> text for fields that are not required.</li>
</ul>
<h3 id="how-to-add-hint-text">How to add hint text</h3>
<p>To provide hint text advising how to complete a field, add a <code>div class="field-hint"</code>. Check the examples that follow to see where this should be added. The pattern differs slightly for checkbox and radio inputs compared to other input types.</p>
<p>Each instance of <code>div class="field-hint"</code> must have a unique ID that is used as the value of the <code>aria-describedby</code> attribute that must be added to the associated <code>input</code>.</p>
Expand Down
5 changes: 0 additions & 5 deletions web/dist/styles/core.css
Original file line number Diff line number Diff line change
Expand Up @@ -1184,11 +1184,6 @@ label,
max-inline-size: 41.25rem;
}

.required {
color: #525252;
font-weight: normal;
}

input, optgroup {
line-height: 1.15;
}
Expand Down
2 changes: 1 addition & 1 deletion web/dist/styles/core.min.css

Large diffs are not rendered by default.

0 comments on commit 1925083

Please sign in to comment.