diff --git a/doc/docs.md b/doc/docs.md
index 454735e36878ad..f98c800683af72 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -5632,6 +5632,40 @@ fn main() {
 }
 ```
 
+```v
+// @[_allow_multiple_values] allows an enum to have multiple duplicate values.
+// Use it carefully, only when you really need it.
+
+@[_allow_multiple_values]
+enum ButtonStyle {
+	primary   = 1
+	secondary = 2
+	success   = 3
+
+	blurple = 1
+	grey    = 2
+	gray    = 2
+	green   = 3
+}
+
+fn main() {
+	assert int(ButtonStyle.primary) == 1
+	assert int(ButtonStyle.blurple) == 1
+
+	assert int(ButtonStyle.secondary) == 2
+	assert int(ButtonStyle.gray) == 2
+	assert int(ButtonStyle.grey) == 2
+
+	assert int(ButtonStyle.success) == 3
+	assert int(ButtonStyle.green) == 3
+
+	assert ButtonStyle.primary == ButtonStyle.blurple
+	assert ButtonStyle.secondary == ButtonStyle.grey
+	assert ButtonStyle.secondary == ButtonStyle.gray
+	assert ButtonStyle.success == ButtonStyle.green
+}
+```
+
 Struct field deprecations:
 
 ```v oksyntax
diff --git a/vlib/v/checker/checker.v b/vlib/v/checker/checker.v
index 854aa497be07fb..a15bfe35abfee5 100644
--- a/vlib/v/checker/checker.v
+++ b/vlib/v/checker/checker.v
@@ -1975,6 +1975,7 @@ fn (mut c Checker) enum_decl(mut node ast.EnumDecl) {
 							field.pos)
 					} else if !c.pref.translated && !c.file.is_translated && !node.is_multi_allowed
 						&& ilast + 1 in iseen {
+						c.add_error_detail('use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed')
 						c.error('enum value `${ilast + 1}` already exists', field.pos)
 					}
 					iseen << ilast + 1
@@ -1989,6 +1990,7 @@ fn (mut c Checker) enum_decl(mut node ast.EnumDecl) {
 							field.pos)
 					} else if !c.pref.translated && !c.file.is_translated && !node.is_multi_allowed
 						&& ulast + 1 in useen {
+						c.add_error_detail('use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed')
 						c.error('enum value `${ulast + 1}` already exists', field.pos)
 					}
 					useen << ulast + 1
@@ -2038,6 +2040,7 @@ fn (mut c Checker) check_enum_field_integer_literal(expr ast.IntegerLiteral, is_
 	}
 	if !overflows && !c.pref.translated && !c.file.is_translated && !is_multi_allowed {
 		if (is_signed && ival in iseen) || (!is_signed && uval in useen) {
+			c.add_error_detail('use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed')
 			c.error('enum value `${expr.val}` already exists', pos)
 		}
 	}
diff --git a/vlib/v/checker/tests/enum_field_value_duplicate_a.out b/vlib/v/checker/tests/enum_field_value_duplicate_a.out
index ce72e698673eb7..5d8651cede64da 100644
--- a/vlib/v/checker/tests/enum_field_value_duplicate_a.out
+++ b/vlib/v/checker/tests/enum_field_value_duplicate_a.out
@@ -5,9 +5,11 @@ vlib/v/checker/tests/enum_field_value_duplicate_a.vv:3:10: error: enum value `0`
       |             ^
     4 |     blue  = 1
     5 |     alpha = 1
+Details: use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed
 vlib/v/checker/tests/enum_field_value_duplicate_a.vv:5:10: error: enum value `1` already exists
     3 |     green = 0
     4 |     blue  = 1
     5 |     alpha = 1
       |             ^
     6 | }
+Details: use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed
diff --git a/vlib/v/checker/tests/enum_field_value_duplicate_b.out b/vlib/v/checker/tests/enum_field_value_duplicate_b.out
index c1a9ae2ab8cb68..c9e20ab46b82cc 100644
--- a/vlib/v/checker/tests/enum_field_value_duplicate_b.out
+++ b/vlib/v/checker/tests/enum_field_value_duplicate_b.out
@@ -4,3 +4,4 @@ vlib/v/checker/tests/enum_field_value_duplicate_b.vv:4:2: error: enum value `0`
     4 |     blue // -1 + 1 = 0
       |     ~~~~
     5 | }
+Details: use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed
diff --git a/vlib/v/checker/tests/enum_field_value_duplicate_c.out b/vlib/v/checker/tests/enum_field_value_duplicate_c.out
index 65bbc0b2cf3a60..27b908dc0ca818 100644
--- a/vlib/v/checker/tests/enum_field_value_duplicate_c.out
+++ b/vlib/v/checker/tests/enum_field_value_duplicate_c.out
@@ -5,3 +5,4 @@ vlib/v/checker/tests/enum_field_value_duplicate_c.vv:6:12: error: enum value `1`
       |               ~~~~~~~~
     7 |     all = 0xFFFFFFFF
     8 | }
+Details: use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed
diff --git a/vlib/v/checker/tests/enum_field_value_duplicate_d.out b/vlib/v/checker/tests/enum_field_value_duplicate_d.out
index b4350c326e08a8..b8b1071ce1770d 100644
--- a/vlib/v/checker/tests/enum_field_value_duplicate_d.out
+++ b/vlib/v/checker/tests/enum_field_value_duplicate_d.out
@@ -5,3 +5,4 @@ vlib/v/checker/tests/enum_field_value_duplicate_d.vv:6:6: error: enum value `1`
       |         ~~~
     7 | }
     8 |
+Details: use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed
diff --git a/vlib/v/checker/tests/enum_field_value_duplicate_e.out b/vlib/v/checker/tests/enum_field_value_duplicate_e.out
index 93314f28d6b647..4e9db5ec0918ac 100644
--- a/vlib/v/checker/tests/enum_field_value_duplicate_e.out
+++ b/vlib/v/checker/tests/enum_field_value_duplicate_e.out
@@ -5,3 +5,4 @@ vlib/v/checker/tests/enum_field_value_duplicate_e.vv:4:6: error: enum value `2`
       |         ~~~
     5 | }
     6 |
+Details: use `@[_allow_multiple_values]` attribute to allow multiple enum values. Use only when it is needed