html
The root element of an HTML document, containing all other elements.
Description
The <html> element is the root of an HTML document. In Vanilla Breeze, it serves as the attachment point for theming, fluid scaling, page layout, and accessibility configuration via data attributes.
Because CSS selectors like :root[data-theme] and :root[data-mode] target this element, the <html> element acts as VB's global control surface. Data attributes set here cascade through the entire document via custom properties, while individual elements can override them locally for scoped theming.
Basic Example
<!DOCTYPE html><html lang="en"> <head>...</head> <body>...</body></html>Typical Page
A typical Vanilla Breeze page sets global config on <html> and page structure on <body>:
<!DOCTYPE html><html lang="en" data-theme="modern" data-fluid> <head>...</head> <body data-page-layout="sidebar-start"> <header>...</header> <nav>...</nav> <main>...</main> </body></html>How It Works
Cascade Model
VB stores configuration as data attributes on <html>. CSS activates token overrides using :root[data-*] selectors. Theme selectors use the ~= operator (word-match) so multiple themes can be space-separated. Mode and fluid selectors use = (exact match) since only one value is valid at a time.
/* Theme CSS uses :root[data-theme~="name"] — the ~= operator matches individual words in a space-separated list */:root[data-theme~="modern"] { --radius-s: 0.5rem; --shadow-sm: 0 2px 8px oklch(0% 0 0 / 0.08);} /* Mode uses exact match since only one value is valid */:root[data-mode="dark"] { color-scheme: dark;}html vs body
VB splits responsibilities between these two elements:
| Attribute | Element | Purpose |
|---|---|---|
data-mode |
<html> |
Light/dark color scheme (global config) |
data-theme |
<html> |
Brand and aesthetic tokens (global config) |
data-fluid |
<html> |
Fluid typography and spacing scaling |
data-page |
<html> |
Site section identifier for scoped CSS |
data-page-layout |
<body> |
Page grid structure (sidebar, holy-grail, etc.) |
Scoped Overrides
Both data-theme and data-mode can be placed on any descendant element to create a scoped region. VB's reset re-applies color: var(--color-text) on scoped elements so custom properties resolve in the element's own context rather than inheriting from the body.
<main data-theme="modern"> <!-- This section gets the modern personality while the rest of the page uses the root theme --></main> <aside data-mode="dark"> <!-- Dark sidebar regardless of page mode --></aside>Vanilla Breeze Attributes
Vanilla Breeze uses data attributes on the <html> element to control theming and layout.
data-mode
Controls light/dark mode. When omitted, mode follows the user's system preference (auto).
| Value | Description |
|---|---|
| (omitted) | Auto mode - follows system preference via prefers-color-scheme |
light |
Force light mode regardless of system preference |
dark |
Force dark mode regardless of system preference |
<html lang="en" data-mode="dark">data-theme
Sets the color theme. Accepts a space-separated list of theme tokens. When omitted, uses the default purple/blue theme. See the Themes page for the full catalogue and live previews.
| Category | Values |
|---|---|
| Accent (via JS) | ocean, forest, sunset, amber, emerald, lavender, indigo, slate, rose, coral — applied via ThemeManager.setAccent(), not data-theme |
| Extreme | swiss, brutalist, organic, kawaii, cyber, terminal, 8bit, nes, win9x, vaporwave, art-deco, bauhaus, memphis, editorial, claymorphism, neumorphism, glassmorphism, cottagecore, rough, genai, and more |
| Editor | solarized, dracula, nord, gruvbox, rose-pine, tokyo-night, catppuccin-mocha, catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, dusk, midnight, dawn, high-noon |
| Industry | government, financial, clinical, startup, modern, minimal, classic |
| Accessibility | a11y-high-contrast, a11y-large-text, a11y-dyslexia |
Themes can be combined. Accessibility themes layer on top of personality or extreme themes. The [data-theme~="name"] word-match selector enables this stacking — each token is matched independently, so data-theme="modern a11y-large-text" activates both rulesets simultaneously. Color accents (ocean, forest, sunset, etc.) are applied separately via ThemeManager.setAccent().
<html lang="en" data-theme="modern"><html lang="en" data-theme="modern a11y-large-text">data-page
Identifies which site section a page belongs to. This is a scoping hook for your own CSS — VB does not define a fixed enumeration. Values are whatever makes sense for your site (e.g., docs, lab, blog, admin).
| Aspect | Detail |
|---|---|
| Purpose | Section-scoped CSS via attribute selectors |
| Values | User-defined. Examples: docs, lab, blog |
| Set by | Template layout or page front matter (dataPage variable) |
<html lang="en" data-page="docs">/* Site-specific CSS can target sections */[data-page="docs"] .sidebar { position: sticky; top: var(--size-m);} [data-page="lab"] main { max-inline-size: none;}For page-level grid layouts, use data-page-layout on <body> instead.
data-fluid
Activates fluid scaling. Typography and spacing scale continuously between 320px and 1440px viewports. Always present in the Vanilla Breeze base layout.
| Value | Description |
|---|---|
| (boolean / omitted value) | Default preset — Major Second → Major Third type ratio |
default |
Same as boolean — explicit default preset |
compact |
Tighter spacing and smaller type ratio (Minor Second → Minor Third) |
spacious |
Generous spacing and larger type ratio (Minor Third → Perfect Fourth) |
<html lang="en" data-fluid><!-- or with a preset --><html lang="en" data-fluid="compact">data-motion-reduced
User-toggled reduced motion. When present, all CSS transitions, animations, and view transitions are disabled. Set programmatically by <theme-picker> or <settings-panel>; complements the prefers-reduced-motion media query for users who want motion control per-site rather than system-wide.
data-border-style
Overrides the global border aesthetic. Can also be set on any descendant element for scoped styling.
| Value | Description |
|---|---|
clean | Crisp, minimal borders (default) |
sharp | Zero-radius hard edges |
soft | Large radius, gentle rounding |
sketch | Hand-drawn look with slight irregularity |
rough | Rough, imperfect edges |
marker | Thick marker-stroke borders |
kawaii | Rounded, playful, pastel-friendly |
pixel | Stepped pixel-art corners |
neon | Glowing neon border effect |
double | Classic double-line border |
bubbly | Extra-round, bubbly shapes |
organic | Natural, irregular organic shapes |
<html lang="en" data-border-style="sketch" data-icon-set="lucide">data-icon-set
Sets the default icon library for all <icon-wc> components on the page. Defaults to lucide when omitted. Individual <icon-wc> elements can override this with their own set attribute.
data-icon-path
Sets the base path for loading icon SVG files. Useful when icons are hosted at a custom CDN path. Individual <icon-wc> elements can override with their own path attribute.
data-ruby
Controls the visibility of ruby annotations (<rt> elements) for CJK text.
| Value | Description |
|---|---|
show |
Always show ruby annotations |
hide |
Always hide ruby annotations |
auto |
Show only when document language is ja, zh, or ko |
data-print-raw
When present, disables all Vanilla Breeze print optimizations. The page prints as-is without VB's @media print adjustments. Set automatically by the <print-page> component in "raw" mode.
Combining Attributes
All data attributes can be combined:
<html lang="en" data-page="docs" data-theme="modern" data-mode="dark" data-fluid>Developer Utilities
These attributes are for development and debugging only.
data-debug
Activates debug mode. Shows an overlay banner and highlights HTML content model violations (e.g., block elements inside inline elements). Can also be activated via localStorage.
data-wireframe
Renders the page in wireframe view, stripping visual styling to expose layout structure.
| Value | Description |
|---|---|
lo | Low fidelity — minimal structure outlines |
mid | Medium fidelity — visible element boundaries |
hi | High fidelity — detailed wireframe with labels |
annotate | Annotated wireframe with element names |
<html lang="en" data-debug><!-- or wireframe mode --><html lang="en" data-wireframe="mid">Theme Manager
Vanilla Breeze includes a ThemeManager utility for programmatic theme control with localStorage persistence.
import { ThemeManager } from './lib/theme-manager.js'; // Initialize on page load (applies saved preferences)ThemeManager.init(); // Change modeThemeManager.setMode('dark'); // Force darkThemeManager.setMode('light'); // Force lightThemeManager.setMode('auto'); // Follow system // Change brand theme (personality themes like swiss, brutalist, etc.)ThemeManager.setBrand('swiss'); // Apply swiss themeThemeManager.setBrand('default'); // Reset to default // Change color accentThemeManager.setAccent('ocean'); // Apply ocean accentThemeManager.setAccent('default'); // Reset to default // Toggle between light and darkThemeManager.toggleMode(); // Get current stateconst { mode, brand, accent, effectiveMode } = ThemeManager.getState(); // Listen for changeswindow.addEventListener('vb:theme-change', (e) => { console.log(e.detail); // { mode, brand, accent, effectiveMode }});CSS Reset
VB's reset applies these rules to <html> automatically:
| Property | Effect |
|---|---|
text-size-adjust: none |
Prevents iOS landscape font inflation |
scrollbar-width: thin |
Thin scrollbars on supported browsers |
scrollbar-color |
Themed scrollbar thumb and track via custom properties |
scroll-behavior: smooth |
Smooth anchor scrolling (on html:focus-within only) |
Smooth scrolling is automatically disabled when prefers-reduced-motion: reduce is active.
html { text-size-adjust: none; /* prevent iOS landscape inflation */ scrollbar-width: thin; scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);} html:focus-within { scroll-behavior: smooth; /* smooth anchor scrolling */} @media (prefers-reduced-motion: reduce) { html:focus-within { scroll-behavior: auto; /* respect motion preference */ }}System Preference Detection
VB responds to these @media queries at the :root level. No configuration needed — these activate automatically based on the user's system settings.
| Query | Effect |
|---|---|
prefers-color-scheme |
Automatic light/dark via light-dark() color function |
prefers-reduced-motion |
Sets all --duration-* tokens to 0ms |
prefers-contrast: more |
Stronger borders, bolder text colors, wider focus rings |
prefers-reduced-transparency |
Fully opaque overlays, no backdrop-filter |
forced-colors: active |
Maps tokens to Windows system colors (Canvas, CanvasText, etc.) |
pointer: coarse |
Enforces 44px minimum touch targets (WCAG 2.5.8) |
hover: none |
Disables hover-based motion effects |
The data-mode attribute overrides prefers-color-scheme, and data-motion-reduced complements prefers-reduced-motion for per-site control.
Custom Properties at :root
VB defines its design token system as custom properties on :root. This table shows the major categories — see the Design Tokens page for the full reference.
| Category | Example Properties |
|---|---|
| Colors | --color-primary, --color-text, --color-surface |
| Typography | --font-sans, --font-mono, --line-height-normal |
| Spacing | --size-xs through --size-3xl |
| Borders | --border-radius, --border-width, --color-border |
| Shadows | --shadow-xs through --shadow-xl |
| Motion | --duration-fast, --duration-normal, --ease-default |
| Sizing | --size-touch-min, --focus-ring-width |
Two standalone :root properties are worth noting: color-scheme: light dark enables the light-dark() CSS function for automatic mode switching, and interpolate-size: allow-keywords enables smooth transitions to and from keyword sizes like auto.
Standard Attributes
lang
Sets the document language. Required for accessibility — screen readers use it to select the correct pronunciation engine.
VB's i18n layer responds to lang through :lang() selectors, automatically applying script-appropriate typography:
| Language | Effect |
|---|---|
zh, ja, ko |
CJK font family, line-height: 1.8, word-break: break-all. Japanese adds font-feature-settings: "palt" for proportional punctuation. |
ar, fa, ur, ps |
Arabic script font family, line-height: 1.9, slight word-spacing |
he, yi |
Hebrew font family, line-height: 1.75 |
th |
Thai font family, line-height: 2, no word breaks |
hi, mr, sa, ne |
Devanagari font family, line-height: 1.75 |
Additional lang-driven behaviors:
- Quotation marks: The
<q>element renders locale-correct quotes (English“”, French«», Japanese「」, German„“, Russian«») - Ruby annotations: With
data-ruby="auto", annotations show only for CJK languages - Translation protection:
<code>,<kbd>,<samp>,<pre>, and<var>are markedtranslate: noto prevent machine translation tools from mangling code
dir
Sets the text direction. VB uses CSS logical properties throughout (inline-start/inline-end instead of left/right), so setting dir="rtl" automatically mirrors all layouts.
| Value | Description |
|---|---|
ltr |
Left-to-right (default for most languages) |
rtl |
Right-to-left. VB sets unicode-bidi: embed for correct embedding. |
auto |
Direction determined by content. VB sets unicode-bidi: isolate. Useful for user-generated content (chat messages, comments, form inputs). |
Progressive Enhancement (no-js)
VB does not enforce a no-js pattern, but the following is a recommended approach for pages with web components that need JavaScript fallbacks:
<!DOCTYPE html><html lang="en" class="no-js" data-fluid><head> <script>document.documentElement.classList.replace('no-js', 'js')</script> ...</head>The inline script runs before any content renders, replacing the class synchronously. CSS can then target both states:
.no-js carousel-wc { /* Show all slides as a vertical stack when JS is unavailable */ overflow: visible;} .no-js [data-show-when="js"] { display: none;}Accessibility
- Always set
lang: Screen readers use this to select the correct pronunciation. VB's i18n layer also reads it to apply script-specific typography, locale-aware quotation marks, and ruby annotation visibility. - Theme considerations: The
data-modeattribute works withcolor-schemeCSS to ensure proper contrast and respect user preferences - Motion preferences: Vanilla Breeze respects
prefers-reduced-motionat the system level. Thedata-motion-reducedattribute provides per-site opt-out for users who want motion elsewhere but not on your page. - Accessibility themes: The
a11y-high-contrast,a11y-large-text, anda11y-dyslexiatheme tokens can be combined with any brand theme viadata-theme. - System preferences: VB automatically responds to
prefers-contrast,prefers-reduced-transparency,forced-colors, andpointer: coarse— no opt-in required. - Touch targets: On coarse-pointer devices, interactive elements enforce a 44px minimum size per WCAG 2.5.8.
Related
<head>- Document metadata container<body>- Document content containerdata-page-layout- Page grid structure (set on<body>)- Themes - Full theme catalogue with live previews
- Fluid Scaling - How
data-fluidpresets work <theme-picker>- Interactive theme and mode switcher<settings-panel>- Full settings panel with motion, border-style, and icon controls<icon-wc>- Icon component that readsdata-icon-setanddata-icon-path- Design Tokens - Color, spacing, and typography tokens