import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import {
  Button,
  Card,
  CardSection,
  NextButton,
  Text,
  Link,
  Box,
  UnstyledButton,
  TertiaryButton,
  TextInput,
} from '../..';
import { Radio } from '.';
import { FieldSet } from './field-set';

<Meta title="Components/Inputs/Accessibility Tips" />

# Using Inputs Accessibly

Inputs are a common source of accessibility problems if not done correctly. Here are some tips to avoid creating issues.

## Avoid Making Your Own Inputs

A lot of thought and testing has gone into making sure Patchwork's inputs work with screen readers, and we're constantly improving them over time. We are at a point where most form controls have a corresponding patchwork implementation; please use them.

If you get a design that calls for a new take on a `TextBox` for example, reach out to the design team and the patchwork team in slack to make sure it's not a mistake and gets implemented correctly.

## Prefer UX Flows Composed from Basic, Familiar Input Types

If you get a design with some wildly novel input control, you will need to research and implement the correct [ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/) for the UX interaction its trying to emulate. This can be tricky to get right and is likely not worth the effort in many cases. Ask the designer if the functionality can be achieved with standard controls instead. Remember that accessibility is UX too, and that optimizing UX for some users can make things worse for others.

Basic form controls paradigms are battle tested and familiar, and should be preferred in designs.

## Always Supply a Descriptive Label

Screen readers need a descriptive label so that their users can understand what information any input is looking for. Most patchwork inputs expose a required `label` property for this purpose.

**Tips:**

> Never omit or specify an empty string for a required `label` property. Doing so creates an accessibility bug.

> If your project supports i18n, use translated strings for the label. Most label props have the `TranslatedContent` type, which can accept either `String`, or `FormattedMessage` instances.

### Label Render Modes

#### Default

By default, labels are rendered above the input, using styling that matches our internal designs.

<Canvas>
  <TextInput label="Label" placeholder="Placeholder" />
</Canvas>

#### Hidden

There may be cases where the design calls for an input but does not have a visible text label present. In this case, you must still specify the label property as above, but you can also supply the `hideLabel` attribute to hide it visually. Screen readers can still pick it up but it will not affect the visual designs.

In this case you will most likely want to specify a `placeholder` for sighted users.

<Canvas>
  <TextInput label="Label" hideLabel placeholder="Placeholder" />
</Canvas>

#### Floating

Some inputs support a mode where the placeholder and label are combined into an animated label that 'floats up' when you interact with the control:

<Canvas>
  <TextInput label="Name" floatLabel />
</Canvas>

## Use Placeholders Judiciously

Placeholders are a source of controversy in accessibility circles.

**Placeholders are ignored by most screen readers**. Inputs that use placeholders as their only descriptive text (i.e. no label) provide visually impaired users with no information as to what the input is asking for.

If you have a design with an input that has a placeholder and no label, specify a label anyway and use the `hideLabel` prop to hide it visually.

<Canvas>
  <TextInput
    label="Hidden label"
    hideLabel
    placeholder="I'd better have a hidden label too!"
  />
</Canvas>

**Placeholders that provide an example value are confusing to some users**. Users are often confused with labels that look like correct values and think the input is filled in when it's not.

<Canvas>
  <TextInput
    error="Bad: this placeholder looks like a real value, which is confusing."
    label="Phone number"
    placeholder="555 555 5555"
  />
</Canvas>

The main use case for a placeholder is to provide instructions to **sighted** users when you're using the hidden label pattern for screen readers.
