<!-- Style variants -->
<button class="vt-btn">Primary</button>
<button class="vt-btn vt-btn--outline">Outline</button>
<button class="vt-btn vt-btn--ghost">Ghost</button>
<button class="vt-btn vt-btn--surface">Surface</button>
<button class="vt-btn vt-btn--danger">Danger</button>

<!-- Size variants -->
<button class="vt-btn vt-btn--sm">Small</button>
<button class="vt-btn">Default</button>
<button class="vt-btn vt-btn--lg">Large</button>

<!-- Icon-only button -->
<button class="vt-btn vt-btn--icon" title="Add">
  <svg ...></svg>
</button>
<button class="vt-btn vt-btn--icon vt-btn--outline"><svg ...></svg></button>

<!-- Button with leading/trailing icon -->
<button class="vt-btn">
  <svg ...></svg>
  New Project
</button>

<!-- Disabled state -->
<button class="vt-btn" disabled>Primary</button>
<button class="vt-btn vt-btn--outline" disabled>Outline</button>

<!-- Basic card -->
<div class="vt-card">
  <div class="vt-card__header">
    <h3 class="vt-card__title">Title</h3>
    <p class="vt-card__description">Description</p>
  </div>
  <div class="vt-card__body">Content here.</div>
</div>

<!-- Raised (box shadow) -->
<div class="vt-card vt-card--raised">...</div>

<!-- Interactive (hover glow from brand token) -->
<div class="vt-card vt-card--interactive">...</div>

<!-- Card with footer — footer aligns right above 420px container (container query) -->
<div class="vt-card">
  <div class="vt-card__header">
    <h3 class="vt-card__title">Title</h3>
  </div>
  <div class="vt-card__body">...</div>
  <div class="vt-card__footer">
    <button class="vt-btn vt-btn--surface vt-btn--sm">Cancel</button>
    <button class="vt-btn vt-btn--sm">Confirm</button>
  </div>
</div>

<!-- Default (brand subtle) -->
<span class="vt-badge">Beta</span>

<!-- Solid -->
<span class="vt-badge vt-badge--solid">Active</span>

<!-- Surface (neutral) -->
<span class="vt-badge vt-badge--surface">Draft</span>
<span class="vt-badge vt-badge--surface">v0.1.3</span>

<!-- Semantic status -->
<span class="vt-badge vt-badge--success">Deployed</span>
<span class="vt-badge vt-badge--warning">Degraded</span>
<span class="vt-badge vt-badge--danger">Incident</span>

<!-- With dot indicator -->
<span class="vt-badge vt-badge--success">
  <svg width="8" height="8" viewBox="0 0 8 8">
    <circle cx="4" cy="4" r="4" fill="currentColor"/>
  </svg>
  Healthy
</span>

<!-- Navigation bar -->
<vt-nav logo="My App" version="v1.0"
  links='[{"href":"/","label":"Home"},{"href":"/docs","label":"Docs"},{"href":"/about","label":"About"}]'>
</vt-nav>

<!-- Card -->
<vt-card title="Card title" description="Subtitle">Body content here.</vt-card>
<vt-card title="Raised" variant="raised" footer='<button class="vt-btn vt-btn--sm">Action</button>'></vt-card>

<!-- Alert -->
<vt-alert variant="success" title="Deployed">Version 2.0 is live.</vt-alert>
<vt-alert variant="danger" title="Error" dismissible="false">Payment failed.</vt-alert>

<!-- Badge & Button -->
<vt-badge variant="success">Active</vt-badge>
<vt-button variant="outline" size="sm">Outline</vt-button>

<!-- Modal -->
<vt-modal id="confirm" title="Confirm" confirm="Yes, delete" cancel="Cancel" variant="danger">
  This cannot be undone.
</vt-modal>

<!-- Toast trigger -->
<vt-toast-trigger variant="success" message="Saved!" title="Done">Save changes</vt-toast-trigger>

<!-- Works on any existing element — useful for CMS output, templates -->
<div data-vt-insert="nav"
     data-logo="My App"
     data-links='[{"href":"/","label":"Home"}]'></div>

<div data-vt-insert="alert"
     data-variant="warning"
     data-title="Heads up">Rate limit at 85%.</div>

<div data-vt-insert="card"
     data-title="Hello"
     data-description="Subtitle">Body content</div>

