span
Generic inline container for phrasing content. Use only when no semantic element fits — for effects, status indicators, translation control, or accessibility helpers.
Description
The <span> element is a generic inline container with no inherent semantics. Like <div> for block content, <span> should be used only when no semantic element fits the need.
Prefer semantic elements first: <em>, <strong>, <mark>, <code>, <time>, <data>, etc. But when the content doesn't fit any semantic category, <span> is the right tool.
When to Use
Legitimate uses of <span> in Vanilla Breeze:
- Effect targets: Apply
data-effectto a text range within a paragraph - Status indicators: The
.statusclass for inline status dots - Translation control:
translate="no"on brand names or identifiers - Visually hidden text:
.visually-hiddenfor screen reader context - Block progress: The
.block-progressUnicode meter pattern - Styling hooks: When CSS needs an inline target that has no semantic equivalent
When NOT to Use
Examples
Effect Targets
When a VB effect needs to wrap a text range inside a paragraph, <span> is the correct container:
<p>This text has an <span data-effect="highlight" data-trigger="scroll">animated highlight</span> effect applied.</p>Status Indicators
The .status class creates an inline status dot using a ::before pseudo-element with Unicode characters. Six states are available:
<span class="status" data-status="success">Deployed</span><span class="status" data-status="warning">Pending review</span><span class="status" data-status="error">Build failed</span><span class="status" data-status="inactive">Offline</span>.status { display: inline-flex; align-items: center; gap: 0.4em; font-size: var(--font-size-sm); &::before { content: "\25CF"; /* filled circle */ font-size: 0.7em; color: var(--color-text-muted); } &[data-status="success"]::before { color: var(--color-success); } &[data-status="warning"]::before { color: var(--color-warning); } &[data-status="error"]::before { color: var(--color-error); } &[data-status="inactive"]::before { content: "\25CB"; /* empty circle */ } &[data-status="check"]::before { content: "\2714"; /* check mark */ color: var(--color-success); } &[data-status="fail"]::before { content: "\2718"; /* cross mark */ color: var(--color-error); }}Translation Control
Use translate="no" on <span> to prevent machine translation of brand names, identifiers, and technical terms:
<p>Install <span translate="no">Vanilla Breeze</span> via npm.</p><p>Your username is <span translate="no">tpowell42</span>.</p>See the i18n guide for VB's full translation convention.
Visually Hidden Text
The .visually-hidden class hides text visually while keeping it accessible to screen readers. This provides context that sighted users get from visual cues:
<p>Price: <span class="visually-hidden">Was </span> <s>$99.99</s> <span class="visually-hidden">Now </span> $79.99</p>Block Progress
A Unicode block-character progress meter using role="meter" for accessibility:
<span class="block-progress" role="meter" aria-valuenow="70" aria-valuemin="0" aria-valuemax="100" aria-label="Progress"> <span aria-hidden="true" data-filled>███████</span> <span aria-hidden="true" data-empty>░░░</span> <small>70%</small></span>Anti-Patterns
Avoid using <span> when a semantic element exists:
<!-- Wrong: span for layout --><span class="header">Site Title</span> <!-- Right: use semantic element --><h1>Site Title</h1> <!-- Wrong: span for emphasis --><span style="font-weight: bold">Important</span> <!-- Right: use semantic element --><strong>Important</strong>Accessibility
<span>has no inherent ARIA role or semantic meaning- Screen readers treat it as anonymous inline text
- Add
role,aria-label, oraria-livewhen the span carries meaning (e.g., status indicators, meters) - The
.visually-hiddenpattern is essential for providing screen reader context that sighted users get visually
Related
<em>— Stress emphasis (preferred over styled span)<strong>— Importance (preferred over styled span)<mark>— Highlighted text (preferred over styled span)<code>— Code content (preferred over styled span)<data>— Machine-readable values (preferred over styled span)<time>— Dates and times (preferred over styled span)