From 6380ae78ede957ca5a23c563b466d53539c11d2d Mon Sep 17 00:00:00 2001
From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com>
Date: Wed, 3 Jun 2026 16:27:42 -0500
Subject: [PATCH] docs: simplify difficulty pills to 3 unlabeled levels (#928)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The 5-level difficulty scale introduced in #920 used a one-word label
after each level number (Starter, Easy, Moderate, Advanced, Pro). Two
problems: only levels 1-3 ever got used in practice (no pages at
Advanced or Pro), and "Easy" is on the project's own corporate-filler
ban list in AGENTS.md / STYLE_GUIDE.md.
Collapse the scale to 3 unlabeled levels:
- Pills now read `Difficulty: Level N` with no descriptor word.
- 5 CSS color tiers collapsed to 3 (green at 1, amber at 2, red at 3).
- STYLE_GUIDE.md section 10 table shrinks from 5 rows to 3 with
collapsed criteria; the stepping-stone trigger guidance changes from
"Moderate-and-up" to "Level 2 and up".
- CONTRIBUTING.md and AGENTS.md both pick up the (beginner) / (advanced)
parenthetical when describing the scale range.
Page rebalance:
- motion-activated-light: Level 1 → Level 1 (no change)
- button-controlled-leds: Level 2 Easy → Level 1
- play-a-tune: Level 2 Easy → Level 1
- temp-reactive-leds: Level 3 Moderate → Level 2
- press-to-check-climate: Level 3 Moderate → Level 3
Stepping-stone boxes on the two harder pages updated to match the new
Level 1 status of their cross-links.
---
AGENTS.md | 9 ++++----
CONTRIBUTING.md | 2 +-
STYLE_GUIDE.md | 22 +++++++++----------
.../automations/button-controlled-leds.md | 2 +-
.../automations/motion-activated-light.md | 2 +-
.../automations/play-a-tune.md | 2 +-
.../automations/press-to-check-climate.md | 6 ++---
.../automations/temp-reactive-leds.md | 6 ++---
docs/stylesheets/extra.css | 6 ++---
9 files changed, 27 insertions(+), 30 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index fbe5ed900a..8438e8503f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,10 +37,11 @@ Read the full style guide, but these are the ones worth checking twice:
- 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.
+ (`Difficulty: Level N`,
+ Level 1 (beginner) to Level 3 (advanced); no descriptor word after
+ the number). On Level 2 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).
- Every page under the ESPHome Starter Kit product (modules, tutorials,
automations, learn-the-basics, FAQ, start-here, first-steps) must end
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3977f2b187..0f6c819eaf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -78,7 +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).
+- **Automation pages** carry a difficulty pill (`Level 1` (beginner) to `Level 3` (advanced)) under the title; harder pages can link easier ones in a stepping-stone box. See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty).
- **Starter-kit pages** end with the community CTA snippet (`--8<-- "_snippets/community-help.md"`). Edit the snippet, not the page, when the CTA copy changes. See [Community CTA on starter-kit pages](STYLE_GUIDE.md#11-community-cta-on-starter-kit-pages).
Mechanical conventions:
diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
index 4a444aba0f..30e7334cef 100644
--- a/STYLE_GUIDE.md
+++ b/STYLE_GUIDE.md
@@ -408,27 +408,25 @@ 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. |
+| Level | Use it when the automation... |
+| --- | --- |
+| 1 | is plug-and-play, or needs only a helper or two and a few guided steps. |
+| 2 | combines several entities, conditions, or a template. |
+| 3 | needs templating, blueprints, multi-device logic, or is 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):
+color (green at 1, amber at 2, red at 3):
```html
# Build a Button-Controlled RGB Light
-Difficulty: Level 2 · Easy
+Difficulty: Level 1
```
### 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
+the **same product**. Add it under the pill at your discretion (Level 2
and up is a good rule of thumb). Use relative links so previews work:
```html
@@ -436,11 +434,11 @@ and up is a good rule of thumb). Use relative links so previews work:
```
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 3277e6f815..a6296e05da 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md
@@ -6,7 +6,7 @@ description: >-
---
# Build a Button-Controlled RGB Light
-Difficulty: Level 2 · Easy
+Difficulty: Level 1
This tutorial uses the Button module and the RGB & Buzzer module connected to the ESP32-C6, all sitting in the starter kit case.
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 4b4b51ca2f..29b0d406ff 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md
@@ -6,7 +6,7 @@ description: >-
---
# Turn On a Light with Motion
-Difficulty: Level 1 · Starter
+Difficulty: Level 1
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.
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 1d9a43f214..03a3057fd5 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md
@@ -6,7 +6,7 @@ description: >-
---
# Play a Tune with the Button
-Difficulty: Level 2 · Easy
+Difficulty: Level 1
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.
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 2f8a55cd91..8662bdf371 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,17 +7,17 @@ description: >-
---
# Press to Check Climate
-Difficulty: Level 3 · Moderate
+Difficulty: Level 3
🌱 New here? Try these first:
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 bbb20e7f4a..fb1895d11d 100644
--- a/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md
+++ b/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md
@@ -6,17 +6,17 @@ description: >-
---
# Temp-Reactive LEDs
-Difficulty: Level 3 · Moderate
+Difficulty: Level 2
🌱 New here? Try these first:
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 1a3f45b959..4f21a799b7 100755
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -206,10 +206,8 @@ article.md-typeset .md-button img {
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; }
+.md-typeset .difficulty.lvl-2 { background:#fff8e1; color:#a16207; border:1px solid #fde68a; --diff-dot:#f9a825; }
+.md-typeset .difficulty.lvl-3 { background:#ffebee; color:#c62828; border:1px solid #ef9a9a; --diff-dot:#d32f2f; }
/* ===== "Start easier" stepping-stone box ===== */
.md-typeset .automation-steps-heading {