close
Vitre UI

Vitre UI Documentation

Vitre UI is the transparent style layer and styleless behavior layer for semantic HTML.

Vitre UI is made of two small packages:

This documentation site is plain static HTML using the same unpkg CDN files a no-build application can use.

Overview

Vitre is for pages and small applications that start with semantic HTML. It styles the platform elements first, then adds small behavior conventions only where behavior is actually needed.

Package Role Use it when
vitre-css Classless styling You want semantic elements, forms, tables, code, dialogs, and alerts styled by default.
vitre-js Optional behavior You want progressive interactivity for Vitre-compatible semantic component markup.

Installation

Install the packages you need from npm.

pnpm add vitre-css vitre-js

For static pages without a build step, load the browser files from unpkg.

<link rel="stylesheet" href="https://unpkg.com/vitre-css/vitre-base.css">
<link rel="stylesheet" href="https://unpkg.com/vitre-css/vitre.css">
<script type="module" src="https://unpkg.com/vitre-js/vitre.js"></script>

The unversioned unpkg URLs resolve to the latest published npm versions quickly. Use a pinned URL such as https://unpkg.com/vitre-css@1.5.10/vitre.css when a page needs a fixed dependency version.

Getting Started

Start with ordinary HTML. Vitre CSS styles the elements directly.

<main>
  <section>
    <h1>Account settings</h1>
    <p>Manage your profile and notification preferences.</p>

    <form>
      <label>
        Email
        <input type="email" placeholder="you@example.com">
      </label>

      <button>Save changes</button>
    </form>
  </section>
</main>

If you notice a first paint "flash", "bounce", or "jump" on the initial rendering, copy vitre-base.css to your local project and link to it from the index.html page before vitre.css.

vitre-base.css is an optional first-paint baseline that sets the Vitre theme, typography, background, and page-width styles immediately — before the CDN stylesheet loads. Serving it locally prevents the flash. You can copy the file from the vitre-css npm package or the unpkg CDN. 

<link rel="stylesheet" href="/vitre-base.css">
<link rel="stylesheet" href="https://unpkg.com/vitre-css/vitre.css">

Directives

Vitre uses ordinary HTML attributes as declarative directives. For example, data-color is an attribute in HTML terms, and a Vitre color directive in Vitre usage.

Attribute Used by Purpose
data-theme CSS Force light or dark mode on the root element.
data-kind CSS and JS Identify semantic component patterns such as alert and theme-toggle.
data-color CSS Apply named intent colors: primary, info, success, warning, or error.
data-variant CSS Choose button treatments: flat, outline, ghost, or plain.
dismiss JS Add a generated close button to a supported component.
timeout JS Automatically dismiss a supported component after the given seconds.

Semantic Component Styling

Vitre CSS treats plain document structure as interface structure. Sections become readable panels, articles become self-contained cards, asides become callouts, and forms become complete controls without class names.

Article Card

Nested headers and footers create a natural card anatomy.

Use this pattern for self-contained records, previews, or settings groups.

Updated

Reference

Use the reference sections for markup patterns, live examples, and relevant tokens.

Directives

These are the Vitre-recognized attributes and values used by the current CSS and JS packages.

Attribute Values Used with Effect
data-theme light, dark html Forces the page theme. Omit it to follow the system color scheme.
data-kind alert, theme-toggle, splitter div, p, span, or another semantic container Marks a semantic component for Vitre styling or optional Vitre JS behavior.
data-color primary, info, success, warning, error [data-kind="alert"], button, input buttons, progress, meter Sets semantic intent. Each supported component applies it as an accent, fill, foreground, border, or progress color.
data-variant flat, outline, ghost, plain button Changes the visual treatment of a button while preserving native button behavior.
data-fit contain video, iframe, embed, object Keeps embedded media responsive while preserving its aspect ratio.
data-token Any documented Vitre token swatch name mark Renders a token color swatch for documentation and examples.
data-width narrow, wide, wide-80, full Direct body children (header, main, nav, etc.) Overrides the default --vitre-measure max-width for that element. narrow = 72ch, wide = 72rem, wide-80 = 80vw, full = 100%.
dismiss Boolean attribute [data-kind="alert"] Lets Vitre JS inject a dismiss button.
timeout Seconds, such as 6 or 12 [data-kind="alert"] Lets Vitre JS dismiss the alert automatically after the given delay.
data-v-content Boolean attribute Child element inside [data-kind="alert"] Required wrapper for alert text content when dismiss is present. Reserves the layout slot so the dismiss button aligns correctly before Vitre JS loads.

Colors

The data-color directive sets semantic intent on supported Vitre components. Alerts use it as an accent and soft background, buttons adapt it to the current variant, and progress indicators use it as their bar color.

Value Example Use it for
primary General emphasis tied to the current primary color.
info Neutral guidance, notes, and context.
success Completed, saved, valid, or positive states.
warning Caution, review-needed, or potentially disruptive states.
error Errors, invalid states, and blocking problems.

Themes

Vitre follows the system color scheme by default. Use data-theme to override it.

<html data-theme="dark">

Typography

Vitre styles headings, paragraphs, links, emphasis, marks, blockquotes, code, keyboard hints, metadata, and document edits.

Classless CSS should make the common path beautiful while keeping customization clear.

