We recently component guidelines to the docs, a herculean effort by our design team that migrated existing content from the DSG and involved the creation of a huge amount of new content. Now that this content has been written and included in the docs, we should review component pages for consistency and clarity of structure and language, to ensure that our users have a smooth and consistent reading experience across all components.

Areas for review

Component naming and casing

A decision on how to handle this will be made in T361285. We are mixing casing of component names (text input vs. TextInput) and component properties (primary progressive button vs. Primary Progressive Button). This can be confusing, especially because capitalization changes the meaning of some things, and is needed to differentiate between things that have the same name, such as the Button component and the button element.

Pluralization

We sometimes mix singular and plural, such as in this example:

Avoid using buttons when:

• The action is to navigate the user to a new resource, which would take them away from the current context. In such cases, consider Link instead.

Instead, we should err on the side of referring to a single component in most cases (e.g. replace "buttons" with "a Button" in the example above). The exception will be components that are usually used in groups, such as Radios or MenuItems. We should still use singular when referring to a single component usage, but may use plural when talking about using a group of components.

Dos and don'ts

We often us "dos and don'ts" on component pages to list out things you should and should not do. The design of these sections is meant to start with a "Do:" or "Don't" label, then a list of items that are assumed ot start with that word. For example:

Sometimes, the text in the list does not follow this structure, which could be confusing. These examples should be udpated to flollow the right pattern. For example:

In the first example, the "Do" text does not sound like it starts with the word "Do." In the second example, the "Don't" text does not follow this structure either.