div
Generic block-level container. In Vanilla Breeze, div usage is discouraged — prefer semantic elements and VB layout primitives.
Philosophy
Vanilla Breeze takes an intentional stance: <div> is a last resort, not a default. The VB conformance checker flags every <div> as a warning, and the semantic check raises it as an error for new code.
This is not about being pedantic — semantic elements provide:
- Accessibility: Screen readers can navigate by landmarks (
<nav>,<main>,<aside>) - SEO: Search engines understand content structure from semantic markup
- Readability: Code is self-documenting when elements describe their purpose
- Less CSS: VB styles semantic elements directly — no class soup
Semantic Alternatives
For every common <div> pattern, a semantic element exists:
| Instead of | Use |
|---|---|
<div class="card"> | <article> |
<div class="sidebar"> | <aside> |
<div class="nav"> | <nav> |
<div class="header"> | <header> |
<div class="footer"> | <footer> |
<div class="main"> | <main> |
<div class="section"> | <section> |
<div class="actions"> | <footer> or <menu> |
<div class="group"> | <fieldset> |
<div data-layout="stack"> | Put data-layout on the semantic parent |
<!-- Instead of <div class="card"> --><article> <h3>Card Title</h3> <p>Self-contained content.</p></article> <!-- Instead of <div class="sidebar"> --><aside> <p>Tangentially related content.</p></aside> <!-- Instead of <div class="nav"> --><nav aria-label="Primary"> <ul class="unstyled"> <li><a href="#">Home</a></li> </ul></nav> <!-- Instead of <div class="footer"> / <div class="actions"> --><footer> <button type="button">Save</button></footer>Layout Without Divs
VB's layout attributes (data-layout) and custom elements (<layout-stack>, <layout-grid>, etc.) can be applied directly to semantic elements:
<!-- Instead of <div data-layout="stack"> --><section data-layout="stack" data-layout-gap="m"> <p>Content with vertical spacing.</p> <p>No wrapper div needed.</p></section> <!-- Instead of <div data-layout="grid"> --><ul data-layout="grid" data-layout-gap="m"> <li>Grid item one</li> <li>Grid item two</li></ul>When no semantic element fits, VB layout custom elements (<layout-stack>, <layout-grid>, <layout-cluster>) serve as the container — they are more descriptive than <div> because they declare layout intent.
Legitimate Uses
There are a few cases where <div> is the correct choice:
<dl>grouping: HTML5 allows<div>inside<dl>to group<dt>/<dd>pairs (for striped styling)- Form field groups: Wrapping radio/checkbox groups inside
<form-field> - Third-party widgets: When external libraries require a container div
- CSS Grid/Flex children: When you genuinely need a non-semantic grid cell
<!-- dl grouping (HTML5 spec allows div inside dl) --><dl data-striped> <div> <dt>Term</dt> <dd>Description</dd> </div></dl> <!-- Radio/checkbox group wrapper for form-field --><form-field> <fieldset> <legend>Options</legend> <div> <label><input type="radio" name="opt" /> Option A</label> <label><input type="radio" name="opt" /> Option B</label> </div> </fieldset></form-field>Conformance Enforcement
VB enforces semantic HTML through automated tooling:
# VB conformance checker flags divs: vb/no-div — Any <div> element (warning → error)vb/no-div-wrapper — <div> wrapping a single semantic childsemantic/no-div — Semantic check for div elementsvb/no-div— Flags any<div>element. Suggests semantic alternatives.vb/no-div-wrapper— Flags<div>wrapping a single semantic child (the div is unnecessary).- Allowlist: Known legitimate uses can be added to
.claude/vb-conformance-allowlist.json
Run npm run conformance to check your HTML files.
The VB Refinement Checklist
When auditing existing code with divs, follow this order:
- Div audit: Can each div be replaced with a semantic element?
- Wrapper audit: Is a div wrapping a single child that could receive the attributes directly?
- data-layout audit: Is
data-layouton a div when it could be on the semantic parent? - Class audit: Are VB element-scoped classes available (e.g.,
form.stacked)? - Semantic opportunities: Can
<footer>replace a button group div? Can<header>replace a title wrapper?
Accessibility
<div>has no implicit ARIA role — it is invisible to screen readers- Screen readers cannot navigate by divs; they can navigate by landmarks, headings, lists, and other semantic elements
- Every div you replace with a semantic element improves the accessibility tree
Related
<span>— Generic inline container (same philosophy: last resort)<section>— Thematic grouping of content<article>— Self-contained content<aside>— Tangentially related content<nav>— Navigation sections<header>— Introductory content<footer>— Footer content and action groups<main>— Dominant content of the page<menu>— Action button groups<fieldset>— Form field grouping