Zero-UI
← Back to docs/Naming Conventions – Zero-UI Home Automation (2025)

Naming Conventions – Zero-UI Home Automation (2025)

Purpose

This document defines mandatory naming conventions for all entities, automations, devices, MQTT topics, and identifiers.

It exists to:

  • Preserve long-term readability
  • Enable safe AI-assisted code generation
  • Prevent “mystery entities” and spaghetti logic
  • Make troubleshooting obvious under stress

This file is authoritative.
Names that violate this document must be corrected.

Core Naming Principles

  1. Names must describe intent, not implementation
  2. Names must read well out loud
  3. Names must scale to hundreds of entities
  4. Names must survive five years without explanation

If a name needs a comment to explain it, the name is wrong.

Global Format Rules

General Pattern

..

Where:

  • domain = what kind of thing it is
  • area = physical location (real-world)
  • intent = purpose or behavior

Areas (Canonical)

Areas must map to physical reality and remain stable.

Examples:

  • entry
  • kitchen
  • living_room
  • hallway
  • garage
  • garage_entry
  • bedroom_master
  • bathroom_master
  • office
  • outside_front
  • outside_back

Rules:

  • No abbreviations
  • No renaming once in use
  • Avoid vague areas like main, misc, temp

Automation Naming (Strict)

..

Format

Examples

  • lighting.entry.auto_on_after_sunset
  • lighting.kitchen.auto_off_no_motion
  • lighting.hallway.night_pathway
  • notify.power.generator_failed
  • security.entry.door_open_night_alert

Rules

  • One automation = one intent
  • Use verbs (auto_on, auto_off, alert, suppress)
  • Avoid generic names like automation_12

Entity Naming

Sensors

Examples:

  • sensor.entry_motion
  • sensor.front_door_contact
  • sensor.kitchen_lux
  • sensor.garage_power_draw

Binary Sensors

sensor._

Examples:

  • sensor.entry_motion
  • sensor.front_door_contact
  • sensor.kitchen_lux
  • sensor.garage_power_draw

Binary Sensors

binary_sensor._

Examples:

  • binary_sensor.front_door_open
  • binary_sensor.entry_motion_active
  • binary_sensor.garage_vehicle_present

Lights

light._

Examples:

  • light.entry_ceiling
  • light.kitchen_island
  • light.hallway_pathway

Switches

switch._

Examples:

  • switch.outside_back_floodlights
  • switch.office_desk_power

Helper Entities (Restricted Use)

input_boolean

Only allowed for real-world concepts.

input_boolean.

Examples:

  • input_boolean.guest_mode
  • input_boolean.house_armed

Banned:

  • input_boolean.temp_fix
  • input_boolean.test_automation

input_number / input_datetime

Only allowed if value has real meaning.

Examples:

  • input_number.night_light_brightness
  • input_datetime.quiet_hours_start

MQTT Topic Naming

Format

home///

Examples

  • home/entry/door/state
  • home/kitchen/motion/state
  • home/garage/ev/charge_state

Rules

  • No spaces
  • Lowercase only
  • States must be explicit (open, closed, active, inactive)
  • No “magic” topics

ESPHome Device Naming

Device Name

esphome__

Examples:

  • esphome_entry_sensors
  • esphome_garage_contacts

Node Name

Matches device name exactly.

Camera Naming

Cameras

camera._

Examples:

  • camera.outside_front_driveway
  • camera.outside_back_yard
  • camera.garage_overhead

AI Objects

sensor.__detected

Examples:

  • sensor.outside_front_person_detected
  • sensor.outside_front_package_detected

Notification Naming

notify..

Examples:

  • notify.power.outage
  • notify.security.door_open_night
  • notify.water.leak_detected

Subdomain Naming (Ingress)

Reserved

  • Root portal: teamlewis.co
  • Docs: docs.teamlewis.co
  • Home Assistant: ha.teamlewis.co
  • Cameras/NVR: cam.teamlewis.co
  • Private AI: ai.teamlewis.co

Rules

  • One subdomain = one service
  • No multiplexing multiple services on one host
  • Wildcard DNS allowed, but explicit NPM hosts must exist
  • Internal Docker service names should mirror intent (e.g., open-webui, zero-ui-frontend)

Prohibited Naming Patterns

❌ test_*
❌ temp_*
❌ automation_*
❌ new_*
❌ fix_*
❌ single-letter suffixes
❌ emojis
❌ abbreviations only the operator understands

AI Coding Guardrails

Any AI-generated code must:

  • Follow this naming scheme exactly
  • Reuse existing area names
  • Avoid introducing new helpers unless explicitly justified
  • Refactor names rather than duplicating concepts

If naming cannot be resolved confidently, the AI must pause and ask.

Final Rule

Names are part of the architecture.

Bad names create bad systems, even if the code works.

This document is authoritative and final.