From abdc95e8a1123ec87c9ca92d4e93639f7ce0e0e5 Mon Sep 17 00:00:00 2001
From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com>
Date: Wed, 3 Jun 2026 12:17:35 -0500
Subject: [PATCH] docs: add automation difficulty pills + stepping-stone boxes
(#920)
Introduce a 1-5 setup-difficulty rating on automation pages (Starter,
Easy, Moderate, Advanced, Pro) shown as a colored pill under the H1,
and an optional same-product stepping-stone box that links easier
automations at the top of harder pages.
- Pill + stepping-stone styles centralized in docs/stylesheets/extra.css
- Applied pills to the 5 ESPHome Starter Kit automation pages; added
stepping-stone boxes to the two Moderate pages
- Documented the convention in STYLE_GUIDE.md (new section 10),
CONTRIBUTING.md, and AGENTS.md
---
AGENTS.md | 6 +++
CONTRIBUTING.md | 1 +
STYLE_GUIDE.md | 51 ++++++++++++++++++-
.../automations/button-controlled-leds.md | 2 +
.../automations/motion-activated-light.md | 2 +
.../automations/play-a-tune.md | 2 +
.../automations/press-to-check-climate.md | 14 +++++
.../automations/temp-reactive-leds.md | 14 +++++
docs/stylesheets/extra.css | 50 ++++++++++++++++++
9 files changed, 141 insertions(+), 1 deletion(-)
diff --git a/AGENTS.md b/AGENTS.md
index d24134660c..57b6b97037 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -36,6 +36,12 @@ Read the full style guide, but these are the ones worth checking twice:
with framing copy (what the reader unlocks, what success looks like).
- Avoid corporate filler: **simply**, **just**, **easy**, **powerful**,
**seamlessly**.
+- Automation pages must carry a difficulty pill under the H1
+ (`Difficulty: Level N 路 Word`,
+ Level 1 Starter to Level 5 Pro). On Moderate-and-up pages, add a
+ same-product stepping-stone box linking easier automations. Pill and
+ box styles live in `docs/stylesheets/extra.css`; never inline colors.
+ See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty).
## Keep the style guide current
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0914f3ec72..8daeeff6c1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -78,6 +78,7 @@ The full writing and formatting rules live in [STYLE_GUIDE.md](STYLE_GUIDE.md).
- **Terminology**: Apollo hardware **addons** and Home Assistant software **apps** are different things; use each in its own context.
- **ESPHome** is the only correct casing.
- **No em dashes** anywhere in user-facing copy.
+- **Automation pages** carry a difficulty pill (`Level 1 Starter` to `Level 5 Pro`) under the title; harder pages can link easier ones in a stepping-stone box. See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty).
Mechanical conventions:
- MkDocs Material: see https://squidfunk.github.io/mkdocs-material/ for admonitions, tabs, and content tabs syntax
diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
index 0578a5068a..bc3ff7d641 100644
--- a/STYLE_GUIDE.md
+++ b/STYLE_GUIDE.md
@@ -401,7 +401,56 @@ how `docs/assets/` is organised), see
---
-## 10. When in doubt
+## 10. Automation difficulty
+
+Every automation page carries a difficulty pill directly under the H1 so
+readers can gauge how involved the setup is. The rating is about **setup
+difficulty and skill** (steps, helpers, templating, integrations), not
+runtime load.
+
+| Level | Word | Use it when the automation... |
+| --- | --- | --- |
+| 1 | Starter | is plug-and-play: toggle one entity, no helpers. |
+| 2 | Easy | needs a helper or two and a few guided steps. |
+| 3 | Moderate | combines several entities, conditions, or a template. |
+| 4 | Advanced | needs templating, blueprints, or multi-device logic. |
+| 5 | Pro | is complex multi-device or heavily custom. |
+
+Add the pill as the first line under the title. The `lvl-N` class sets the
+color (green at 1 to red at 5):
+
+```html
+# Build a Button-Controlled RGB Light
+
+Difficulty: Level 2 路 Easy
+```
+
+### Stepping-stone box
+
+On a harder page, point newcomers at one to three easier automations from
+the **same product**. Add it under the pill at your discretion (Moderate
+and up is a good rule of thumb). Use relative links so previews work:
+
+```html
+馃尡 New here? Try these first:
+
+```
+
+The pill and box styles live in `docs/stylesheets/extra.css`; never inline
+colors on the page.
+
+---
+
+## 11. When in doubt
If a rule above conflicts with clarity for the reader, clarity wins.
Open an issue or PR proposing the rule change so the guide stays
diff --git a/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md b/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md
index f9ed1a8482..40e68e5364 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md
@@ -6,6 +6,8 @@ description: >-
---
# Build a Button-Controlled RGB Light
+Difficulty: Level 2 路 Easy
+
This tutorial uses the Button module and the RGB & Buzzer module connected to the ESP32-C6, all sitting in the starter kit case.
!!! note "Before you start"
diff --git a/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md b/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md
index 86b0ac08db..61375af4e6 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md
@@ -6,6 +6,8 @@ description: >-
---
# Turn On a Light with Motion
+Difficulty: Level 1 路 Starter
+
This tutorial uses the Motion module and the LED & Buzzer module connected to the ESP32-C6. When the PIR sensor detects movement, the RGB light turns on. It's the same trigger-then-action pattern as the [Button Controlled LEDs](button-controlled-leds.md) automation, swapping the button trigger for a motion trigger.
!!! note "Before you start"
diff --git a/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md b/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md
index 2a907c3250..0e70f126e2 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md
@@ -6,6 +6,8 @@ description: >-
---
# Play a Tune with the Button
+Difficulty: Level 2 路 Easy
+
This tutorial uses the Button module and the LED & Buzzer module connected to the ESP32-C6. When you click the button, the piezo buzzer plays a short tune. It's the same trigger-then-action pattern as the [Button Controlled LEDs](button-controlled-leds.md) automation, swapping the light action for a buzzer action.
!!! note "Before you start"
diff --git a/docs/products/ESPHome-Starter-Kit/automations/press-to-check-climate.md b/docs/products/ESPHome-Starter-Kit/automations/press-to-check-climate.md
index 06c7999c8c..e83b42e951 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/press-to-check-climate.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/press-to-check-climate.md
@@ -7,6 +7,20 @@ description: >-
---
# Press to Check Climate
+Difficulty: Level 3 路 Moderate
+
+馃尡 New here? Try these first:
+
+
Want a quick read on how the room feels without opening Home Assistant? Press the button and the **Onboard RGB LED** gives you one color for the current temperature, then another for the current humidity.
The Onboard RGB LED on the ESP32-C6 is all you need for this tutorial, so the LED & Buzzer module can sit this one out.
diff --git a/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md b/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md
index f81a046b25..9e87f43559 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md
@@ -6,6 +6,20 @@ description: >-
---
# Temp-Reactive LEDs
+Difficulty: Level 3 路 Moderate
+
+馃尡 New here? Try these first:
+
+
This tutorial uses the Temperature and Humidity module and the LED & Buzzer module connected to the ESP32-C6. As the room temperature drifts across set thresholds, the RGB LEDs change color so you can see the comfort band at a glance. It's the same trigger-then-action pattern as [Button Controlled LEDs](button-controlled-leds.md), swapping the button trigger for a sensor-value trigger and adding one trigger per band.
!!! note "Before you start"
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index f443b45a23..1a3f45b959 100755
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -186,3 +186,53 @@ article.md-typeset .md-button img {
border-color: #4752c4;
color: #fff;
}
+
+/* ===== Automation difficulty pills ===== */
+.md-typeset .difficulty {
+ display: inline-flex;
+ align-items: center;
+ gap: 7px;
+ border-radius: 999px;
+ padding: 5px 13px;
+ font-size: 0.78rem;
+ font-weight: 600;
+ line-height: 1;
+}
+.md-typeset .difficulty::before {
+ content: "";
+ width: 9px;
+ height: 9px;
+ border-radius: 50%;
+ background: var(--diff-dot);
+}
+.md-typeset .difficulty.lvl-1 { background:#e8f5e9; color:#2e7d32; border:1px solid #a5d6a7; --diff-dot:#2e7d32; }
+.md-typeset .difficulty.lvl-2 { background:#f1f8e9; color:#558b2f; border:1px solid #c5e1a5; --diff-dot:#7cb342; }
+.md-typeset .difficulty.lvl-3 { background:#fff8e1; color:#a16207; border:1px solid #fde68a; --diff-dot:#f9a825; }
+.md-typeset .difficulty.lvl-4 { background:#fff3e0; color:#e65100; border:1px solid #ffcc80; --diff-dot:#ef6c00; }
+.md-typeset .difficulty.lvl-5 { background:#ffebee; color:#c62828; border:1px solid #ef9a9a; --diff-dot:#d32f2f; }
+
+/* ===== "Start easier" stepping-stone box ===== */
+.md-typeset .automation-steps-heading {
+ font-size: 0.8rem;
+ font-weight: 600;
+ margin: 1em 0 0.25em;
+}
+.md-typeset .automation-steps {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 10px;
+ margin: 0.5em 0 1em;
+}
+.md-typeset .automation-steps > .step {
+ flex: 1;
+ min-width: 170px;
+ border: 1px solid var(--md-default-fg-color--lightest);
+ border-radius: 8px;
+ padding: 11px 13px;
+ background: var(--md-code-bg-color);
+}
+.md-typeset .automation-steps .step-title {
+ display: block;
+ font-weight: 600;
+ margin-bottom: 7px;
+}