DEV Community: Matt Priour

An Introduction to High Contrast Accessibility

Matt Priour — Wed, 19 Jan 2022 21:00:30 +0000

Background

High contrast mode is a special rendering mode on Windows that applies forced colors and simplifies visual elements throughout the entire platform. This mode is an accessibility feature of Windows and used by people with low vision or visual acuity issues. High contrast mode severely changes the way that websites are rendered on all Windows browsers.

The following CSS properties are overwritten by the theme's system colors:

color
background-color
text-decoration-color
text-emphasis-color
border-color
outline-color
column-rule-color
-webkit-tap-highlight-color
SVG fill attribute
SVG stroke attribute

Additionally, the following CSS properties are set to none:

box-shadow
text-shadow
background-image (unless it is a URL)

References

Rendering native elements and system colors

Default	HC Chrome/Edge	HC Firefox

Rendering specifics

System colors

Chromium-based browsers (Edge and Chrome) and Firefox both respect the forced color and style adjustments of Windows in high contrast mode. Both browsers types use the system colors rather than user specified colors for most elements. The system colors names and specification is often seen as deprecated, but that is the recommended way to specify a color and have it work in high contrast mode. The table below shows the system color name and its purpose. The system color names are case insensitive. Canvas and CanvasText are meant to replace Window and WindowText. However, all of them are currently supported in both browser types on Windows. System colors are not set in CSS but rather set in the Windows theme controls and then can be used as colors in CSS.

System Color	Purpose
ActiveText	Text of active links
ButtonBorder	Base border color of controls
ButtonFace	Background color of controls
ButtonText	Foreground color of controls
Canvas	Background of application content or documents
CanvasText	Foreground color in application content or documents
Field	Background of input fields
FieldText	Text in input fields
GrayText	Foreground color for disabled items (e.g. a disabled control)
Highlight	Background of selected items
HighlightText	Foreground color of selected items
LinkText	Text of non-active, non-visited links
VisitedText	Text of visited links
Window	Window background
WindowText	Text in windows

Media queries

A simple media query can determine if the page is being rendered in high contrast mode or not. The recommended way to determine this is to use the forced-colors media query. The deprecated -ms-high-contrast query still works on Edge, but is expected to be removed "soon". If you are still supporting Internet Explorer or Legacy Edge then you would want to use this deprecated media query. For example, this snippet would set the color and background-color of an element with a selected class to be the inverse of a "normal" element on the page only when the system is in high contrast mode.



@media (forced-colors: active) {
   .selected {
      background-color: CanvasText;
      color: Canvas;
   }
}

There is an escape hatch that should be used very sparingly. Setting a CSS selector to forced-color-adjust: none opts out of the high contrast color mode. While it may seem tempting to do this where ever high contrast mode is causing UI problems, it is not a recommended practice. Users have turned on high contrast mode for a reason. You should work with it if at all possible.

UPDATE - `forced-colors` emulation now available

As of Chromium 98 (both Chrome 98 and Edge 98) you can set forced-colors: active in the "Rendering" pane of DevTools.

Browser differences

While both browser types render high contrast, there are some obvious differences between the browsers. The most obvious difference is in rendering SVGs with a fill of currentColor. Chrome and Edge on Windows have a specific user-agent style for SVG that sets forced-color-adjust: none. This allows one to easily set the color on an SVG in those browsers. However, there is no guaranty that the SVG will have appropriate contrast or even be visible. On Firefox, SVG's currentColor is forced to the WindowText/CanvasText color. This ensures that the icon is visible, but eliminates any color information that the SVG is expected to convey.

Another, less obvious difference is that Chrome and Edge also set the value of the prefers-color-scheme in high contrast mode depending on the Window/Canvas color used by the high contrast theme. High contrast themes with backgrounds below a certain luminosity get prefers-color-scheme: dark while background values above that threshold get prefers-color-scheme: light set, regardless of other system preferences. This is not the case in Firefox, which follows the system preference and defaults to prefers-color-scheme: light regardless of the actual theme colors. Because of the way that Firefox overwrites SVG currentColor along with the other rendering changes, the value of prefers-color-scheme has little impact on what the user sees. In Chrome and Edge, the primary difference is also in SVG's. Since they maintain the CSS specified color for currentColor, if there are different color values depending on the prefers-color-scheme value then those colors are seen by the user.

Challenges

The most notable challenges with high contrast mode are that box-shadow and background-color compute to none. This means that any component attempting to show state or other information using either of these properties will not show properly if at all. The difference in the way that SVG's are rendered causes issues with several components and creates significant differences between Firefox and Chrome or Edge browsers.

Opportunities

Few developers or quality assurance engineers test for high contrast issues. There are not currently any good automated tests or tools for setting forced-colors to active and looking for visual regressions. This really has to be done by someone manually, at this time. Spending even a small amount of time reviewing your UI for high contrast issues and fixing the highest impact items will go a long way to distinguish your product from others for high contrast users.

Generating strongly typed reducer actions for React

Matt Priour — Thu, 30 Sep 2021 17:13:25 +0000

Using reducers in the React Context api leaves a lot of room for error, even when using TypeScript. A reducer takes a single argument and returns a state. The common format for the argument is an object with an action property and a payload or value property. The action's value is generally a string such as setTitle. In the case of action:'setTitle', the value would then be the title you want to set on the state object. The problems with this approach are:

