Provide help docs

Author: rianrietveld

assets/css/richtlijnen_formulier_voorkom-fouten_geboortedatum-english.png

@@ -0,0 +1,57 @@
+---
+title: Autocomplete
+layout: default
+parent: Provide help
+nav_order: 3
+has_video: true
+---
+
+# Autocomplete in a form
+
+The HTML [autocomplete](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute tells the browser what type of value is expected when filling in out form field. Browsers store what users have entered before. Browsers can then use those saved values to automatically fill out fields. 
+
+Data such as names, addresses, and phone numbers can then be filled in automatically by the browser.
+
+Autocomplete is helpful for users who have difficulty typing, have memory issues, struggle with language or just love the convenience of not typing the same data over and over again.
+
+## Use autocomplete when a value is defined
+
+WCAG contains a complete [list of values for autocomplete](https://www.w3.org/TR/WCAG22/#input-purposes). Always use an `autocomplete` attribute if a value for a form field is defined in this list.
+
+When using `autocomplete`, it is important that the label always remains visible. The user needs to know whether the correct value has been entered in the according field.
+
+{: .callout .tip }
+**Tip**: The autocomplete value for City is `address-level2`.
+
+## Code example
+
+```html
+<input 
+        id="firstname"
+        name="firstname"
+        type="text"
+        autocomplete="given-name"
+/>
+```
+
+{: .callout .info }
+Note: `aria-autocomplete` has a different purpose and usage than autocomplete on form fields. [aria-autocomplete is used in web components](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete), for example to indicate that suggestions are available for search results.
+
+## Pre-fill known information where possible
+
+This doesn't address 'autocomplete', but it is related: if the user is logged in, use known information to pre-fill fields. For example, if a session already contains available information that could be used to pre-fill fields. Like a shipping address for an online order.
+
+## Resources
+
+### WCAG Success Criteria
+
+Using the correct autocomplete attribute is required to meet WCAG Success Criterion [1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG22/quickref/#identify-input-purpose) (Level AA).
+
+### Autocomplete in WP Plugins
+- Gravity Forms
+- WP Forms
+- etc
+
+### Other resources
+
+Jules Ernst from 200 OK has created a [Dutch interpretation of autocomplete](https://www.200ok.nl/tips/autocomplete/) of this list.

assets/images/richtlijnen_formulier_voorkom-fouten_geboortedatum-english.png

@@ -0,0 +1,89 @@
+---
+title: Avoid input patterns
+layout: default
+parent: Provide help
+nav_order: 3
+has_video: true
+---
+
+# Avoid input patterns on form fields
+
+Make it as easy as possible for users to enter a value flexibly. A fixed input pattern (mask) may not be suitable for the answer a user wants to provide.
+
+## What is the issue about input patterns?
+
+When you force a user to enter data according to a fixed pattern it can cause confusion when their value to enter doesn't match the pattern.
+
+A fixed pattern can even become a barrier to completing a form. 
+
+For example:
+
+- The phone number does not match the required pattern: the user wants to enter a foreign number, but that is not allowed.
+- The user wants to add important information such as “call only in the afternoon,” but cannot.
+- The user doesn't understand what is going wrong because, for example, letters cannot be entered and there is no good feedback explaining the error.
+- Screen reader users may miss the visual information about how to fill out the form.
+
+Note: There are situations where an exact input is required. In those cases, always clearly explain in the description how the field should be filled in.
+
+## What is a pattern on an input field?
+
+A pattern (mask) defines exactly how a form field must be filled out and doesn't allow any other input.
+
+This can be done using the HTML pattern attribute in combination with JavaScript.
+
+The pattern specifies what the value must look like exactly. JavaScript then checks that value, may adjust the layout, and blocks invalid input. How the user is expected to enter the value according to the desired pattern is then explained in the description or in a placeholder.
+
+You can restrict a first-name input field to, for example, a minimum of 3 and a maximum of 12 characters. Too bad if your name is Jo or Claus-Casimir.
+
+```html
+<!-- Incorrect code, do not use -->
+<input 
+        id="firstname" 
+        name="firstname" 
+        type="text" 
+        pattern="\w{3,16}" 
+        autocomplete="given-name" 
+/>
+```
+
+You can require a specific format for a phone number input field. Too bad if you no longer have a landline or want to provide an international number.
+
+```html
+<!-- Incorrect code, do not use -->
+<input
+    type="tel"
+    id="telephone"
+    name="telephone"
+    pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}"
+    placeholder="___-___-____"
+    autocomplete="tel"
+/>
+```
+
+## User experience and accessibility of input patterns
+
+Adam Silver summarizes it well in his article [The problem with input masks and what to do instead](https://adamsilver.io/blog/the-problem-with-input-masks-and-what-to-do-instead/).
+
+- The pattern may not be suitable for the answer the user wants to give.
+- Enforced patterns are confusing: the cursor automatically jumps to the next position, and special characters such as -, (, or ) cannot be removed.
+- A placeholder with an example can look like a pre-filled field.
+- The placeholder with the example disappears while typing, and you no longer know how to complete the rest of the value.
+- Because characters are removed or skipped, it can feel like something is going wrong without an immediate error message appearing.
+
+In the article [Accessible input masking](https://giovanicamara.com/blog/accessible-input-masking/), Giovani Camara shows in the YouTube video [Allow users to edit anywhere](https://www.youtube.com/watch?v=rTk3XNSXJXY) what can go wrong when a user wants to change a value. The cursor can automatically jump to the end of the value while you want to edit the first character. This is annoying for everyone and leads to errors.
+
+Indicating input patterns in a placeholder or in the value attribute can be very unclear for screen reader users. A series of underscores is not very informative. Watch and listen to Giovani Camara’s demo on YouTube using VoiceOver.
+<video data-able-player data-youtube-nocookie="true" data-youtube-id="7WWQXGgRDLc" data-heading-level="0"></video>
+
+If exact input is required, for example for a date of birth, provide an option that everyone can easily complete. 
+ In addition, a [good description]({{site.baseurl}}/docs/topics/forms/help/valid-values/) and [clear error messages]({{site.baseurl}}/docs/topics/forms/feedback/error-message-text/) are important. Help the user and do not make them puzzle over how exactly to fill in a field or what went wrong again.
+
+## Resources
+
+### WCAG Success Criteria for descriptions
+
+Providing good feedback about correctly entering data in form fields is necessary to meet the WCAG success criteria:
+
+- [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/quickref/#error-identification) (Level A)
+- [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/quickref/#error-suggestion) (Level AA)
+

assets/images/richtlijnen_formulier_voorkom-fouten_wachtwoord-english.png

@@ -0,0 +1,39 @@
+---
+title: Be flexible
+layout: default
+parent: Provide help
+nav_order: 3
+---
+
+# Don’t reject a form entry too quickly
+
+Be flexible accepting the data a user fills out a field. If it's not exactly in the format you want, change it for them in the code.
+
+{: .info .callout}
+**Note**: this is best practice and not a WCAG requirement.
+
+## Date formats
+
+Users may unknowingly enter a different separation character then planned and then get the warning "Invalid date". While actually it's not invalid, it's not in your preferred format.
+
+For example January 1, 2026 can be entered as: 
+
+- 01.01.2026
+- 01-01-2026
+- 01/01/2026
+
+Why not help the user and transform the separation character in your software for them?
+
+## Email addresses
+
+Some people use a + in their email address, for example to make it easier to group emails.
+
+They might use name+school@example.com for school-related emails and name+work@example.com for work emails. These are valid email addresses, so don’t reject them.
+
+Email addresses with a plus sign are valid.
+
+## Postal codes
+
+[Postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes) can be written in different ways, for example in the Netherlands as: “1234 AA” (with a space), “1234AA” (without a space), or “1234aa” (lowercase). Extra spaces at the beginning or end can also be included when text is copied and pasted.
+
+In code, these variations can easily be normalized to a single format. By accepting all valid ways and letting the software correct them, you prioritize the user instead of your software.

docs/topics/forms/help.md

@@ -0,0 +1,16 @@
+---
+title: Allow copy/paste
+layout: default
+parent: Provide help
+nav_order: 2
+---
+
+# Allow copying and pasting of passwords
+
+A password needs to be secure. If you prevent copying and pasting of passwords, you force users to choose simple, easy-to-remember passwords. That is exactly what you want to avoid.
+
+Copying and pasting from a password manager is a much easier and safer way for users to enter a password. As explained by the UK National Cyber Security Centre in [Top tips for staying secure online](https://www.ncsc.gov.uk/collection/top-tips-for-staying-secure-online).
+
+## Related WCAG Success Criteria
+
+- [3.3.8 Accessible Authentication (Minimum)](https://www.w3.org/WAI/WCAG22/quickref/#accessible-authentication-minimum) Level AA (added in version 2.2)

docs/topics/forms/help/autocomplete.md

@@ -0,0 +1,11 @@
+---
+title: Provide help
+layout: default
+parent: Web forms
+nav_order: 7
+description: Filling out a form should be as easy as possible. How can you best help your user?
+---
+
+# Provide help filling out a form
+
+Filling out a form should be as easy as possible. How can you best help your user?

docs/topics/forms/help/avoid-input-masks.md

@@ -0,0 +1,28 @@
+---
+title: Provide valid values
+layout: default
+parent: Provide help
+nav_order: 4
+---
+
+# Provide valid values for a form field
+
+Provide valid values for an input field (for example, date or password requirements) in the description and not only in the placeholder.
+
+Also consider whether it is really important that, for example, a date of birth or phone number must meet exact input requirements.
+
+![Password requirements are shown in the description.](/assets/images/richtlijnen_formulier_voorkom-fouten_wachtwoord-english.png)
+
+![Examples of valid values for date of birth are shown in the description.](/assets/images/richtlijnen_formulier_voorkom-fouten_geboortedatum-english.png)
+
+
+## Resources
+
+### Related WCAG Success Criteria
+ - Helping users to understand better what they need to fill out is necessary to meet the WCAG success criterion [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/quickref/#labels-or-instructions) (Level AA).
+
+### Related info in this documentation
+
+- [Placeholders]({{site.baseurl}}/docs/topics/forms/input-label/placeholders/)
+- [Input field and description]({{site.baseurl}}/docs/topics/forms/descriptions/)
+- [Description with a fieldset]({{site.baseurl}}/docs/topics/forms/fieldsets/fieldset-descriptions/)