Device class: standardize intro paragraph (#32981)

* Device class: standardize intro paragraph

* Humidifier device classes: add screenshot

* Apply suggestions from code review

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>

* Fix typo

* Rephrase

* Update source/_integrations/humidifier.markdown

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>

---------

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>

source/_integrations/binary_sensor.markdown

@@ -27,25 +27,21 @@ a binary sensor to detect room occupancy. Other binary sensors can be created
 manually using the [template integration](/integrations/template/)
 or using an [input boolean helper](/integrations/input_boolean).
 
-
 {% include integrations/building_block_integration.md %}
 
 ### Device class
 
-Knowing a sensor is binary impacts how the sensor's current state may be
-represented in Home Assistant's UI (see [Dashboards](/dashboards/)). Opposing states
-may be given different icons, colors, and value labels to highlight a particular
-state over the other. This is set by the binary sensor's device class.
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
 
-Here are a few examples of this representation in the UI:
+The screenshot shows a few examples of different device classes for binary sensors:
 
 ![List of binary sensors](/images/screenshots/binary_sensor_classes_icons.png)
+
 Example of various device classes icons in `on` and `off` state. The on image
-in this example has `state_color: true` specified in the Entities card
+in this example has `state_color: true` specified in the entities card
 configuration to receive the icon coloring.
 
-The full list of supported binary sensor device classes is below
-*(note: these may also be modified in the [customizing section](/docs/configuration/customizing-devices)).*
+The following device classes are supported for binary sensors:
 
 - **None**: Generic on/off. This is the default and doesn't need to be set.
 - **battery**: `on` means low, `off` means normal

source/_integrations/button.markdown

@@ -9,6 +9,11 @@ ha_domain: button
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 A button {% term entity %} is an entity that can fire an {% term event %} / trigger an {% term action %} towards
@@ -55,14 +60,17 @@ This service can be called to trigger a button press for that entity.
 
 ## Device class
 
-The way these buttons are displayed in the frontend can be modified in the [customize section](/docs/configuration/customizing-devices/).
-The following device classes are supported for buttons:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The screenshot shows different icons representing different device classes for buttons:
 
 <p class='img'>
 <img src='/images/screenshots/button_classes_icons.png' />
 Example of device class icons.
 </p>
 
+The following device classes are supported for buttons:
+
 - **None**: Generic button. This is the default and doesn't need to be set.
 - **identify**: The button is used to identify a device.
 - **restart**: The button restarts the device.

source/_integrations/cover.markdown

@@ -9,6 +9,11 @@ ha_codeowners:
   - '@home-assistant/core'
 ha_domain: cover
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 Home Assistant can give you an interface to control covers such as rollershutters, blinds, and garage doors.
@@ -17,7 +22,18 @@ Home Assistant can give you an interface to control covers such as rollershutter
 
 ## Device class
 
-The way these {% term sensors %} are displayed in the {% term frontend %} can be modified in the [customize section](/docs/configuration/customizing-devices/). The following device classes are supported for covers:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The screenshot shows different icons representing different device classes for covers:
+
+<p class='img'>
+<img src='/images/screenshots/cover_classes_icons.png' />
+List of cover examples.
+</p>
+
+Example of various device classes icons in `open` and `closed` state. The open image in this example has `state_color: true` specified in the Entities card configuration to receive the icon coloring.
+
+The following device classes are supported for covers.
 
 - **None**: Generic cover. This is the default and doesn't need to be set.
 - **awning**: Control of an awning, such as an exterior retractable window, door, or patio cover.
@@ -31,20 +47,15 @@ The way these {% term sensors %} are displayed in the {% term frontend %} can be
 - **shutter**: Control of shutters, which are linked slats that swing out/in to covering an opening or may be tilted to partially cover an opening, such as indoor or exterior window shutters.
 - **window**: Control of a physical window that opens and closes or may tilt.
 
-Here are a few examples of this representation in the UI:
-
-![List of cover examples](/images/screenshots/cover_classes_icons.png)
-Example of various device classes icons in `open` and `closed` state. The open image in this example has `state_color: true` specified in the Entities card configuration to receive the icon coloring.
-
 ## Services
 
 ### Cover control services
 
 Available services: `cover.open_cover`, `cover.close_cover`, `cover.stop_cover`, `cover.toggle`, `cover.open_cover_tilt`, `cover.close_cover_tilt`, `cover.stop_cover_tilt`, `cover.toggle_tilt`
 
-| Service data attribute | Optional | Description |
-| ---------------------- | -------- | ----------- |
-| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all.
+| Service data attribute | Optional | Description                                                                                          |
+| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `entity_id`            | yes      | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all. |
 
 #### Automation example
 
@@ -63,10 +74,10 @@ automation:
 
 Set cover position of one or multiple covers.
 
-| Service data attribute | Optional | Description |
-| ---------------------- | -------- | ----------- |
-| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all.
-| `position` | no | Integer between 0 and 100.
+| Service data attribute | Optional | Description                                                                                          |
+| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `entity_id`            | yes      | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all. |
+| `position`             | no       | Integer between 0 and 100.                                                                           |
 
 #### Automation example
 
@@ -87,10 +98,10 @@ automation:
 
 Set cover tilt position of one or multiple covers.
 
-| Service data attribute | Optional | Description |
-| ---------------------- | -------- | ----------- |
-| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all.
-| `tilt_position` | no | Integer between 0 and 100.
+| Service data attribute | Optional | Description                                                                                          |
+| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `entity_id`            | yes      | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all. |
+| `tilt_position`        | no       | Integer between 0 and 100.                                                                           |
 
 #### Automation example
 

source/_integrations/event.markdown

@@ -9,6 +9,11 @@ ha_domain: event
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 Events are signals that are emitted when something happens, for example, when a user presses a physical button like a doorbell or when a button on a remote control is pressed.
@@ -77,6 +82,8 @@ When creating automations in the automation editor in the UI, the event types ar
 
 ## Device classes
 
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
 The following device classes are supported by event entities:
 
 - **None**: Generic event. This is the default and doesn't need to be set.

source/_integrations/humidifier.markdown

@@ -10,6 +10,11 @@ ha_codeowners:
   - '@home-assistant/core'
   - '@Shulyaka'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 The `humidifier` integration is built for the controlling and monitoring of humidifiers, dehumidifiers, and hygrostat devices.
@@ -18,7 +23,14 @@ The `humidifier` integration is built for the controlling and monitoring of humi
 
 ## Device class
 
-The way sensors are displayed in the {% term frontend %} can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, if the device class is set to humidifier, the UI shows "Humidifying". If it is set to dehumidifier, it shows "Drying".
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The screenshot shows different text and UI for different device classes for humidifiers:
+
+<p class='img'>
+<img src='/images/screenshots/humidifier_device_class.png' />
+Humidifier device classes.
+</p>
 
 The following device classes are supported for humidifiers:
 

source/_integrations/media_player.markdown

@@ -9,6 +9,11 @@ ha_domain: media_player
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 Interacts with media players on your network.
@@ -180,7 +185,9 @@ Allows to group media players together for synchronous playback. Only works on s
 
 ### Device class
 
-The way media players are displayed in the frontend can be modified in the [customize section](/getting-started/customizing-devices/). The following device classes are supported for media players:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The following device classes are supported for media players:
 
 - `tv`: Device is a television type device.
 - `speaker`: Device is a speaker or stereo type device.

source/_integrations/number.markdown

@@ -10,6 +10,11 @@ ha_codeowners:
   - '@home-assistant/core'
   - '@Shulyaka'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 Keeps track on `number` entities in your environment, their state, and allows you to control them. This integration allows other integrations to get a value input from user within a range.
@@ -20,7 +25,9 @@ If you are looking for a way to create a number entity, please take a look at th
 
 ## Device class
 
-The type of data a number represents impacts how it is displayed in the frontend. This is controlled by the number's device class designation. Built-in numbers and many created from an integration will have this designation predefined. Those can be modified in the [customize section](/docs/configuration/customizing-devices/). When manually creating a new number the device class may be optionally assigned. A full list of available number device classes is below:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The following device classes are supported for numbers:
 
 - **None**: Generic number. This is the default and doesn't need to be set.
 - **apparent_power**: Apparent power in VA.

source/_integrations/sensor.markdown

@@ -9,6 +9,11 @@ ha_domain: sensor
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 Sensors are a basic integration in Home Assistant. They monitor the states and conditions of a variety of entities. An entity can be many things. This can include a physical device like a motion sensor that reports the battery level, a web service that retrieves the weather temperature, a built-in function that calculates the sun's elevation relative to your GPS position, or even a custom sensor you may have created to report the free space on your laptop. These are all _things_ reporting different types of information.
@@ -17,7 +22,16 @@ Some of these sensors are built-in to Home Assistant, some are created automatic
 
 ## Device class
 
-The type of data a sensor returns impacts how it is displayed in the frontend. This is controlled by the sensor's device class designation. Built-in sensors and many created from an integration will have this designation predefined. Those can be modified in the [customize section](/docs/configuration/customizing-devices/). When manually creating a new sensor the device class may be optionally assigned. A full list of available sensor device classes is below:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The screenshot shows different icons representing different device classes for sensors:
+
+<p class='img'>
+<img src='/images/screenshots/sensor_device_classes_icons.png' />
+Example of various device class icons for sensors.
+</p>
+
+The following device classes are supported for sensors:
 
 - **None**: Generic sensor. This is the default and doesn't need to be set.
 - **apparent_power**: Apparent power in VA.
@@ -71,8 +85,3 @@ The type of data a sensor returns impacts how it is displayed in the frontend. T
 - **water**: Water consumption in L, gal, m³, ft³, or CCF
 - **weight**: Generic mass in kg, g, mg, µg, oz, lb, or st
 - **wind_speed**: Wind speed in Beaufort, ft/s, km/h, kn, m/s, or mph
-
-<p class='img'>
-<img src='/images/screenshots/sensor_device_classes_icons.png' />
-Example of various device class icons for sensors.
-</p>

source/_integrations/switch.markdown

@@ -11,6 +11,11 @@ ha_platforms:
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 Keeps track which switches are in your environment, their state and allows you to control them.
@@ -22,10 +27,12 @@ Keeps track which switches are in your environment, their state and allows you t
 
 ## Device class
 
-The way these switches are displayed in the frontend can be modified in the [customize section](/docs/configuration/customizing-devices/). The following device classes are supported for switches:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+ The following device classes are supported for switches:
 
 - **None**: Generic switch. This is the default and doesn't need to be set.
-- **outlet**: This switch, switches a power outlet.
+- **outlet**: A switch for a power outlet.
 - **switch**: A generic switch.
 
 ## Use the services
@@ -36,6 +43,6 @@ In the frontend open the sidebar. At the bottom, under **Developer Tools**, clic
 {"entity_id":"switch.livingroom_pin2"}
 ```
 
-| Service data attribute | Optional | Description |
-| ---------------------- | -------- | ----------- |
-| `entity_id`            |      no  | String or list of strings that point at `entity_id`s of switches. To target all switches, set `entity_id` to `all`.
+| Service data attribute | Optional | Description                                                                                                         |
+| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `entity_id`            | no       | String or list of strings that point at `entity_id`s of switches. To target all switches, set `entity_id` to `all`. |

source/_integrations/update.markdown

@@ -8,6 +8,11 @@ ha_domain: update
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 An update {% term entity %} is an entity that indicates if an update is available for a
@@ -51,8 +56,9 @@ information on the update state:
 
 ## Device class
 
-The way these update entities are displayed in the frontend depend on their
-device classes. The following device classes are supported for switches:
+The device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The following device classes are supported for update entities:
 
 - **`None`**: A generic software update. This is the default and doesn't need
   to be set.

source/_integrations/valve.markdown

@@ -9,6 +9,11 @@ ha_codeowners:
   - '@home-assistant/core'
 ha_domain: valve
 ha_integration_type: entity
+related:
+  - docs: /docs/configuration/customizing-devices/
+    title: Customizing devices
+  - docs: /dashboards/
+    title: Dashboard
 ---
 
 The valve entity in Home Assistant provides an interface to control valves such as water, gas, or air valves.
@@ -17,7 +22,9 @@ The valve entity in Home Assistant provides an interface to control valves such
 
 ## Device class
 
-You can change the device class of the valve in the [customize section](/docs/configuration/customizing-devices/). Valves support the following device classes:
+A device class defines how the entity is represented on the [dashboard](/dashboards/). This can be modified in the [customize section](/docs/configuration/customizing-devices/). For example, different states may be represented by different icons, colors, or text.
+
+The following device classes are supported for valves:
 
 - **None**: Generic valve. This is the default and doesn't need to be set.
 - **water**: Valve that controls the flow of water through a system.