Accessibility settings

Notes for developers

In order to support the WCAG 2.3.3 accessibility guideline, all CSS and JavaScript animation/motion should be provided as an enhancement.

When JavaScript runs, if the user has not chosen to disable animations then a CSS class (u-animation) is added to the html element and a global JavaScript variable (FRAMEWORK.animation) is set to true that can then be used to enable animations on your components.

The following example shows how animation would be applied, firstly using CSS and secondly using JavaScript.

.a-example {
	transform: scale(1);
}
.a-example:hover,
.a-example:focus {
	transform: scale(2);
}
.u-animation .a-example {
	transition: transform .35s;
}

if ( FRAMEWORK.animation ) {
	element.slideDown( 350 );
} else {
	element.show();
}

The Framework also has some standard animation speeds (in milliseconds) available for use which will be automatically set to 0 if animation has been disabled. These can be used to keep code using animations more manageable.

FRAMEWORK.timings = {
	'current' : {
		t100ms : 100,
		t150ms : 150,
		t200ms : 200,
		t250ms : 250,
		t300ms : 300,
		t350ms : 350,
		t500ms : 500,
		t1s : 1000
	}
};

Between v4.3.0 and v4.8.0 the timings available were:

FRAMEWORK.timings = {
	'current' : {
		t150ms : 150,
		t350ms : 350,
		t500ms : 500,
		t1s : 1000
	}
};

As of v5.0.0 the jQuery.fx.off variable will be set on page load and if the animation setting is changed via the accessibility settings component, if jQuery is already present on the page. If your module loads jQuery as a dependancy ensure that the jQuery.fx.off variable is set appropriately when your module runs to ensure animations are not used when they shouldn't.

Aria usage for errors and help text

To aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occured, some additional aria attributes are now recommended to be applied across all form fields/rows.

All form row help, explanatory text, form row instructions and form row errors must have a unique id assigned to them and be appropriately linked to either the individual form input or the form row using aria-describedby. This ensures that the help text is read out immediately on focus of the form input/fieldset. When there is more that one item that requires referencing within the aria-describedby attribute the id values must be supplied in the form of a space separated list. For example if there is an error with id of 'err1' and help text with id of 'help1' the value for the aria-describedby attribute would be 'err1 help1'.

All inline form error messages should start with the hidden text 'Error: ' so that when read by out by a screen reader it is immediately clear that the text being read is an error message.

All erroring form fields (or fieldset if a group or radios/checkboxes) must have aria-invalid="true" set on them, ensuring that when a user focus' on an errored form field, the field will be announced as invalid, so the user is then aware that there in an issue that requires fixing.

When linking help or errors, or even adding aria-invalid to the markup careful consideration must be taken as to where it is most appropriate to apply the value. The following rules should be used to decide where the attribute(s) should be applied.

• Single form field - All attributes should be applied directly to that form field
• Group of form fields but only one in error or help text applies to only one - Apply the attribute(s) to the only field in error or where the help text applies
• Group of form field where all in error or the help text applies to all - Apply the attribute(s) to the groups surrounding fieldset (form row)

There may situations where more than one of these rules applies to the overall form row for example a date range where the instruction text applies to both fields so should be linked to the fieldset for the date range but one of the two fields is in error so the error should be linked to just that field not to the fieldset.

Controling the accessibility settings component programatically

Accessibility settings can be controlled programatically to turn animation preference on and off. The following method is available for use:

For example:

document.addEventListener( 'frameworkready', function () {
	FRAMEWORK.require([ 'blocks/o-accessibility-settings' ], function ( oAccessibilitySettingsModule ) {
		var oAccessibilitySettingsEl = document.querySelector( '#accessibilitySettingsId' ),
			oAccessibilitySettingsInstance = oAccessibilitySettingsModule.initInstance( oAccessibilitySettingsEl );		oAccessibilitySettingsInstance.setState( 'off' );
	});
});

Changing locale settings

The notification message text can be updated for a particular locale.

en: {
	oAccessibilitySettings : {
		error : 'The ability to store your accessibility preferences for this website requires the use of cookies. Please enable cookies for this site so that we can save your preference, or use the prefer reduced motion setting on your device.',
		reduced : 'Animations and transitions have been automatically disabled for this website in accordance with your device settings.',
		success : 'Your preferences have been updated successfully.',
	},
},

For more information on this, see our page on how to change locale settings within JavaScript.

---

Notes for testers

• Ensure that the selected option is visually clear.
• Ensure that any notification messages (error or submission) are clear and read by screen readers.
• Ensure that an error notification message is displayed and the submit button is disabled when users have not accepted or disabled cookies.

---

Classes overview

The following table gives you a quick overview of the CSS classes that can be applied.

---

Keyboard operations

TAB

Tabbing to an accessibility option or button, they will become it clearly visually different so that the focus point on the page is obvious to the user.

SPACE or ENTER

With focus on the submit button, pressing SPACE or ENTER will trigger the selected options to be saved to a cookie and notification displayed.