Vanilla Breeze

Feel

Small visual and motion details that make Vanilla Breeze interfaces feel considered. Most are already in the framework — this page makes them legible and adds the few that weren't.

Where this list comes from

Jakub Krehel's Details that make interfaces feel better catalogues a dozen small techniques that lift the perceived quality of an interface without adding features. Cross-referenced against Vanilla Breeze, most were already shipped — the framework's reset and tokens already handle balanced text, tabular numerals, smoothed text, staggered entry, separate enter/exit timing, and reduced-motion respect.

This page does two things: it makes the existing primitives findable, and it adds the few details that weren't in VB yet.

Already in VB

DetailWhat VB does
text-wrap: balance on headings Applied globally on h1–h6 and lead paragraphs in src/native-elements/headings/styles.css and paragraph/styles.css. Headings distribute words evenly across lines without per-page tuning.
text-wrap: pretty on body prose Default on p and inside hgroup. Browsers prevent single-word orphans on the last line.
font-variant-numeric: tabular-nums on <time> Default on every <time> element via src/native-elements/inline-semantics/styles.css. Updating digits don't cause horizontal jitter in dates, durations, version strings, or relative-time labels.
-webkit-font-smoothing: antialiased Set in the global reset (src/base/reset.css). Text reads slightly thinner and crisper on macOS without per-component overrides.
Staggered entry animations --motion-stagger-delay in src/tokens/extensions/motion-fx.css. Applied via animation-delay: calc(var(--i) * var(--motion-stagger-delay)) on list items.
Subdued exit timing --motion-exit-duration: 200ms ships separately from --motion-enter-duration: 300ms, so exits feel quicker and less attention-grabbing than entrances.
Reduced-motion respect Both the OS-level prefers-reduced-motion: reduce and the user-controlled :root[data-motion-reduced] attribute collapse stagger, hover lift, and enter/exit durations to zero. Set automatically by <settings-panel>.

Concentric border radius

An outer container's border-radius and the radius of an element nested inside it should look concentric: the inner radius equals the outer radius minus the padding between them. VB ships a CSS helper that derives the inner value automatically.

Parents declare their own radius in --_radius and their padding in --_inset. Children that should hug the parent's inner edge use border-radius: var(--radius-inner).

Image outlines

A 1-pixel outline with outline-offset: -1px sits inside the image edge and gives photographs definition on light or transparent backgrounds without changing layout (which a real border would). Opt-in via data-outlined so existing imagery is unchanged.

The line uses color-mix(in oklch, currentColor 8%, transparent) so it adapts to the surrounding text colour and works equally well in light and dark themes.

Shadow as border (--shadow-flush)

For raised surfaces — cards, popovers, code blocks — a layered shadow reads as edge definition and a touch of elevation, where a flat border: 1px solid reads as just an outline.

Stack with --shadow-md or --shadow-lg to combine edge + lift: box-shadow: var(--shadow-flush), var(--shadow-md);.

Blur-fade entrance

A blur + scale + opacity entrance reads softer than a hard scale-in. Useful for icons, thumbnails, or any element that should feel like it focused into place rather than slid. Pair the symmetric vb-blur-out when you need an exit.

Both honour reduced-motion: the keyframe still runs but at --motion-enter-duration: 0ms, which collapses to an immediate snap.

Transitions for interruptible state, keyframes for one-shot

This is the article's most important subtle point and worth restating as a VB convention:

  • Use a CSS transition when an element moves between persistent states the user can change (open/closed, focused/blurred, hovered/not, dragged/dropped). The browser retargets mid-flight when the user changes intent — the animation never feels like it's fighting the user.
  • Use a keyframe animation for one-shot effects with a defined start and end (entrance, exit, success flash, attention pulse).

VB follows this in practice: <details>, <dialog>, hover lift, focus ring, and form-field hint reveal all use transitions. vb-fade-in, vb-pop, vb-blur-in, and the spinner are keyframe animations. When you reach for one or the other in your own code, the same rule keeps interfaces from feeling brittle.

One the framework can't help you with: optical alignment

No primitive can decide whether an icon needs margin-block-start: 1px to look centred next to text, or whether a triangle needs to shift right of its bounding box to feel balanced. The framework gives you predictable defaults so the cases that need optical adjustment stand out clearly. When they do, override with a small inline style or a one-off CSS rule. Resist the urge to invent a token for it — tokens are for repeating patterns, not per-element vibes.

Related

  • Effect Compositing — how visual effects layer via space-separated data-effect values
  • Typography — the rest of VB's typographic refinement (font synthesis control, sub/sup positioning, drop caps, character tokens)
  • Principles — progressive enhancement, smart defaults, the broader philosophy these details live inside
↑