From 7b2f13414155de6603a350c849ef6cbd22c549b1 Mon Sep 17 00:00:00 2001
From: Santiago Palma <spalmaa@unsa.edu.pe>
Date: Sat, 17 Jan 2026 22:30:51 -0500
Subject: [PATCH] docs: add component class mixing guidelines

Closes #5413

Added documentation explaining that component class names should not be mixed on the same element. Includes recommended usage examples and rationale for this convention.
---
 templates/docs/building-vanilla.md | 38 ++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/templates/docs/building-vanilla.md b/templates/docs/building-vanilla.md
index 886372121..1b66661aa 100644
--- a/templates/docs/building-vanilla.md
+++ b/templates/docs/building-vanilla.md
@@ -498,3 +498,41 @@ Example HTML:
 ```html
 <script type="module" src="/static/js/modules/vanilla-framework/js/tabs.js"></script>
 ```
+
+## Component Class Mixing
+
+When using Vanilla, **component class names should not be mixed on the same element**. Each element should only have classes from one component, along with any applicable `is-<theme>` modifiers.
+
+### Recommended usage
+
+Wrap components in their own container elements:
+
+```html
+<!-- ✓ Recommended: Each component in its own container -->
+<div class="row--50-50">
+  <div class="col">
+    <div class="p-section">
+      <p>Content here</p>
+    </div>
+  </div>
+</div>
+```
+
+### Avoid
+
+Do not combine classes from different components on the same element:
+
+```html
+<!-- ✗ Avoid: Mixing col and p-section on the same element -->
+<div class="row--50-50">
+  <div class="col p-section">
+    <p>Content here</p>
+  </div>
+</div>
+```
+
+### Why this matters
+
+- **Predictable styling**: Each component's styles are designed to work independently. Mixing classes can lead to unexpected interactions.
+- **Maintainability**: When components are properly separated, updating or debugging styles becomes easier.
+- **Consistency**: Following this convention ensures your project looks and behaves consistently with other projects using Vanilla.