Improvements to picture-elements.markdown (#14144)

Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_lovelace/picture-elements.markdown

@@ -51,8 +51,23 @@ theme:
 
 ## Elements
 
+Elements are the active components (icons, badges, buttons, text, etc.) that overlay the image.
+
+There are several different element types that can be added to a Picture Elements card:
+
+- [State Badge](#state-badge)
+- [State Icon](#state-icon)
+- [State Label](#state-label)
+- [Service Call Button](#service-call-button)
+- [Icon](#icon-element)
+- [Image](#image-element)
+- [Conditional](#conditional-element)
+- [Custom](#custom-elements)
+
 ### State Badge
 
+This element creates a badge representing the state of an entity.
+
 {% configuration %}
 type:
   required: true
@@ -64,7 +79,7 @@ entity:
   type: string
 style:
   required: true
-  description: Position and style the element using CSS.
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
   type: map
   default: "position: absolute, transform: translate(-50%, -50%)"
 title:
@@ -85,7 +100,9 @@ double_tap_action:
   type: map
 {% endconfiguration %}
 
-### Icon representing an entity state
+### State Icon
+
+This element represents an entity state using an icon.
 
 {% configuration %}
 type:
@@ -158,12 +175,14 @@ double_tap_action:
   type: map
 style:
   required: true
-  description: Position and style the element using CSS.
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
   type: string
   default: "position: absolute, transform: translate(-50%, -50%)"
 {% endconfiguration %}
 
-### Label with state text
+### State Label
+
+This element represents an entity's state via text.
 
 {% configuration %}
 type:
@@ -205,13 +224,15 @@ double_tap_action:
   type: map
 style:
   required: true
-  description: Position and style the element using CSS.
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
   type: string
   default: "position: absolute, transform: translate(-50%, -50%)"
 {% endconfiguration %}
 
 ### Service Call Button
 
+This entity creates a button (with arbitrary text) that can be used to call a service.
+
 {% configuration %}
 type:
   required: true
@@ -231,13 +252,15 @@ service_data:
   type: map
 style:
   required: true
-  description: Position and style the element using CSS.
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
   type: string
   default: "position: absolute, transform: translate(-50%, -50%)"
 {% endconfiguration %}
 
 ### Icon Element
 
+This element creates a static icon that is not linked to the state of an entity. 
+
 {% configuration %}
 type:
   required: true
@@ -269,13 +292,15 @@ double_tap_action:
   type: map
 style:
   required: true
-  description: Position and style the element using CSS.
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
   type: string
   default: "position: absolute, transform: translate(-50%, -50%)"
 {% endconfiguration %}
 
 ### Image Element
 
+This creates an image element that overlays the background image.
+
 {% configuration %}
 type:
   required: true
@@ -333,7 +358,7 @@ aspect_ratio:
   default: "50%"
 style:
   required: true
-  description: Position and style the element using CSS.
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
   type: string
   default: "position: absolute, transform: translate(-50%, -50%)"
 {% endconfiguration %}
@@ -370,6 +395,25 @@ elements:
   type: list
 {% endconfiguration %}
 
+### Custom Elements
+
+The process for creating and referencing custom elements is the same as for custom cards.
+Please see the [developer documentation](https://developers.home-assistant.io/docs/frontend/custom-ui/lovelace-custom-card.html)
+for more information.
+
+{% configuration %}
+type:
+  required: true
+  description: 'Card name with `custom:` prefix (e.g., `custom:my-custom-card`)'
+  type: string
+style:
+  required: true
+  description: '[Position and style the element](#how-to-use-the-style-object) using CSS.'
+  type: string
+  default: "position: absolute, transform: translate(-50%, -50%)"
+{% endconfiguration %}
+
+
 ## Options For Exemptions
 
 {% configuration badges %}
@@ -379,27 +423,12 @@ user:
   type: string
 {% endconfiguration %}
 
-### Custom Elements
+## Notes on Element Attributes
 
-{% configuration %}
+### How to use the style object
-type:
-  required: true
-  description: 'Card name with `custom:` prefix (e.g., `custom:my-custom-card`)'
-  type: string
-style:
-  required: true
-  description: Position and style the element using CSS.
-  type: string
-  default: "position: absolute, transform: translate(-50%, -50%)"
-{% endconfiguration %}
 
-The process for creating and referencing custom elements is the same as for custom cards.
+Position and style your elements using [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS). More/other keys are also possible.
-Please see the [developer documentation](https://developers.home-assistant.io/docs/frontend/custom-ui/lovelace-custom-card.html)
+Note, the default style for most elements includes [translate](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/translate)(-50%, -50%), which means that the coordinates you provide will set the position of the center of the element.
-for more information.
-
-## How to use the style object
-
-Position and style your elements using [CSS](https://en.wikipedia.org/wiki/Cascading_Style_Sheets). More/other keys are also possible.
 
 ```yaml
 style:
@@ -410,7 +439,7 @@ style:
   "--paper-item-icon-color": pink
 ```
 
-## How to use state_image
+### How to use state_image
 
 Specify a different image to display based on the state of the entity.
 
@@ -420,7 +449,7 @@ state_image:
   "off": /local/living_room_off.jpg
 ```
 
-## How to use state_filter
+### How to use state_filter
 
 Specify different [CSS filters](https://developer.mozilla.org/en-US/docs/Web/CSS/filter)
 
@@ -430,7 +459,7 @@ state_filter:
   "off": brightness(50%) hue-rotate(45deg)
 ```
 
-## How to use click-and-hold
+### How to use click-and-hold
 
 If the option `hold_action` is specified, that action will be performed when the entity is clicked and held for half a second or more.
 
@@ -445,7 +474,9 @@ hold_action:
     brightness_pct: 100
 ```
 
-## Example
+## Examples
+
+### Example of icons, labels and buttons
 
 ```yaml
 type: picture-elements
@@ -495,7 +526,7 @@ elements:
       left: 10%
 ```
 
-## Images Example
+### Images Example
 
 ```yaml
 type: picture-elements
@@ -544,7 +575,7 @@ elements:
       width: 5%
 ```
 
-## Conditional Example
+### Conditional Example
 
 ```yaml
 type: picture-elements