<p>Use <strong>strong</strong>, <em>emphasis</em>, and <mark>marks</mark> inline.</p>

Lists

Ordered, unordered, and menu lists use the same spacing rhythm as body copy.

  • Semantic defaults
  • Readable spacing
  • Nested content support
  1. Install the stylesheet
  2. Write semantic HTML
  3. Adjust variables when needed

Buttons

Native buttons receive a complete default treatment. Variants use data-variant, and semantic intent uses data-color. 

<button>Default</button>
<button data-variant="flat">Flat</button>
<button data-variant="outline" data-color="error">Delete</button>

Alerts

Alerts use data-kind="alert". Add dismiss or timeout when Vitre JS is loaded.

When using dismiss, wrap the alert text in a child element with data-v-content. This reserves the layout slot for the close button so the alert doesn't reflow when Vitre JS injects it.

Saved successfully. This alert can be dismissed.
Review this warning. It can be dismissed or time out. 
<div data-kind="alert" data-color="success" role="status" dismiss>
  <span data-v-content>Saved successfully.</span>
</div>

Dialogs

Vitre styles native dialogs and dialog-like semantic regions.

Dialog Preview

This non-modal preview uses dialog semantics without opening a native modal.

<dialog>
  <article>
    <h2>Confirm action</h2>
    <button>Close</button>
  </article>
</dialog>

Splitter

A [data-kind="splitter"] with role="separator" renders a resizable divider handle between two panels. It supports both vertical (cursor: col-resize) and horizontal (aria-orientation="horizontal", cursor: row-resize) orientations. The handle highlights on hover, focus, and when actively dragged. 

<!-- Vertical splitter between two panels -->
<div style="display: flex">
  <div>Left panel</div>
  <span data-kind="splitter" role="separator" aria-valuenow="50"></span>
  <div>Right panel</div>
</div>
Variable Default Description
--vitre-splitter-size 0.375rem Width (or height for horizontal) of the splitter handle
--vitre-splitter-bg var(--vitre-border) Default handle background
--vitre-splitter-active-bg var(--vitre-primary) Handle background on hover, focus, or active drag

Semantic Components

Use real HTML structure first: section, article, aside, header, and footer.

Release Notes

A self-contained semantic card.

Version 1.5.10

Forms

Labels, inputs, selects, textareas, fieldsets, validation states, and grouped controls are styled by default.

Within forms, use type="button" for buttons that should not submit the form.

Media

Images, SVG, video, audio, canvas, iframes, objects, and embeds inherit sensible sizing and framing. Iframes keep a responsive aspect ratio by default, and data-fit="contain" is available for framed media that needs the same treatment explicitly.

Inline SVG inside a figure.
Audio example using a local MP3 asset.
Video example using a local MP4 asset.
YouTube embed example for responsive iframe styling.

CSS Variable Reference

Override variables after loading Vitre CSS.

:root {
  --vitre-hue: 168;
  --vitre-primary: hsl(var(--vitre-hue) 76% 42%);
  --vitre-radius: 0.5rem;
}

Color Variables

Variable Preview Role
--vitre-bg Page background
--vitre-text Primary text
--vitre-muted Secondary text
--vitre-subtle Low-emphasis text and quiet UI details
--vitre-primary Links, focus rings, and primary actions
--vitre-primary-ink Text color used on primary action backgrounds
--vitre-surface Panels and elevated surfaces
--vitre-surface-strong Higher-emphasis panel surfaces
--vitre-surface-soft Soft hover and subtle surface fills
--vitre-border Default control, table, and panel borders
--vitre-border-strong Higher-emphasis borders
--vitre-glass Translucent panel background
--vitre-glass-border Translucent panel border
--vitre-mark Highlighted text background
--vitre-info Informational states and alerts
--vitre-info-ink Text color used on informational action backgrounds
--vitre-info-bg Informational alert background
--vitre-success Success states and alerts
--vitre-success-ink Text color used on success action backgrounds
--vitre-success-bg Success alert background
--vitre-warning Warning states and alerts
--vitre-warning-ink Text color used on warning action backgrounds
--vitre-warning-bg Warning alert background
--vitre-error Error states, invalid inputs, and alerts
--vitre-error-ink Text color used on error action backgrounds
--vitre-error-bg Error alert background
--vitre-code-bg Inline and block code background
--vitre-code-text Code text
--vitre-code-border Code block and inline code borders
--vitre-inserted Inserted document text
--vitre-inserted-bg Inserted document background
--vitre-deleted Deleted document text
--vitre-deleted-bg Deleted document background

Variable Groups

Group Variables
Color --vitre-bg, --vitre-text, --vitre-muted, --vitre-primary, --vitre-surface, --vitre-border
Semantic Color --vitre-info, --vitre-success, --vitre-warning, --vitre-error, --vitre-*-ink, --vitre-*-bg
Typography --vitre-font-sans, --vitre-font-mono, --vitre-font-weight, --vitre-leading, --vitre-step-*
Layout --vitre-measure, --vitre-space-*, --vitre-radius, --vitre-shadow
Controls --vitre-control-*, --vitre-button-*, --vitre-focus
Components --vitre-alert-*, --vitre-code-*, --vitre-table-*, --vitre-indicator-color, --vitre-nav-gap