Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update switch.mdx #21

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update switch.mdx #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/components/switch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,29 @@ When a switch represents multiple values that are not identical, the switch shou
<Guideline title="No partial state">
Switches can only be on or off. When a parent switch represents a group of switches, it should be turned off unless all of the switches are on (turning the parent switch on turns all of the switches on). To show a partial state, use checkboxes instead.
</Guideline>

## Content standards

A label for a switch describes a setting that is either on or off — two mutually exclusive states. Use a short description (1-3 words) of the setting. Try to include all necessary information in the label, but it’s OK to add clarifying text after to supplement if needed.

Keep in mind that when a user takes an action on a switch, that action will often affect other content in an experience. Think systematically to ensure that all labels are paralleling each other in their writing.

<Guideline title="Consider if the label should use a verb or a noun">
A switch shows a state of persistence for something — a noun or a proper noun — as either being “on” or “off.” A verb isn’t usually needed to communicate the thing being turned on or off, but there can be instances where phrasing the label as a verb can aid in clarity. Just try to keep switches consistently using either verbs or nouns if you have more than one of them in a single view.
</Guideline>

<Guideline title="Avoid using verb phrases related to a state of activity">
Avoid using verb phrases related to activity states in a switch label, such as “turn on” or “turn off.” A switch is naturally either in a state of being on or off — active or inactive — so repeating in the label that something is “on” or “off” is redundant and clutters an interface.
</Guideline>

<Guideline title="Use neutral tone">
Because switches are used for controls and utility, their labels are written in a neutral, utilitarian way. There’s no need for overly celebratory language.
</Guideline>

<Guideline title="Use “you” or “your” if needed to refer to the user directly">
adidick marked this conversation as resolved.
Show resolved Hide resolved
Describe switches objectively by using only the names of features or settings, or what those features and settings will do. In the case where it’s necessary to refer to a user directly, do so sparingly and use the second person “you/your.” We aim to be conversational and talk to the user — not as them.
</Guideline>

<Guideline title="Use sentence case">
Labels for switches are written in sentence case unless they contain words that are branded terms.
</Guideline>