diff --git a/docs/components/switch.mdx b/docs/components/switch.mdx index 3f37b7ce..511f48a7 100644 --- a/docs/components/switch.mdx +++ b/docs/components/switch.mdx @@ -54,3 +54,29 @@ When a switch represents multiple values that are not identical, the switch shou 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. + +## 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. + + +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. + + + +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. + + + +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. + + + +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. + + + +Labels for switches are written in sentence case unless they contain words that are branded terms. +