// Render into a target element (replaces innerHTML)
Volty.insert('nav', document.querySelector('header'), {
  logo: 'My App',
  links: [
    { href: '/', label: 'Home' },
    { href: '/docs', label: 'Docs', active: true },
    { href: 'https://github.com/org/repo', label: 'GitHub', external: true },
  ],
});

// Get raw HTML string from any template
const html = Volty.templates.card({
  title: 'Hello',
  description: 'World',
  content: '<p>Body text</p>',
  variant: 'raised',
});

// Re-scan for data-vt-insert after dynamic content is added
Volty.processInserts(document.getElementById('container'));

<!-- Default field -->
<div class="vt-field">
  <label class="vt-label" for="email">Email address</label>
  <input class="vt-input" id="email" type="email" placeholder="you@example.com">
  <span class="vt-hint">We'll never share your email.</span>
</div>

<!-- Required field -->
<div class="vt-field">
  <label class="vt-label vt-label--required" for="name">Full name</label>
  <input class="vt-input" id="name" type="text" placeholder="Jane Smith">
</div>

<!-- Error state -->
<div class="vt-field">
  <label class="vt-label" for="username">Username</label>
  <input class="vt-input vt-input--error" id="username" type="text" value="jane!smith">
  <span class="vt-hint vt-hint--error">Only letters, numbers, and underscores.</span>
</div>

<!-- Disabled -->
<div class="vt-field">
  <label class="vt-label" for="api-key">API Key</label>
  <input class="vt-input" id="api-key" type="text" value="sk-••••••••••••••••" disabled>
  <span class="vt-hint">Contact support to rotate your key.</span>
</div>

<label class="vt-switch">
  <input type="checkbox" checked>
  <span class="vt-switch__track">
    <span class="vt-switch__thumb"></span>
  </span>
  <span class="vt-switch__label">Email notifications</span>
</label>

<!-- Unchecked -->
<label class="vt-switch">
  <input type="checkbox">
  <span class="vt-switch__track"><span class="vt-switch__thumb"></span></span>
  <span class="vt-switch__label">SMS alerts</span>
</label>

<!-- Disabled — :has(input:checked) drives state in CSS, no JS needed -->
<label class="vt-switch">
  <input type="checkbox" disabled>
  <span class="vt-switch__track"><span class="vt-switch__thumb"></span></span>
  <span class="vt-switch__label">Account activity (required)</span>
</label>

<!-- Default (info) -->
<div class="vt-alert" role="alert">
  <div class="vt-alert__icon"><svg ...></svg></div>
  <div class="vt-alert__body">
    <p class="vt-alert__title">Info</p>
    <p class="vt-alert__desc">Your session will expire in 15 minutes.</p>
  </div>
  <button class="vt-alert__dismiss" aria-label="Dismiss"
    onclick="this.closest('.vt-alert').remove()"><svg ...></svg></button>
</div>

<!-- Semantic variants -->
<div class="vt-alert vt-alert--success" role="alert">...</div>
<div class="vt-alert vt-alert--warning" role="alert">...</div>
<div class="vt-alert vt-alert--danger"  role="alert">...</div>

<!-- Solid variant (higher contrast) -->
<div class="vt-alert vt-alert--solid vt-alert--success" role="alert">...</div>
<div class="vt-alert vt-alert--solid vt-alert--danger"  role="alert">...</div>

<!-- data-tooltip — zero markup, pure CSS, no JS -->
<button class="vt-btn" data-tooltip="Saves your current progress">Save</button>
<button class="vt-btn" data-tooltip="Permanently deletes this item"
  data-tooltip-placement="bottom">Delete</button>

<!-- Placement variants: top (default) | bottom | left | right -->
<button data-tooltip="Appears above"  data-tooltip-placement="top">Top</button>
<button data-tooltip="Appears below"  data-tooltip-placement="bottom">Bottom</button>
<button data-tooltip="Appears left"   data-tooltip-placement="left">Left</button>
<button data-tooltip="Appears right"  data-tooltip-placement="right">Right</button>

<!-- Wrap in .vt-field for label + hint layout -->
<div class="vt-field">
  <label class="vt-label" for="region">Region</label>
  <div class="vt-select">
    <select id="region">
      <option>US East (N. Virginia)</option>
      <option>EU (Ireland)</option>
    </select>
  </div>
  <span class="vt-field-hint">Closest to your users.</span>
</div>

<!-- Small size -->
<div class="vt-select vt-select--sm"><select>...</select></div>

<!-- Error state -->
<div class="vt-select vt-select--error">
  <select><option value="">Select a role…</option></select>
