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

Typical Page

A typical Vanilla Breeze page sets global config on <html> and page structure on <body>:

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.

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.

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

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().

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)

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)

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

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:

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

Theme Manager

Vanilla Breeze includes a ThemeManager utility for programmatic theme control with localStorage persistence.

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.

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 marked translate: no to 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:

The inline script runs before any content renders, replacing the class synchronously. CSS can then target both states:

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-mode attribute works with color-scheme CSS to ensure proper contrast and respect user preferences
Motion preferences: Vanilla Breeze respects prefers-reduced-motion at the system level. The data-motion-reduced attribute 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, and a11y-dyslexia theme tokens can be combined with any brand theme via data-theme.
System preferences: VB automatically responds to prefers-contrast, prefers-reduced-transparency, forced-colors, and pointer: coarse — no opt-in required.
Touch targets: On coarse-pointer devices, interactive elements enforce a 44px minimum size per WCAG 2.5.8.

<head> - Document metadata container
<body> - Document content container
data-page-layout - Page grid structure (set on <body>)
Themes - Full theme catalogue with live previews
Fluid Scaling - How data-fluid presets 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 reads data-icon-set and data-icon-path
Design Tokens - Color, spacing, and typography tokens

Welcome to Vanilla Breeze