From 9fe5a812d9985cd154a4758a6a71c74c9c9cd6c6 Mon Sep 17 00:00:00 2001
From: MSanjanaa <2400033265@kluniversity.in>
Date: Mon, 20 Oct 2025 14:17:02 +0530
Subject: [PATCH] docs: clarify guarded namespaces; remove invalid namespace
 guards

---
 docs/features/mixins.md | 61 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/features/mixins.md

diff --git a/docs/features/mixins.md b/docs/features/mixins.md
new file mode 100644
index 000000000..e0ca87291
--- /dev/null
+++ b/docs/features/mixins.md
@@ -0,0 +1,61 @@
+// ...existing code...
+### Namespaces are not mixins — correct usage of default()
+
+Invalid code:
+
+```less
+#sp_1 {
+  #sp_2 {
+    .mixin() when not(default()) { /* */ }
+  }
+}
+```
+
+Why it's wrong
+- The `default()` guard only applies to mixins and their parameters, not to namespaces.
+- Namespaces (`#sp_1`, `#sp_2`) are logical groups and do not participate in `default()` logic.
+- In the invalid example the mixin is defined but never called; putting `when(default())` on namespaces has no effect.
+
+Fixed guidance and examples
+- Place `default()` guards on mixin parameters or mixin definitions themselves.
+- Namespaced mixins can still use `default()` — the guards must be on the mixin, not the namespace.
+
+Correct (guards on mixin parameters):
+
+```less
+.mixin(@a: default()) when (default(@a)) {
+  /* default implementation */
+}
+.mixin(@a) when not(default(@a)) {
+  /* non-default implementation / override */
+}
+
+/* calling the mixin */
+.selector {
+  .mixin();        /* uses default implementation */
+  .mixin(42);      /* uses non-default implementation */
+}
+```
+
+Correct with namespaces (mixin defined inside namespaces but guards still on the mixin):
+
+```less
+#sp_1 {
+  #sp_2 {
+    .mixin(@a: default()) when (default(@a)) {
+      /* default implementation */
+    }
+    .mixin(@a) when not(default(@a)) {
+      /* override implementation */
+    }
+  }
+}
+
+/* call the namespaced mixin by its full path */
+.selector {
+  #sp_1 #sp_2 .mixin();   /* default */
+  #sp_1 #sp_2 .mixin(5);  /* override */
+}
+```
+
+// ...existing code...
\ No newline at end of file