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. 

<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 div, p, 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.
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.

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.

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>
  Saved successfully.
</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>

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