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:
Turn On a Light with Motion - Difficulty: Level 1 · Starter + Difficulty: Level 1
Build a Button-Controlled RGB Light - Difficulty: Level 2 · Easy + Difficulty: Level 1
``` 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:

Turn On a Light with Motion - Difficulty: Level 1 · Starter + Difficulty: Level 1
Build a Button-Controlled RGB Light - Difficulty: Level 2 · Easy + Difficulty: Level 1
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:

Turn On a Light with Motion - Difficulty: Level 1 · Starter + Difficulty: Level 1
Build a Button-Controlled RGB Light - Difficulty: Level 2 · Easy + Difficulty: Level 1
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 {