diff --git a/src/uix/morfo/components/avatar.ts b/src/uix/morfo/components/avatar.ts
index b6772a349..b149b1af3 100644
--- a/src/uix/morfo/components/avatar.ts
+++ b/src/uix/morfo/components/avatar.ts
@@ -25,6 +25,17 @@ export const avatarMorfo = {
 					value: v.propRef('variant')
 				},
 				{
+					// Optional severity acknowledges the documented escape
+					// hatch: the wrapper accepts any CSS color string
+					// (hex, oklch, rgb, etc.) and routes non-canonical
+					// values through `data-color-custom` + a
+					// `--avatar-color-custom` inline CSS variable instead.
+					// When the consumer passes a canonical role
+					// (`primary`, `affirm`, etc.) the enum value lands
+					// here; when they pass a custom color, this attr is
+					// absent by design (the recipe knows to fall through
+					// to the custom path). Symmetric with `Avatar.Badge`,
+					// which already declared this attr as optional.
 					attr: 'data-color',
 					values: [
 						'primary',
@@ -36,7 +47,8 @@ export const avatarMorfo = {
 						'threat',
 						'loss'
 					],
-					value: v.propRef('color')
+					value: v.propRef('color'),
+					severity: 'optional'
 				},
 				{
 					attr: 'data-radius',