From 11be726def354408b9618c0c2788e412efd2a0d2 Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Wed, 20 Mar 2024 15:19:51 +0100
Subject: [PATCH] Cards: add categories and expand on introduction (#31947)

Co-authored-by: Franck Nijhof <git@frenck.dev>
---
 source/dashboards/cards.markdown | 41 ++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/source/dashboards/cards.markdown b/source/dashboards/cards.markdown
index fda6771de95..ae3936ff1f3 100644
--- a/source/dashboards/cards.markdown
+++ b/source/dashboards/cards.markdown
@@ -1,6 +1,6 @@
 ---
 title: "Cards"
-description: "Cards."
+description: "Introduction to the role of cards on the dashboard and how to add a card."
 ---
 
 Each dashboard is made up of cards.
@@ -10,7 +10,32 @@ Each dashboard is made up of cards.
 Screenshot of the masonry view with different types of cards.
 </p>
 
-There are several built-in card types, each with their own configuration options.
+## Card categories
+
+There are several different card types, each with their own configuration options. They can be categorized in terms of their function:
+
+- **Specific to a device type or service**: alarm, light, humidifier, thermostat, plant status, media control, weather forecast, shopping list, map, logbook, and calendar card
+- **Grouping other cards**: vertical stack, horizontal stack, and grid card
+- **Logic function**: conditional and entity filter card
+- **Display generic data**: sensor, history graph, statistic, statistics graph, energy, gauge, and webpage card
+- **Control devices and entities**: button and entity card
+- **Display data and control entities**: area, picture elements, and picture glance card
+
+## Card actions, features, header and footer widgets
+
+Some cards have support for [tap actions](/dashboards/actions/). These actions define what will happen when you tap or hold on an object within a card.
+
+Some cards have support for [features](/dashboards/actions/). These widgets add quick controls to the card. Supported features depend on the card and entity capabilities. Multiple features can be added to a single card.
+
+<p class='img'><img src='/images/dashboards/features/screenshot-tile-feature-grid.png' alt="Screenshot of tile cards with features.">
+Screenshot of tile cards with features.
+</p>
+
+Some cards have support for [header and footer widgets](/dashboards/header-footer/). These widgets fill up the entire available space in a card.
+
+<p class='img'><img src='/images/dashboards/header-footer/screenshot-picture-buttons.png' alt="Screenshot of an entities card with a picture header.">
+Screenshot of an entities card with a picture header and buttons footer.
+</p>
 
 ## Adding cards to your dashboard
 
@@ -18,7 +43,7 @@ There are several built-in card types, each with their own configuration options
 
 2. Choose one of the two methods to add cards to a dashboard:
 
-{% details "Using the Add Card button" %}
+{% details "Using the Add card button" %}
 
 1. In the bottom right, select **Add card**.
 
@@ -53,7 +78,13 @@ Another way to add entities to a dashboard is to use the **Device** page.
 
 ## Related topics
 
-- For a list of available card types and more detailed documentation, refer to the **Card types** section in the side navigation.
 - [Views](/dashboards/views/)
 - [Introduction to dashboards](/dashboards/)
-- [Take control of the default dashboard](/dashboards/#get-started-with-your-own-dashboard)
\ No newline at end of file
+- [Take control of the default dashboard](/dashboards/#get-started-with-your-own-dashboard)
+
+### Cards
+
+- For a list of available card types and more detailed documentation, refer to the **Card types** section in the side navigation.
+- [Card tap actions](/dashboards/actions/)
+- [Card features](/dashboards/actions/)
+- [Card header and footer widgets](/dashboards/header-footer/)
\ No newline at end of file