diff --git a/esphome/components/light/color_mode.h b/esphome/components/light/color_mode.h
index 9c6a4d147b..03132f54bf 100644
--- a/esphome/components/light/color_mode.h
+++ b/esphome/components/light/color_mode.h
@@ -184,6 +184,12 @@ inline bool has_capability(const ColorModeMask &mask, ColorCapability capability
 }  // namespace esphome
 
 // Template specializations for ColorMode must be in global namespace
+//
+// C++ requires template specializations to be declared in the same namespace as the
+// original template. Since EnumBitmask is in the esphome namespace (not esphome::light),
+// we must provide these specializations at global scope with fully-qualified names.
+//
+// These specializations define how ColorMode enum values map to/from bit positions.
 
 /// Map ColorMode enum values to bit positions (0-9)
 /// Bit positions follow the enum declaration order
diff --git a/esphome/core/enum_bitmask.h b/esphome/core/enum_bitmask.h
index 4c29c7047e..fdbd0c50cc 100644
--- a/esphome/core/enum_bitmask.h
+++ b/esphome/core/enum_bitmask.h
@@ -26,6 +26,9 @@ namespace esphome {
 ///   if (modes.contains(CLIMATE_MODE_HEAT)) { ... }
 ///   for (auto mode : modes) { ... }  // Iterate over set bits
 ///
+/// For complete usage examples with template specializations, see:
+///   - esphome/components/light/color_mode.h (ColorMode example)
+///
 /// Design notes:
 ///   - Uses compile-time type selection for optimal size (uint8_t/uint16_t/uint32_t)
 ///   - Iterator converts bit positions to actual enum values during traversal