You have to look back at the reducer to see what the correct spelling and valid values of action are.
There is no type checking of the values that are linked with the action.

This article assumes that you have a basic familiarity with React, useReducer, and TypeScript.

If you just want to skip to the code, you can see the final working version on this TS Playground

The optimal solution would allow us to define the state object and its valid values, then TypeScript would provide code completion and type validation for the actions and values passed to the reducer function. A less optimal solution would be to do something similar to Redux and create a series of action functions that are strongly typed and wrap calls to the reducer. Then in your code you only use action functions and never call the reducer directly. However, TypeScript's mapped types can make that extra layer unnecessary.

Let's take a simple state type

type ItemState = {
    id: string,
    title: string,
    description?: string,
    quantity: number
}

We want to create a reducer that knows that setId and setQuantity are valid actions but setID and setQty are not. It should also type check so that the value paired with setQuantity is a number and not a Date or string.

The first step is to create a generic utility type called Setters that takes another type and produces "setPropertyName" style function names for each property on that type.

type Setters<T> = {
    [P in keyof T as `set${Capitalize<string & P>}`]-?: T[P]
}

Capitalize is a built in string modifier that capitalizes the passed string. The -? means that we remove the optional attribute of any property. T[P] gives us the type of each property of the passed in generic type.

We then use the Setters utility to generate a setters type for our state type.

type ItemSetters = Setters<ItemState>
/* 
This is equivalent to writing out:
type ItemSetters = {
    setId: string,
    setTitle: string,
    setDescription: string,
    setQuantity: number
}
*/

Now let's use another mapped type to create a map of action objects with valid action names and value types.

type ActionsMap = {
    [S in keyof ItemSetters]: {
        action: S,
        value: ItemSetters[S]
    }
}
/* 
This results in:
type ActionsMap = {
    setId: {
        action: 'setId',
        value: string
    }, ...
    setQuantity: {
        action: 'setQuantity',
        value: number
    }
}
*/

Now we need to extract the action/value objects out of ActionsMap and use the union of those objects as our action type in our reducer.

type ItemActions = ActionsMap[keyof ActionsMap]

const itemReducer = (state: ItemState, action: ItemActions) : ItemState => { return state }

The itemReducer doesn't actually do anything yet. We need to fill it out with the reducer logic. What you can't see here in the code sample is the ease of doing this. With the strongly typed ItemActions we will have code completion on the switch case statements we will write and type validation when we use the reducer.

Here is the filled out reducer function:

const itemReducer = (state: ItemState, action: ItemActions) : ItemState => {
    switch(action.action) {
        case 'setId':
            return {...state, id: action.value};
        case 'setTitle':
            return {...state, title: action.value};
        case 'setDescription':
            return {...state, description: action.value};
        case 'setQuantity':
            return {...state, quantity: action.value};
        default:
            console.error(`Action of ${action.action} is not supported`);
     }
     return state;
}

Unfortunately our default statement has an error:

Property 'action' does not exist on type 'never'.

That error occurs because we covered all possible valid cases. In order to account for a possible error, we can add a dummy action type. ItemActions becomes:

type ItemActions = 
    ActionsMap[keyof ActionsMap] | {action: 'other'}

Using the mapped types with string template literals approach really shows its power when you need to add another property to the state. For example, let's add a boolean 'backordered' property. We just have to add 3 total lines of code.

type ItemState = {
    ...
    quantity: number,
    backordered: boolean
}

...

    switch(action.action) {
    ...
    case 'setQuantity':
        return {...state, quantity: action.value};
    case 'setBackordered':
        return {...state, backordered: action.value};
    ...

Even better than the developer experience when adding or removing properties from state, is the experience of using the reducer. While it can't easily be shown in code snippets, the auto-complete and type validation is a game changer. No longer do you have to look back at the reducer to determine the correct spelling and what exactly type of value it is expecting. For example:

/* GOOD */
...
    dispatch({
        action: 'setQuantity',
        value: 5
    })
...

/* ERROR */
...
    dispatch({
        action: 'setQuantity',
        value: 'none'
   })
...

Hope this approach helps you when creating and using reducers. Once I figured it out, it has saved me plenty of development time and frustration.

Here is the final TypeScript annotated reducer:

type ItemState = {
    id: string,
    title: string,
    description?: string,
    quantity: number,
    backordered: boolean,
}

type Setters<T> = {
    [P in keyof T as `set${Capitalize<string & P>}`]-?: T[P]
}

type ItemSetters = Setters<ItemState>

type ActionsMap = {
    [S in keyof ItemSetters]: {
        action: S,
        value: ItemSetters[S]
    }
}

type ItemActions = 
    ActionsMap[keyof ActionsMap] | {action: 'other'}

const itemReducer = (state: ItemState, action: ItemActions) : ItemState => {
    switch(action.action) {
        case 'setId':
            return {...state, id: action.value};
        case 'setTitle':
            return {...state, title: action.value};
        case 'setDescription':
            return {...state, description: action.value};
        case 'setQuantity':
            return {...state, quantity: action.value};
        case 'setBackordered':
            return {...state, backordered: action.value};
        default:
            console.error(`Action of ${action.action} is not supported`);
     }
     return state;
}