Skip to content

docs: add component class mixing guidelines #5737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
santiagopalma12 wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −0
Open

docs: add component class mixing guidelines #5737

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions templates/docs/building-vanilla.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.