</div>
<span class="vt-field-error">A role is required.</span>

<!-- Disabled -->
<div class="vt-select">
  <select disabled><option>Production</option></select>
</div>

<!-- Trigger button -->
<button class="vt-btn" onclick="document.getElementById('my-modal').showModal()">
  Open modal
</button>

<!-- Default modal — entry/exit animation via @starting-style, no JS -->
<dialog class="vt-modal" id="my-modal">
  <div class="vt-modal__header">
    <h2 class="vt-modal__title">Publish changes</h2>
    <button class="vt-modal__close" aria-label="Close"
      onclick="this.closest('dialog').close()"><svg ...></svg></button>
  </div>
  <div class="vt-modal__body">
    <p>Your changes will go live immediately.</p>
  </div>
  <div class="vt-modal__footer">
    <button class="vt-btn vt-btn--surface" onclick="this.closest('dialog').close()">Cancel</button>
    <button class="vt-btn" onclick="this.closest('dialog').close()">Publish</button>
  </div>
</dialog>

<!-- Size variants -->
<dialog class="vt-modal vt-modal--sm" id="rename">...</dialog>
<dialog class="vt-modal vt-modal--lg" id="preview">...</dialog>

<!-- Danger variant -->
<dialog class="vt-modal vt-modal--danger" id="delete">...</dialog>

document.querySelectorAll('.vt-modal').forEach(modal => {
  modal.addEventListener('click', e => {
    if (e.target === modal) modal.close();
  });
});

// Simple message
Volty.toast('Copied to clipboard.')

// With options
Volty.toast({ message: 'Changes saved.', variant: 'success', title: 'Saved' })
Volty.toast({ message: 'Rate limit at 85%.', variant: 'warning', title: 'Warning' })
Volty.toast({ message: 'Could not connect.', variant: 'danger', title: 'Error' })

// Persistent — stays until user dismisses (duration: 0)
Volty.toast({ message: 'Action required.', title: 'Notice', duration: 0 })

// Custom duration in ms (default: 4000)
Volty.toast({ message: 'Deploying…', duration: 8000 })

<!-- Any element with data-theme="dark" always renders dark -->
<div data-theme="dark">
  <div class="vt-card">...</div>
  <button class="vt-btn">Always dark</button>
  <span class="vt-badge vt-badge--success">Active</span>
</div>

<!-- Pin a section to always-light -->
<div data-theme="light">...</div>

// Override theme globally
Volty.setTheme('dark')    // force dark
Volty.setTheme('light')   // force light
Volty.setTheme('system')  // follow OS preference (default)

Volty.getTheme()          // → 'light' | 'dark' | 'system'
Volty.getSystemTheme()    // → 'light' | 'dark' (actual resolved value)

<!-- Scoped brand on any container — entire token scale regenerates -->
<section data-brand="violet">...</section>
<section data-brand="emerald">...</section>
<section data-brand="rose">...</section>
<section data-brand="amber">...</section>
<section data-brand="cyan">...</section>

// Apply brand globally
Volty.setBrand('violet')
Volty.setBrand('emerald')
Volty.setBrand(null)    // reset to default

Volty.getBrand()        // → 'violet' | null

/* Override --vt-color-brand — entire scale (50–950) regenerates via color-mix() */
:root {
  --vt-color-brand: oklch(58% 0.21 310);
}

/* Surface tokens */
--vt-color-surface          /* page background */
--vt-color-surface-raised   /* elevated (sidebars, inputs) */
--vt-color-surface-overlay  /* highest (cards, modals) */

/* Text */
--vt-color-text
--vt-color-text-muted

/* Brand — entire scale (50–950) auto-generated via color-mix() */
--vt-color-brand
--vt-color-brand-subtle
--vt-color-brand-hover
--vt-color-brand-text

/* Semantic */
--vt-color-success  /  --vt-color-success-subtle
--vt-color-warning  /  --vt-color-warning-subtle
--vt-color-danger   /  --vt-color-danger-subtle
--vt-color-info     /  --vt-color-info-subtle

/* Override brand — entire scale regenerates automatically */
:root {
  --vt-color-brand: oklch(58% 0.21 310);
}

/* Type scale — all registered as @property <length> tokens */
--vt-text-xs    /* 12px */
--vt-text-sm    /* 14px */
--vt-text-base  /* 16px */
--vt-text-lg    /* 18px */
--vt-text-xl    /* 20px */
--vt-text-2xl   /* 24px */
--vt-text-3xl   /* 30px */
--vt-text-4xl   /* 36px */
--vt-text-5xl   /* 48px */

/* Font weight tokens */
--vt-font-weight-normal    /* 400 */
--vt-font-weight-medium    /* 500 */
--vt-font-weight-semibold  /* 600 */
--vt-font-weight-bold      /* 700 */

/* Usage example */
.my-heading {
  font-size: var(--vt-text-3xl);
  font-weight: var(--vt-font-weight-bold);
  letter-spacing: -0.02em;
  color: var(--vt-color-text);
}

/* @layer order — declared once, deterministic cascade */
@layer
  volty.reset,       /* box-sizing, margin resets */
  volty.tokens,      /* @property custom properties */
  volty.base,        /* html, body defaults */
  volty.components,  /* .vt-btn, .vt-card, etc. */
  volty.utilities;   /* your overrides — always win */

/* Override any component without specificity battles */
@layer volty.utilities {
  .vt-btn { border-radius: 2px; }
}

/* @property registration (44 tokens total) */
@property --vt-color-brand {
  syntax: '<color>';
  inherits: true;
  initial-value: oklch(55% 0.2 250);
}

/* Volty registers all color tokens as typed <color> via @property */
@property --vt-color-brand {
  syntax: '<color>';
  inherits: true;
  initial-value: oklch(55% 0.2 250);
}

/* :root transitions the token itself — every element inherits the animation */
:root {
  transition:
    --vt-color-brand          350ms ease,
    --vt-color-surface        350ms ease,
    --vt-color-surface-raised 350ms ease,
    --vt-color-text           350ms ease;
}

/* No transition rule needed on components — they animate for free */
.vt-btn {
  background: var(--vt-color-brand); /* animates when brand changes */
  color: var(--vt-color-brand-text);
}

// Each call triggers a smooth 350ms color fade across the entire page
Volty.setBrand('violet')   // → all brand tokens animate to violet
Volty.setTheme('dark')     // → all surface + text tokens animate to dark values

/* Components use container-type — they respond to their own container, not viewport */
.vt-card {
  container-type: inline-size;
  container-name: card;
}

/* Footer aligns right above 420px — no media query needed */
@container card (min-width: 420px) {
  .vt-card__footer { justify-content: flex-end; }
}

/* Buttons go full-width below 280px container */
@container (max-width: 280px) {
  .vt-btn { width: 100%; justify-content: center; }
}

/* Inline field layout above 400px container */
@container (min-width: 400px) {
  .vt-field--inline { flex-direction: row; align-items: center; }
}

/* ❌ Broken approach — mixing into white produces pale muddy tints in dark mode */
background: color-mix(in oklch, var(--vt-color-success) 15%, white);

/* ✅ Volty's approach — mix into surface so dark mode gets rich dark tints */
background: color-mix(in oklch, var(--vt-color-success) 15%, var(--vt-color-surface));

/* This is how all subtle tokens are defined in Volty */
--vt-color-success-subtle: color-mix(
  in oklch,
  var(--vt-color-success) 15%,
  var(--vt-color-surface)   /* dark surface in dark mode → rich dark tint ✓ */
);

/* Usage — tokens adapt automatically in both modes */
.vt-badge--success {
  background: var(--vt-color-success-subtle);
  color: var(--vt-color-success);
}

// Attach shadow root — tokens flow in automatically via @property inherits: true
const shadow = Volty.createShadow(hostElement);
shadow.innerHTML = `<div class="vt-card">
  <div class="vt-card__header">
    <h3 class="vt-card__title">Shadow card</h3>
  </div>
</div>`;

// Adopt component styles into an existing shadow root
Volty.adoptStyles(existingShadowRoot);

// Scoped token override — cascades into all shadow children automatically
Volty.setTokens(hostElement, {
  '--vt-color-brand': 'oklch(55% 0.22 10)',
});

class MyCard extends HTMLElement {
  connectedCallback() {
    const shadow = Volty.createShadow(this);
    shadow.innerHTML = `
      <div class="vt-card vt-card--raised">
        <div class="vt-card__header">
          <h3 class="vt-card__title"><slot name="title"></slot></h3>
        </div>
        <div class="vt-card__body"><slot></slot></div>
      </div>`;
  }
}
customElements.define('my-card', MyCard);

// Usage — all Volty tokens flow in automatically
// <my-card>
//   <span slot="title">Hello from Shadow DOM</span>
//   Body content — tokens cross the boundary for free.
// </my-card>