Inline Text Semantics

Nine semantic inline elements for annotating prose. All inherit parent font size and line height. <mark> is physics-differentiated: glass gets an energy-tinted background, light mode softens the tint, and retro inverts to solid --energy-primary with canvas-colored text.

<p>
  The experiment revealed <mark>a significant energy spike</mark> in
  the reactor core. Previous readings of
  <del>42.7 terawatts</del> were revised to
  <ins>51.3 terawatts</ins> after recalibration. The formula
  <var>E</var> = <var>mc</var><sup>2</sup> governs the conversion,
  where H<sub>2</sub>O serves as the coolant medium.
  <abbr title="Void Energy Reactor Interface">VERI</abbr> logs
  confirm the anomaly. As Dr. Vasquez noted,
  <q>the readings exceed all theoretical models</q>
  (<cite>Void Research Quarterly</cite>). This phenomenon, known as
  <dfn>energy cascade</dfn>, occurs when containment thresholds are
  breached. The <s>original safety protocols</s> have since been
  replaced.
</p>

Mark — Physics Comparison

The <mark> element changes appearance per physics preset. Glass: translucent --energy-primary at 25% opacity. Light mode: softened to 15%. Retro: solid inverted block with zero border-radius. Switch themes to compare.

Individual Elements

Each inline element isolated for reference. del and s share identical styling (strikethrough + --text-mute). ins uses --color-success underline. q adds --energy-secondary colored quote marks. dfn is italic + semibold at --text-main color.

<mark>highlighted text</mark>
<del>deleted text</del>
<s>inaccurate text</s>
<ins>inserted text</ins>
H<sub>2</sub>O
E = mc<sup>2</sup>
<abbr title="Full Name">ABBR</abbr>
<q>inline quotation</q>
<cite>Citation Title</cite>
<dfn>definition term</dfn>

Blockquote

Statement-level quotations with a physics-differentiated left border. Glass: inset glow from --energy-primary. Flat: solid left border. Retro: double border, thicker. Light mode adds a faint primary tint background. Nested blockquotes shift to --energy-secondary. Attribution via <footer> or <cite> inside the blockquote shows an em-dash prefix.

<!-- Simple blockquote -->
<blockquote>
  <p>The void is not empty...</p>
</blockquote>

<!-- With attribution -->
<blockquote>
  <p>Energy cannot be created or destroyed...</p>
  <footer>Dr. Elena Vasquez, <cite>Principles of Void Energy</cite></footer>
</blockquote>

<!-- Nested (border shifts to --energy-secondary) -->
<blockquote>
  <p>Outer quote.</p>
  <blockquote>
    <p>Nested quote with secondary accent.</p>
  </blockquote>
</blockquote>

Figure & Caption

The <figure> element wraps self-contained content (images, diagrams, code blocks) with an optional <figcaption> for description. Margins are reset inline; captions are muted italic at small size.

function initReactor(config: ReactorConfig) {
  const core = new VoidCore(config);
  core.calibrate();
  return core.activate();
}

<!-- Figure with image -->
<figure>
  <img src="diagram.png" alt="Energy distribution map" />
  <figcaption>Figure 1 &mdash; Energy distribution map.</figcaption>
</figure>

<!-- Figure with code block -->
<figure>
  <pre><code>function initReactor() { ... }</code></pre>
  <figcaption>Figure 2 &mdash; Reactor initialization.</figcaption>
</figure>

Address

The <address> element provides contact information. Styled with font-style: normal (overriding the browser default italic) and --text-dim color.

<address>
  Void Energy Research Lab<br />
  Sector 7, Level 42<br />
  New Geneva Research Campus<br />
  contact@void.energy
</address>

Prose Lists

The .prose class re-enables list markers stripped by the global reset. Unordered lists use disc/circle/square nesting with --energy-primary colored markers. In retro physics, markers switch to text characters: -, >, *. Ordered lists use decimal/lower-alpha/lower-roman with semibold markers. Cross-type nesting is supported. Definition lists use semibold terms with indented definitions.

<div class="prose">
  <!-- Unordered: disc → circle → square -->
  <ul>
    <li>Level 1
      <ul>
        <li>Level 2
          <ul><li>Level 3</li></ul>
        </li>
      </ul>
    </li>
  </ul>

  <!-- Ordered: decimal → lower-alpha → lower-roman -->
  <ol>
    <li>Level 1
      <ol>
        <li>Level 2
          <ol><li>Level 3</li></ol>
        </li>
      </ol>
    </li>
  </ol>

  <!-- Cross-type nesting -->
  <ul>
    <li>Unordered parent
      <ol><li>Ordered child</li></ol>
    </li>
  </ul>

  <!-- Definition list -->
  <dl>
    <dt>Term</dt>
    <dd>Definition text.</dd>
  </dl>
</div>

Legal Content

The .legal-content scope class (defined in _typography.scss) re-enables list markers with standard browser styling — no energy coloring. Supports .uppercase and .lowercase ordered list variants, contract-style .subordered counters (1.1, 1.2), and laser-underline links. Use for terms of service, privacy policies, and formal documentation.

<div class="legal-content">
  <!-- Unordered: 3 levels (disc → circle → square) -->
  <ul>
    <li>Item
      <ul><li>Nested
        <ul><li>Third level</li></ul>
      </li></ul>
    </li>
  </ul>

  <!-- Ordered variants -->
  <ol><li>Decimal: 1, 2, 3</li></ol>
  <ol class="uppercase"><li>Upper-alpha: A, B, C</li></ol>
  <ol class="lowercase"><li>Lower-alpha: a, b, c</li></ol>

  <!-- Contract-style sub-numbering -->
  <ol class="subordered">
    <li>Clause
      <ol class="subordered"><li>Sub-clause (1.1)</li></ol>
    </li>
  </ol>

  <!-- Links auto-inherit laser-underline -->
  <p>See the <a href="/docs">documentation</a>.</p>
</div>

Prose vs Legal-Content

Same markup, different scopes. .prose uses energy-colored markers and retro text markers. .legal-content uses standard browser markers. Choose .prose for blogs and user content, .legal-content for formal documents.

Tables

Raw <table> elements are styled automatically — no classes needed. Numbers align with tabular-nums, cell padding scales with density, and borders adapt per physics preset. Hover any row to see the highlight. Opt-in classes: .table-striped for alternating rows, .table-responsive for horizontal scrolling.

<!-- Default table (no classes needed) -->
<table>
  <caption>Subsystem Power Allocation</caption>
  <thead>
    <tr><th>Module</th><th>Status</th><th>Power (kW)</th><th>Uptime</th></tr>
  </thead>
  <tbody>
    <tr><td>Navigation</td><td>Online</td><td>12.4</td><td>99.97%</td></tr>
    <tr><td>Propulsion</td><td>Standby</td><td>4.8</td><td>98.20%</td></tr>
  </tbody>
  <tfoot>
    <tr><td>Total</td><td></td><td>47.9</td><td></td></tr>
  </tfoot>
</table>

<!-- Striped rows (opt-in) -->
<table class="table-striped">...</table>

<!-- Responsive scroll wrapper -->
<div class="table-responsive">
  <table>...wide table...</table>
</div>

Switch atmospheres to see table borders, hover effects, and header treatments change across glass, flat, and retro. Retro shows full grid borders on every cell. Numbers align in columns via tabular-nums.

function computeNext(): SortState {
  const cycle = opts.cycle ?? 'tristate';
  const isActive = opts.current?.key === opts.key;

  if (!isActive) return { key: opts.key, direction: 'ascending' };

  const dir = opts.current?.direction;
  if (dir === 'ascending') return { key: opts.key, direction: 'descending' };

  // dir === 'descending'
  if (cycle === 'tristate') return null;
  return { key: opts.key, direction: 'ascending' };
}

<script lang="ts">
  import { sortable, type SortState } from '@actions/sortable';

  const crew = [
    { name: 'Chen, A.',   duration: 847,  fuel: 62.4 },
    { name: 'Okafor, N.', duration: 234,  fuel: 31.8 },
    // ...
  ];

  let sort: SortState = $state(null);
  const setSort = (next: SortState) => (sort = next);

  const sortedCrew = $derived.by(() => {
    if (!sort) return crew;
    const { key, direction } = sort;
    const dir = direction === 'ascending' ? 1 : -1;
    return [...crew].sort((a, b) => {
      const av = a[key], bv = b[key];
      return av < bv ? -dir : av > bv ? dir : 0;
    });
  });
</script>

<table>
  <thead>
    <tr>
      <th use:sortable={{ key: 'name',     current: sort, onsort: setSort }}>Operator</th>
      <th use:sortable={{ key: 'duration', current: sort, onsort: setSort }}>Duration</th>
      <th use:sortable={{ key: 'fuel',     current: sort, onsort: setSort }}>Fuel %</th>
    </tr>
  </thead>
  <tbody>
    {#each sortedCrew as row (row.name)}
      <tr>...</tr>
    {/each}
  </tbody>
</table>

Media Defaults

Base responsive defaults for media elements. All media is display: block; max-width: 100% by default. <img> alt text renders in italic muted style when the image fails to load. <iframe> gets a physics border and radius. <audio> inherits accent-color from the energy-primary token.

Broken image — alt text fallback (italic, muted, small):

<audio> with native controls — accent-color matches the active atmosphere:

<iframe> — physics border, radius, and sunk background:

<canvas> — block display, responsive:

<!-- Responsive image (block, max-width: 100%, height: auto) -->
<img src="photo.webp" alt="Description" />

<!-- Audio with accent-color -->
<audio controls>
  <source src="track.mp3" type="audio/mpeg" />
</audio>

<!-- Iframe with physics border -->
<iframe src="https://example.com" title="Embedded content"></iframe>

<!-- Canvas (block, responsive) -->
<canvas width="400" height="200"></canvas>

Aspect ratios use Tailwind utilities: aspect-video (16/9), aspect-square (1/1). The [popover] attribute has a global UA reset (margin, padding, border, inset cleared) so custom popovers start from a clean slate.

AI-Generated Narrative (Default — Sanitized)

The default path: bare <Markdown source={x} /> runs the sanitizer and scopes the output to .prose. This is what every AI-generated story beat, help body, or CMS field should pass through.

<script>
  import Markdown from '@components/ui/Markdown.svelte';
  const aiNarrative = `# The Reactor Hums to Life

You step into the **observation chamber**...`;
</script>

<Markdown source={aiNarrative} />

Trusted System String (trusted — Sanitizer Bypassed)

For markdown the application authors and commits to source — changelog entries, help copy, settings descriptions. The trusted flag skips sanitization. Treat the word trusted in any diff as a sanitizer-bypass review surface; never pass it for AI-generated, CMS, or user content.

<Markdown source={trustedChangelog} trusted />

Hostile Input (Sanitizer Stripping)

Demonstrates what the default sanitizer removes from untrusted input: <script> tags, javascript: URLs, <iframe> embeds, and onerror= attributes. The raw input is shown first; the rendered output below contains only safe content.

Raw input string:

# Looks innocent

This story beat seems harmless.

<script>alert('XSS via script tag')</script>

Click [this totally safe link](javascript:alert('XSS via javascript: URL')) to continue.

<iframe src="https://attacker.example.com"></iframe>

<img src="x" onerror="alert('XSS via onerror')" alt="broken">

But the sanitizer strips every payload above before it reaches the DOM.

Rendered output (sanitized):

Looks innocent

This story beat seems harmless.

Click [this totally safe link](javascript:alert('XSS via javascript: URL')) to continue.

But the sanitizer strips every payload above before it reaches the DOM.

<!-- Default <Markdown> always sanitizes — no flag needed -->
<Markdown source={hostileInput} />

Text Selection

The ::selection pseudo-element uses alpha(var(--energy-primary), 25%) as the background and --text-main for text color. Select any text on this page to see the themed highlight — it adapts automatically when you switch atmospheres.

Scrollbars

The @include laser-scrollbar mixin styles all scrollable containers. Glass: translucent thumb with energy glow on hover. Flat: solid minimal thumb with subtle track. Retro: chunky double-width thumb with hard borders. Switch physics presets to compare.

const energyMatrix = [[12.4, 8.1, 22.6, 4.8, 15.3, 9.7, 31.2, 7.5, 18.9, 42.1], [11.8, 7.4, 20.1, 5.2, 14.7, 10.3, 28.9, 8.1, 17.2, 39.8], [13.1, 8.7, 23.4, 4.5, 16.1, 9.2, 32.7, 7.9, 19.5, 43.6]];

// SCSS mixin (from _mixins.scss)
@mixin laser-scrollbar() {
  // Glass (default): translucent thumb, energy glow on hover
  scrollbar-width: thin;
  scrollbar-color: alpha(var(--energy-secondary), 50%) transparent;

  &::-webkit-scrollbar-thumb {
    background: alpha(var(--energy-secondary), 50%);
    border-radius: var(--radius-full);
  }

  // Flat: solid minimal
  @include when-flat {
    scrollbar-color: var(--energy-secondary) var(--bg-sunk);
  }

  // Retro: chunky double-width
  @include when-retro {
    scrollbar-width: auto;
    scrollbar-color: var(--energy-primary) var(--bg-sunk);
  }
}

// Applied globally in _reset.scss:
html {
  @include laser-scrollbar;
}

Applied to html, pre, tables, dialogs, dropdowns, sidebar, and tile containers. The page scrollbar itself demonstrates the effect — scroll this page to see it.

Print Stylesheet

A comprehensive @media print stylesheet optimizes every page for physical output. White canvas, black ink, hidden chrome, and link URLs revealed inline. Use Cmd + P (macOS) or Ctrl + P (Windows/Linux) to preview.

/* _print.scss — key rules */
@media print {
  @page { margin: 2cm; }

  html, body {
    background: white !important;
    color: black !important;
    padding-top: 0 !important;
  }

  /* Hide chrome */
  .nav-bar, .bottom-nav, .breadcrumbs,
  .toast-region, dialog, .page-sidebar-header,
  [popover] {
    display: none !important;
  }

  /* Reveal link URLs */
  a[href^="http"]::after {
    content: " (" attr(href) ")";
    font-size: 0.8em;
    font-style: italic;
  }

  /* Page breaks */
  img, figure, blockquote, pre, table {
    break-inside: avoid;
  }
}

Source: src/styles/base/_print.scss. Last in the _index.scss cascade so it overrides all other rules. !important is justified — print must win.

Container Queries

Component-scoped responsive styles based on container width, not viewport width. Infrastructure is ready — no production components use container queries yet. Two APIs: the @include container-up($breakpoint) SCSS mixin and Tailwind @sm: / @md: / @lg: / @xl: variants.

<!-- Tailwind usage -->
<div class="@container">
  <div class="flex flex-col @md:flex-row gap-md">
    <div class="flex-1">Panel A</div>
    <div class="flex-1">Panel B</div>
  </div>
</div>

// SCSS usage
.my-card {
  container-type: inline-size;

  .my-card-body {
    flex-direction: column;
    @include container-up('md') {
      flex-direction: row;
    }
  }
}

SCSS: @include container-up('sm' | 'md' | 'lg' | 'xl') from _mixins.scss. Tailwind: @sm:, @md:, @lg:, @xl: variants. Parent needs class="@container" (Tailwind) or container-type: inline-size (SCSS).

Toggle

Click to switch between two persistent states. Uses data-state, data-muted, or data-fullscreen.

Hover

Animate on pointer enter via data-state="active". Grouped by usage context.

Search — supports data-zoom variants for zoom-in and zoom-out.

Playback — media and control flow.

Navigation — entry, exit, and state switching.

Actions — content operations and data manipulation. Most use hover animations; Copy uses a click-triggered state toggle (data-state="active") with auto-reset.

Loading

Physics-aware loading indicators: smooth animation in glass/flat, stepped in retro. Each serves a distinct semantic purpose.

LoadingSpin — data fetching, backend requests, and asynchronous operations. The universal spinner for any non-AI loading state.

LoadingSparkle — AI content generation and creative AI processes. A staggered twinkle cascade (main → cross → dot) signals that an AI is actively authoring content.

Static

Display-only icons with no interactive state. Accept only data-size.

Lucide (Static Library)

For generic static icons, use Lucide — an open-source library with 1500+ icons. Below are a few examples; browse the full set at lucide.dev/icons. Always pass class="icon" for base styling and data-size for sizing.

Text Input

Native <input type="text"> with surface-sunk physics. Focus shows the energy-primary border and focus ring. Supports placeholder, disabled, and aria-invalid for error state.

<label for="my-input">Label</label>
<input id="my-input" type="text" placeholder="Enter value..." bind:value />

<!-- Disabled -->
<input type="text" value="Locked" disabled />

<!-- Validation error -->
<input type="text" aria-invalid="true" />
<p class="text-caption text-error">Error message.</p>

All text-like inputs (text, email, password, url) share the same sunk styling. No wrapper component needed.

Textarea

Native <textarea> with vertical resize. Same sunk physics as text inputs. Min-height scales with the density token.

<label for="notes">Description</label>
<textarea id="notes" placeholder="Enter details..." bind:value></textarea>

Validation & FormField

The FormField wrapper handles label association, error messages with icons, hint text, and full ARIA wiring (for, aria-describedby, aria-invalid) automatically. Error borders also activate via the native :user-invalid pseudo-class after user interaction.

Use FormField when you need label + error + hint + ARIA wiring. Use raw aria-invalid for standalone inputs that only need a red border. The :user-invalid pseudo-class fires automatically for native constraints (required, pattern, type="email") after interaction.

<script>
  import FormField from './ui/FormField.svelte';
  let email = $state('');
  let error = $state('');
</script>

<!-- FormField with label, error, hint, and ARIA wiring -->
<FormField label="Email" error={error} required hint="We won't share it.">
  {#snippet children({ fieldId, descriptionId, invalid })}
    <input
      type="email"
      id={fieldId}
      required
      aria-invalid={invalid}
      aria-describedby={descriptionId}
    />
  {/snippet}
</FormField>

<!-- Low-level: border-only error (no wrapper needed) -->
<input type="text" aria-invalid="true" />

Select

The Selector component wraps a native <select> with label association and layout. Zero custom dropdown JS — the browser handles the dropdown entirely. Native form attributes pass through to the underlying <select>.

Props: options, value (bindable), label, placeholder, disabled. Supports align="start" for left-aligned labels. Native form submission serializes String(option.value).

<script>
  import Selector from './ui/Selector.svelte';
</script>

<Selector
  bind:value
  label="Role"
  options={[
    { value: 'viewer', label: 'Viewer' },
    { value: 'editor', label: 'Editor' },
    { value: 'admin', label: 'Admin' },
  ]}
/>

Range Slider

Native <input type="range"> with accent-color set to the energy-primary token. The browser draws the track and thumb natively.

<label for="volume">Volume — {value}%</label>
<input id="volume" type="range" bind:value min="0" max="100" />

Date & Time

Native <input type="date">, <input type="time">, and <input type="datetime-local"> with themed picker indicators and segment styling. The OS-level calendar/clock popup is native — SCSS styles the trigger icon, internal text segments, and focus highlights to match the active atmosphere.

<label for="date">Launch Date</label>
<input id="date" type="date" bind:value />

<label for="time">Launch Time</label>
<input id="time" type="time" bind:value />

<label for="datetime">Full Schedule</label>
<input id="datetime" type="datetime-local" bind:value />

<!-- With FormField for label + error + hint -->
<FormField label="Launch Date" error={dateError} hint="Select a future date.">
  {#snippet children({ fieldId, descriptionId, invalid })}
    <input type="date" id={fieldId} aria-invalid={invalid}
      aria-describedby={descriptionId} />
  {/snippet}
</FormField>

No wrapper component needed — these are styled natively in _inputs.scss. Use with FormField for label/hint/error wiring. The picker icon color is handled by color-scheme (dark/light). Individual date segments highlight with energy-primary on focus.

Color Picker

Two approaches: a standalone native <input type="color"> swatch (styled in _inputs.scss), and the ColorField composite that adds a hex value display alongside the swatch preview. Both open the OS-native color picker dialog.

<!-- Native swatch only -->
<input type="color" bind:value aria-label="Pick a color" />

<!-- ColorField composite (swatch + hex) -->
<script>
  import ColorField from './ui/ColorField.svelte';
  let color = $state('#7c3aed');
</script>

<ColorField bind:value={color} />
<ColorField bind:value={color} onchange={handleChange} />
<ColorField value="#6b7280" disabled />

<!-- With FormField -->
<FormField label="Brand Color" hint="Dashboard theme color." fieldId="brand-color">
  {#snippet children({ fieldId, descriptionId, invalid })}
    <ColorField id={fieldId} describedby={descriptionId} {invalid} bind:value={color} />
  {/snippet}
</FormField>

The native <input type="color"> renders as a --control-height square swatch with surface-sunk physics. Use ColorField when you need the hex value visible alongside the swatch. Props: value (bindable), onchange, disabled.

Checkbox & Radio

Native <input type="checkbox"> and <input type="radio"> with accent-color. Size scales with the density token. No custom styling — the browser handles checked states, focus, and accessibility.

<fieldset>
  <legend>Notifications</legend>
  <label class="flex flex-row items-center gap-xs">
    <input type="checkbox" checked />
    <span>Email alerts</span>
  </label>
  <label class="flex flex-row items-center gap-xs">
    <input type="checkbox" />
    <span>Push notifications</span>
  </label>
</fieldset>

<fieldset>
  <legend>Layout</legend>
  <label class="flex flex-row items-center gap-xs">
    <input type="radio" name="layout" checked />
    <span>Grid</span>
  </label>
  <label class="flex flex-row items-center gap-xs">
    <input type="radio" name="layout" />
    <span>List</span>
  </label>
</fieldset>

Checkboxes and radios have physics-aware enhancements: glass mode adds a glow on :checked, retro mode scales controls up by 15%. Fieldsets highlight with energy-primary border and legend color on :focus-within. Switch to glass or retro atmospheres and interact with the controls above to see the effects.

Toggle

Physics-aware switch for boolean states. Supports custom Lucide icons, emoji icons, hidden icons, and disabled state. The thumb animates between positions using spring transitions. Retro mode uses instant snapping.

<script>
  import Toggle from './ui/Toggle.svelte';
  import { Sun, Moon } from '@lucide/svelte';
  let checked = $state(false);
</script>

<Toggle bind:checked label="Dark Mode" />
<Toggle bind:checked label="Theme" iconOn={Sun} iconOff={Moon} />
<Toggle bind:checked label="Minimal" hideIcons />
<Toggle checked={false} label="Locked" disabled />

Props: checked (bindable), label, iconOn/iconOff (Component or string), hideIcons, disabled.

Switcher

Segmented control for selecting between N options. Built on native radio inputs with a shared group name, so keyboard behavior follows browser-default radio interaction (Tab + Arrow keys). Native form submission uses the browser's string value for the checked option.

Props: options (value, label, icon?), value (bindable), label, name, required, form, and disabled.

<script>
  import Switcher from './ui/Switcher.svelte';
  let value = $state('option-a');
</script>

<Switcher
  bind:value
  label="View Mode"
  options={[
    { value: 'grid', label: 'Grid' },
    { value: 'list', label: 'List' },
    { value: 'table', label: 'Table' },
  ]}
/>

Details & Summary

Native <details> disclosure element for collapsible sections. Zero JS — the browser handles open/close, keyboard support (Enter/Space), and accessibility. SCSS adds border, chevron indicator, and smooth expand/collapse animation via ::details-content. Use the name attribute for exclusive accordion groups.

<!-- Single disclosure -->
<details>
  <summary>Section Title</summary>
  <div class="p-md">Content here</div>
</details>

<!-- Exclusive accordion group -->
<details name="my-group" open>
  <summary>Panel A</summary>
  <div class="p-md">...</div>
</details>
<details name="my-group">
  <summary>Panel B</summary>
  <div class="p-md">...</div>
</details>

Add name="group" to multiple <details> elements for exclusive accordion behavior (only one open at a time). Nest <fieldset> inside for semantic form grouping.

Progress Bar

Fully custom-styled <progress> element. Pill-shaped fill bar with energy-primary color, density-scaled height. Glass mode adds a glow to the fill. Retro squares the bar and uses a stepped shimmer for indeterminate state.

<!-- Determinate -->
<progress value="65" max="100"></progress>

<!-- Indeterminate -->
<progress></progress>

The indeterminate state activates when the value attribute is absent. Glass adds a glowing fill; retro uses a stepped scan-line shimmer.

Meter

Native <meter> element for scalar measurements. Three semantic color ranges — optimum (success green), sub-optimum (premium amber), and danger (error red). The browser selects the color based on low/high/optimum attributes.

<!-- Optimum (green) -->
<meter min="0" max="100" low="25" high="75" optimum="80" value="90"></meter>

<!-- Sub-optimum (amber) -->
<meter min="0" max="100" low="25" high="75" optimum="80" value="50"></meter>

<!-- Danger (red) -->
<meter min="0" max="100" low="25" high="75" optimum="80" value="10"></meter>

Same dimensions as <progress> for visual consistency. Glass mode adds a glow on the optimum value. No classes needed — the browser determines the color zone from the attributes.

Output

The <output> element for computed/calculated values. Styled as a data pill — monospace font with tabular-nums, energy-primary tinted background, pill shape. Retro mode shows a bordered box.

<output>{computedValue}</output>

<!-- With form association -->
<form oninput="result.value = parseInt(a.value) + parseInt(b.value)">
  <input type="range" id="a" value="50"> +
  <input type="number" id="b" value="25"> =
  <output name="result" for="a b">75</output>
</form>

Monospace font with tabular-nums ensures numbers align consistently. The pill background uses alpha(energy-primary, 10%).

File Upload

Drag-and-drop file upload via the DropZone component. Wraps a native <input type="file"> with drag detection, type/size validation, and physics-aware active state. Drop files onto the zone or click to browse.

<script>
  import DropZone from './ui/DropZone.svelte';
</script>

<!-- Basic (any file) -->
<DropZone onfiles={(files) => console.log(files)} />

<!-- Restricted (type + size) -->
<DropZone
  accept=".json,.csv"
  maxSize={2 * 1024 * 1024}
  onfiles={handleFiles}
/>

<!-- Multiple files -->
<DropZone multiple onfiles={handleFiles} />

Props: accept (file type filter), maxSize (bytes), multiple, onfiles (callback). Invalid files are rejected with toast errors. Drag-over triggers data-state="active" with shadow elevation and subtle scale-up; retro physics uses a thicker border instead.

Input Fields

Each field wraps a native <input> inside a .field container. The input keeps all native styling (surface-sunk, focus ring, border). Icon slots are absolutely positioned via .field-slot-left / .field-slot-right, with input padding adjusting automatically to make room.

<script>
  import SearchField from './ui/SearchField.svelte';
  import { createPasswordValidation } from '@lib/password-validation.svelte';
  import PasswordField from './ui/PasswordField.svelte';
  import PasswordMeter from './ui/PasswordMeter.svelte';
  import PasswordChecklist from './ui/PasswordChecklist.svelte';
  import FormField from './ui/FormField.svelte';
  import EditField from './ui/EditField.svelte';
  import EditTextarea from './ui/EditTextarea.svelte';
  import CopyField from './ui/CopyField.svelte';
  import GenerateField from './ui/GenerateField.svelte';
  import GenerateTextarea from './ui/GenerateTextarea.svelte';

  let password = $state('');
  let confirm = $state('');

  const pv = createPasswordValidation(
    () => password,
    () => confirm,
    { requireConfirm: true },
  );
</script>

<SearchField
  bind:value={query}
  placeholder="Search..."
  onsubmit={(v) => console.log(v)}
/>

<FormField error={pv.error}>
  {#snippet children({ fieldId, descriptionId, invalid })}
    <PasswordField
      id={fieldId}
      bind:value={password}
      {invalid}
      describedby={descriptionId}
      autocomplete="new-password"
    />
  {/snippet}
</FormField>
<PasswordMeter password={password} validation={pv} />
<PasswordChecklist password={password} validation={pv} />
<PasswordField bind:value={confirm} autocomplete="new-password" />
<button disabled={!pv.isValid}>Submit</button>

<EditField
  bind:value={name}
  placeholder="Identifier..."
  onconfirm={(v) => save(v)}
/>

<EditTextarea
  bind:value={notes}
  placeholder="Notes..."
  rows={4}
  onconfirm={(v) => save(v)}
/>

<CopyField value="sk-secret-key-here" />

<GenerateField
  bind:value={title}
  placeholder="Project title..."
  instructions="Generate a catchy title"
  ongenerate={generateText}
/>

<GenerateTextarea
  bind:value={bio}
  placeholder="About..."
  instructions="Generate a professional bio"
  ongenerate={generateText}
  rows={4}
/>

SearchField — value (bindable), placeholder, zoom ("in" | "out"), autocomplete (default "off"), onsubmit, oninput. PasswordField — value (bindable), placeholder, invalid, describedby, autocomplete (default "current-password"). PasswordMeter — password (string), validation (PasswordValidationState). Hidden when empty. Four levels: Weak, Fair, Good, Strong. PasswordChecklist — password (string), validation (PasswordValidationState). Hidden when empty. EditField — value (bindable), placeholder, autocomplete, onconfirm. EditTextarea — value (bindable), placeholder, rows (number), onconfirm. Ctrl/Cmd+Enter confirms. CopyField — value (readonly string). GenerateField — value (bindable), placeholder, instructions (AI prompt context), ongenerate (async handler). GenerateTextarea — same as GenerateField plus rows (number). All accept id, disabled, and class.

Slider Field

A range slider with optional preset snap points. When presets are provided, the slider locks to those values only — like a visual <select>. Without presets it degrades to a plain labeled range input. Works at any scale: 3 presets or 7.

<script>
  import SliderField from './ui/SliderField.svelte';

  let quality = $state(50);
  const presets = [
    { label: 'MIN', value: 0 },
    { label: 'STANDARD', value: 50 },
    { label: 'MAX', value: 100 },
  ];
</script>

<!-- With presets: locks to preset values -->
<SliderField bind:value={quality} label="Quality" presets={presets} />

<!-- Without presets: plain continuous range -->
<SliderField bind:value={volume} label="Volume" />

Props: value (bindable), presets (SliderFieldPreset[] — label/value pairs; locks slider to preset values), min, max, step (ignored when presets are provided), label, onchange, disabled, class. Presets should be sorted ascending by value.

Media Controls

Horizontal control bars for audio and media. The mute toggle uses data-muted to cross out the icon and dim the slider. The play/pause icon cross-fades smoothly via data-paused.

<script>
  import MediaSlider from './ui/MediaSlider.svelte';
  let volume = $state(65);
  let muted = $state(false);
  let paused = $state(false);
</script>

<MediaSlider bind:volume bind:muted bind:paused icon="voice" playback replay />
<MediaSlider bind:volume bind:muted bind:paused icon="music" playback />

Props: volume (bindable), muted (bindable), icon ("voice" | "music"), playback (boolean), paused (bindable), replay (boolean), onchange, onmute, onpause, onreplay (callbacks).

Action Button

ActionBtn composes any interactive icon with a text label. The button's hover state drives the icon animation via data-state forwarding. Pass any btn-* variant class to change the visual style.

Try different icon and style combinations. Hover the button to see the icon animate. Sparkle is the default fit for AI and generation actions.

<script>
  import ActionBtn from './ui/ActionBtn.svelte';
  import Sparkle from './icons/Sparkle.svelte';
</script>

<!-- AI / generate action -->
<ActionBtn icon={Sparkle} text="Generate" class="btn-cta" onclick={generate} />

<!-- Swap icon / variant as needed -->
<ActionBtn icon={DoorOut} text="Sign Out" class="btn-error" />

Props: icon (Component), text (label), class (btn-* variant). All native button attributes pass through.

Icon Button

IconBtn is a circular icon-only button (.btn-icon) that forwards hover state to the icon via data-state. It encapsulates the hover tracking boilerplate — no manual onpointerenter/onpointerleave needed. Compare with ActionBtn which adds a text label and styled button variants.

<script>
  import IconBtn from './ui/IconBtn.svelte';
  import Refresh from './icons/Refresh.svelte';
</script>

<IconBtn icon={Refresh} aria-label="Refresh" />
<IconBtn icon={Refresh} size="xl" onclick={handler} />

Props: icon (Component), size (icon size scale, default lg), class (additional classes). All native button attributes pass through (onclick, disabled, aria-*).

Theme Button

ThemesBtn combines a Lucide Moon/Sun icon with a button that opens the theme modal. The icon switches reactively based on the current color mode. Supports a labeled variant (default) and an icon-only variant via the icon prop.

<script>
  import ThemesBtn from './ui/ThemesBtn.svelte';
</script>

<!-- Labeled button (default) -->
<ThemesBtn />

<!-- Icon-only -->
<ThemesBtn icon size="xl" />

<!-- With variant class -->
<ThemesBtn class="btn-cta" />

Props: icon (boolean — icon-only mode), size (icon size scale), class (style variants).

Settings Row

SettingsRow is a label + content layout for settings panels. On desktop it renders as a two-column grid (label left, controls right); on mobile it stacks vertically. Used throughout the Settings modal and the intro page sandbox.

<script>
  import SettingsRow from './ui/SettingsRow.svelte';
  import Toggle from './ui/Toggle.svelte';
  import Selector from './ui/Selector.svelte';
</script>

<SettingsRow label="Notifications">
  <Toggle bind:checked label="Enabled" />
</SettingsRow>

<SettingsRow label="Density">
  <Selector bind:value options={layoutOptions} />
</SettingsRow>

<SettingsRow label="Actions">
  <button>Export</button>
  <button class="btn-error">Reset</button>
</SettingsRow>

Props: label (string — left column heading). Content is passed as a Svelte snippet (slot). The label column is 12rem wide on desktop.

Combobox

Combobox is an input/select hybrid: type to filter a list of options, navigate with arrow keys, commit with Enter. Unlike Selector (which wraps a native <select>), Combobox supports client-side filtering, rich option descriptions, and optional free-text entry. Form submission is handled via a hidden input; the visible input is intentionally unnamed.

<script>
  import Combobox from './ui/Combobox.svelte';

  const countries = [
    { value: 'fr', label: 'France', description: 'Paris, Lyon' },
    { value: 'de', label: 'Germany', description: 'Berlin, Munich' },
    { value: 'jp', label: 'Japan', disabled: true },
  ];
  const suggestions = [
    { value: 'svelte', label: 'Svelte' },
    { value: 'react', label: 'React' },
  ];
  let country = $state(null);
  let tag = $state(null);
</script>

<Combobox options={countries} bind:value={country} placeholder="Search..." />

<!-- Clearable with commit callback -->
<Combobox options={countries} bind:value={country} clearable onchange={(value) => console.log(value)} />

<!-- With form submission -->
<Combobox options={countries} bind:value={country} name="country" />

<!-- Allow free-text entry -->
<Combobox options={suggestions} bind:value={tag} allowCustomValue />

Props: options (Array of { value, label, description?, disabled? }), value (string | number | null, bindable), open (bindable), name/form (route to hidden input — not the visible input), allowCustomValue (free text on Enter), clearable (shows × when a value is selected — clears to null), required (maps to aria-required only — no native constraint validation in v1), oninput (keystroke callback for async loading), onchange (commit callback). All other HTMLInputAttributes forward to the visible input.

Current State

Login / Logout

Two-Phase Hydration

Phase 1: synchronous cache read (constructor). Phase 2: refresh(fetcher) verifies against the server. The fetcher returns a typed VoidResult, so transport and payload failures stay out of the component tree.

Login first, then click to simulate a 1.5s API verification. The user name updates to confirm the refresh completed.

Profile Button

Role-aware avatar with tab styling for navbar use. Players show their profile picture, all other roles show a role initial badge (G/A/C), and unauthenticated visitors see a silhouette icon. The chevron signals a dropdown menu that works for both auth states. Use the login buttons above to switch between roles.

Player (avatar image) · Admin / Creator / Guest (initial badge) · Unauthenticated (silhouette icon). Login as each role to see the difference. Hard-refresh (Cmd+Shift+R) to verify no avatar flash.

FOUC Prevention

UserScript.astro sets data-auth on <html> before first paint. CSS utilities .auth-only / .public-only react immediately — no flash. Login, then hard-refresh to verify.

Nav Integration

ProfileBtn is designed for navbar use with the built-in Nav Menu Pattern. Navigation.svelte contains a step-by-step blueprint for a burger-triggered dropdown menu with ProfileBtn as the trigger. The pattern includes scrim, hover control, expandable sections, stagger animation, and Escape-to-close.

<!-- In Navigation.svelte, replace ThemesBtn with ProfileBtn trigger -->
<button
  class="btn-void text-primary tab ml-auto"
  onclick={() => (menuOpen = !menuOpen)}
  aria-expanded={menuOpen}
  aria-controls="profile-menu"
>
  <ProfileBtn />
</button>

<!-- Menu items adapt to auth state -->
{#if menuOpen}
  <div id="profile-menu" class="nav-menu" role="menu">
    {#if user.isAuthenticated}
      <a class="subtab" href="/profile">My Profile</a>
      <a class="subtab" href="/settings">Settings</a>
      <hr />
      <button class="btn-ghost btn-error">Sign Out</button>
    {:else}
      <a class="subtab" href="/login">Sign In</a>
      <a class="subtab" href="/register">Create Account</a>
    {/if}
  </div>
{/if}

This demo app only has 2 pages, so the profile menu is not wired into the actual navbar. The pattern is production-ready — uncomment and adapt the blueprint in Navigation.svelte.

Developer Mode

Local preference, not a server role. Resets on logout.

Image

Native <img> wrapper. The wrapper carries any CSS aspect-ratio you set (16 / 9, 1 / 1, 9 / 16, 21 / 9, etc.) so layout doesn't shift while the source loads. objectFit defaults to cover and accepts contain, fill, none, or scale-down for letterbox-style content. Lazy by default; pass lazy={false} for above-the-fold imagery. The skeleton shimmer is visible on every initial load — below, a working image alongside the error state when src is broken.

Working — image fades in on load

Broken src — ImageOff icon

<Image src="/hero.jpg" alt="Hero" aspectRatio="16 / 9" />
<Image src="/portrait.jpg" alt="Portrait" aspectRatio="9 / 16" />
<Image
  src="/banner.jpg"
  alt="Banner"
  aspectRatio="21 / 9"
  lazy={false}
/>
<Image
  src="/logo.svg"
  alt="Logo"
  aspectRatio="3 / 1"
  objectFit="contain"
/>

Avatar

Circular user representation. Five sizes mapped to the spacing scale: xs (--space-md, used by ProfileBtn for dense nav contexts), sm (--space-lg, compact lists), md (--space-xl, default for general use), lg (--space-2xl, profile cards), and xl (--space-3xl, hero / settings). Width and initials font scale together via coupled local CSS variables. When src is missing or fails to load, Avatar swaps to initials derived from name (first + last initial, max 2 chars, uppercase).

Presence dot

Optional presence prop with four semantic colors. Border uses --bg-canvas so the dot reads cleanly against any backdrop.

online

busy

M

away

Q

offline

Member list (composition)

Mixed image and initials avatars at sm in a typical list layout.

Jane Doe online

AL

Alex Lin away

QR

Quinn Reyes offline

<Avatar name="Jane Doe" />
<Avatar src="/jane.jpg" name="Jane Doe" size="lg" />
<Avatar
  src="/jane.jpg"
  name="Jane Doe"
  size="xl"
  presence="online"
/>
<Avatar name="Quinn" presence="busy" />

Video

Native <video> wrapper. Defaults: controls={true}, preload="metadata", aspectRatio="16 / 9". For non-16:9 content set aspectRatio directly (9 / 16 for portrait, 1 / 1 for square, etc.). Pass through native attributes (autoplay, muted, loop, playsinline) for background-loop patterns. <source> and <track> elements pass through as children. For custom playback chrome, set controls={false}, capture the inner element via bind:element, and pair with <MediaScrubber> on top (timeline) and <MediaSlider> below (transport + volume) — demo at the bottom.

Standard playback & error state

Native browser controls with poster on the left. Broken src on the right surfaces the VideoOff icon over the --bg-sunk placeholder; preload="auto" is set on the error demo so the browser actually fetches and the 404 triggers the error event — with the default preload="metadata" modern browsers may defer the fetch until user interaction, hiding broken-source failures behind the play affordance.

Background loop

controls={false} with autoplay muted loop playsinline — browsers gate autoplay on muted; this combo plays without a user gesture.

Custom controls (MediaScrubber + MediaSlider)

Capture the inner <video> via bind:element and bind paused on <Video> — the binding is bidirectional, so the same state drives MediaSlider's play button and reflects autoplay, click, and end-of-clip back. <MediaScrubber> takes the element ref and owns its own timeupdate / durationchange listeners. clickToPlay on Video makes the pixels themselves toggle pause/play — the universal web-player convention. The two-row layout (timeline above, transport & volume below) mirrors Plyr / Vidstack / Video.js.

<!-- Standard -->
<Video src="/clip.mp4" poster="/poster.jpg" />

<!-- Background loop -->
<Video
  src="/loop.mp4"
  controls={false}
  autoplay muted loop playsinline
/>

<!-- Vertical -->
<Video src="/short.mp4" aspectRatio="9 / 16" />

<!-- With captions -->
<Video src="/clip.mp4">
  <track
    kind="captions"
    src="/captions.vtt"
    srclang="en"
    label="English"
    default
  />
</Video>

<!-- Custom controls (two-row: scrubber + transport/volume) -->
<Video
  src="/clip.mp4"
  controls={false}
  clickToPlay
  bind:element={videoEl}
  bind:paused
/>
<MediaScrubber element={videoEl} />
<MediaSlider
  bind:volume bind:muted bind:paused playback replay onreplay={replay}
/>

Adaptive Image

Selects between consumer-supplied source URLs based on the active atmosphere's physics × mode — the two finite axes (five valid combinations: glass-dark, flat-dark, flat-light, retro-dark, retro-light). Built on the same .image SCSS surface as <Image> (skeleton, error, aspect-ratio, opacity fade) but holds the previous frame across atmosphere-driven swaps via Image().decode() — no skeleton flash, no opacity reset. Never modifies pixels — selects only between URLs the consumer provides. The demo below binds glass, retro, dark, and light to distinct picsum seeds; the flat physics-prop is intentionally omitted so flat atmospheres fall through to the mode-prop — giving four visually distinct images, one per valid physics × mode combination. Switch atmospheres via the navigation to watch the resolver advance.

<!-- Full variant set -->
<AdaptiveImage
  src="/hero.jpg"
  dark="/hero-dark.jpg"
  light="/hero-light.jpg"
  glass="/hero-glass.jpg"
  flat="/hero-flat.jpg"
  retro="/hero-retro.jpg"
  alt="Hero image"
  aspectRatio="16 / 9"
/>

<!-- Single override (others fall through to src) -->
<AdaptiveImage
  src="/hero.jpg"
  glass="/hero-glass.jpg"
  alt="Hero image"
  aspectRatio="16 / 9"
/>

<!-- Precedence: physics > mode > src -->
<AdaptiveImage
  src="/hero.jpg"
  dark="/hero-dark.jpg"
  glass="/hero-glass.jpg"
  alt="Hero image"
  aspectRatio="16 / 9"
/>

Semantic Types

Each type sets the border, background blend, and icon color via the --toast-accent variable. Click to trigger each type.

Warning toasts use the Premium accent color — both signal “pay attention” and share the same visual weight.

Action Buttons

Toasts can include an inline action button for "undo over confirmation" patterns. The toast.undo() convenience method shows a success toast with an Undo button that fires a callback when clicked.

Click the action button inside the toast to trigger the callback. Use the X button to dismiss a toast early, or wait for auto-dismiss.

Long Messages

Toasts gracefully handle longer content. The capsule stretches horizontally to fit, capped by the region’s max-width.

Keep messages concise when possible, but longer text is fully supported for cases that need additional context.

Loading Controller

toast.loading() returns a controller with .update(), .success(), .error(), .warning(), and .close(). The toast persists until a terminal method is called.

Each button demonstrates a different resolution path. The loading toast persists until a terminal method (.success(), .error(), or .warning()) is called.

Promise Wrapper

toast.promise() wraps any Promise with automatic loading → success/error transitions. The success message can be a function that receives the resolved value.

Clear All

toast.clearAll() removes every active toast at once. Click “Stack Toasts” to fire several in quick succession, then “Clear All” to sweep them away.

Useful for page transitions or state resets where stale notifications should not persist.

Alert

modal.alert(title, body) opens a small informational dialog with a single acknowledge button. The helper body is plain text. Use modal.open(...) with bodyHtml when trusted internal markup is required. Size defaults to sm.

Confirm

modal.confirm(title, body, actions) opens a dialog with confirm and cancel buttons. The helper body is plain text. Use modal.open(...) with bodyHtml for trusted internal markup. Supports an optional cost badge displayed on the confirm button via tooltip. Size defaults to md.

Actions: onConfirm (required), onCancel (optional), cost (optional number shown as badge).

Themes & Settings

Convenience methods for built-in modals. modal.themes() opens the atmosphere/theme selector. modal.settings() opens the display preferences panel. Both use the lg size.

Command Palette & Shortcuts

modal.palette() opens a fuzzy-search command palette (md size). modal.shortcuts() opens a keyboard shortcut reference grouped by category (sm size). The command palette is also wired to Cmd + K / Ctrl + K globally.

The shortcuts modal reads from shortcutRegistry.entries — any shortcut registered via the registry appears automatically.

Sizes

Four dialog sizes control width: sm (alerts, confirmations), md (forms, selections), lg (complex panels), full (immersive experiences that fill the viewport). Pass the size as the third argument to modal.open().

Custom Fragments

Add your own modal content by creating a fragment component, registering it in the modal registry, and opening it via modal.open(). Three steps:

// 1. Create the fragment component
// src/components/modals/InviteFragment.svelte
<script lang="ts">
  let { email, onInvite }: {
    email: string;
    onInvite: (email: string) => void;
  } = $props();
</script>

<div class="flex flex-col gap-lg p-xl">
  <h2 id="modal-title">Invite User</h2>
  <p>Send an invitation to <strong>{email}</strong></p>
  <div class="flex justify-end gap-md">
    <button class="btn-ghost btn-error" onclick={() => modal.close()}>
      Cancel
    </button>
    <button class="btn-cta" use:laserAim onclick={() => onInvite(email)}>
      Send Invite
    </button>
  </div>
</div>

// 2. Register in src/config/modal-registry.ts
import InviteFragment from '@components/modals/InviteFragment.svelte';

export const MODAL_KEYS = {
  // ...existing keys
  INVITE: 'invite',
} as const;

export const modalRegistry = {
  // ...existing entries
  invite: InviteFragment,
};

// 3. Open from anywhere
modal.open(MODAL_KEYS.INVITE, {
  email: 'user@example.com',
  onInvite: (email) => sendInvite(email),
}, 'md');

Fragment props are type-checked via ModalContract in src/types/modal.d.ts. Add a matching entry there to get full type safety on modal.open() calls.

Svelte Actions

Reusable directives that add behavior to any element via use:action. These are the building blocks behind several composite components.

<script>
  import { morph } from '@actions/morph';
  import { navlink } from '@actions/navlink';
</script>

<!-- Morph: smooth height animation on content change -->
<div use:morph={{ width: false }}>
  {#if expanded}
    <p>Long content...</p>
  {:else}
    <p>Short content.</p>
  {/if}
</div>

<!-- Navlink: loading state on navigation -->
<a href="/page" use:navlink>Go to page</a>

Svelte Transitions

Physics-aware motion primitives for Svelte’s in:, out:, and animate: directives. Each transition reads the active physics preset (glass/flat/retro) and adapts timing, easing, and filters automatically.

<script>
  import { emerge, dissolve, materialize, dematerialize, implode, live } from '@lib/transitions.svelte';
</script>

<!-- Layout-aware entry/exit (normal flow) -->
{#if visible}
  <div in:emerge out:dissolve>
    Content grows in, collapses out.
  </div>
{/if}

<!-- Visual-only entry/exit (positioned/overlay) -->
{#if visible}
  <div class="absolute" in:materialize out:dematerialize>
    Fades in with blur + scale, floats up on exit.
  </div>
{/if}

<!-- Implode + live: collapse removed item, reflow siblings -->
{#each items as item (item)}
  <button animate:live out:implode onclick={() => remove(item)}>
    {item}
  </button>
{/each}

Interactive Demo

Move your cursor anywhere on the page while the portal is visible to destabilize it. Each ring layer tracks at a different depth, creating a parallax tunnel effect. The closer your cursor to the center, the stronger the wobble.

The portal fills its container width (width: 100%, height: auto). Constrain with a max-width on the parent. Color inherits from --energy-primary.

Intensity Control

The intensity prop multiplies all parallax translations. At 0 the portal is static. At 1 (default) it responds naturally. Values above 1 exaggerate the effect for dramatic presentations.

Use intensity={0} to disable pointer interaction entirely (e.g., as a static background). Values between 0.3–0.7 work well for subtle ambient use.

Physics Adaptation

The portal adapts its rendering to the active physics preset. Switch physics in Settings to see live changes.

Light mode reduces ring opacities for readability on bright backgrounds. All physics and mode combinations are supported automatically.

Stat Cards

KPI metric cards with formatted values, trend indicators, and optional embedded sparklines. Use StatCard for dashboard headers and summary metrics.

<StatCard
  label="Revenue"
  value="$78.4k"
  trend="up"
  delta="+12.5%"
  sparkline={[38, 42, 35, 48, 52, 45, 61, 58, 67, 72, 68, 78]}
/>

<!-- trend: 'up' | 'down' | 'flat' -->
<!-- sparkline auto-colors: up=success, down=error, flat=primary -->

Props: label, value (formatted string), trend ('up'|'down'|'flat'), delta (trend text), sparkline (number[]), id.

Bar Chart

Category comparison chart with vertical and horizontal orientations, grouped bar clusters, reference lines, and axis labels. Single-metric charts use uniform color; grouped charts assign distinct series per metric. Toggle options below to explore features.

<!-- Basic -->
<BarChart
  data={[
    { label: 'Jan', value: 12400 },
    { label: 'Feb', value: 15800 },
    ...
  ]}
  showValues
  showGrid
  yLabel="Revenue ($)"
/>

<!-- Grouped -->
<BarChart
  groups={[
    { label: 'Engineering', values: [
      { name: 'Budget', value: 120000 },
      { name: 'Actual', value: 115000, series: 1 },
    ] },
    ...
  ]}
  showLegend
  referenceLines={[{ value: 80000, label: 'Target' }]}
/>

<!-- Horizontal -->
<BarChart
  data={[...]}
  orientation="horizontal"
  xLabel="Users"
/>

Props: data, groups, orientation ('vertical'|'horizontal'), height, showValues, showGrid, showLegend, referenceLines, xLabel, yLabel, formatValue, onselect, animated, title, id.

Line Chart

Trend visualization with optional area fill, data point dots, and multi-series support. Toggle between single and multi-series views.

<!-- Single series -->
<LineChart
  data={[
    { label: 'Jan', value: 1200 },
    { label: 'Feb', value: 1850 },
  ]}
  filled showDots showGrid
/>

<!-- Multi-series -->
<LineChart
  series={[
    { name: 'Sessions', data: [...], series: 0 },
    { name: 'Conversions', data: [...], series: 2 },
  ]}
  showLegend filled
/>

Props: data ({label, value}[]), series ({name, data, series?}[]), height, filled, showDots, showGrid, smooth, showLegend, referenceLines, xLabel, yLabel, formatValue, onselect, animated, title, id.

Funnel Chart

Conversion funnel for multi-stage flows and drop-off analysis. Each stage is a trapezoid whose width (vertical) or height (horizontal) is proportional to stage.value / firstStage.value, with conversion rates computed inline between consecutive stages. The default fill paints every stage with --energy-primary at a descending alpha (sequential drop-off); a per-stage series index opts into the categorical data palette for stages that represent distinct buckets rather than a sequence.

<!-- Canonical conversion funnel (sequential drop-off) -->
<FunnelChart stages={[
  { label: 'Visitors',  value: 10000 },
  { label: 'Signups',   value: 2400 },
  { label: 'Trials',    value: 800 },
  { label: 'Customers', value: 120 },
]} />

<!-- Categorical mode — per-stage `series` paints from the data palette -->
<FunnelChart stages={[
  { label: 'Email',    value: 4200, series: 0 },
  { label: 'Search',   value: 2800, series: 1 },
  { label: 'Direct',   value: 1900, series: 2 },
  { label: 'Referral', value:  800, series: 3 },
]} />

<!-- Horizontal orientation -->
<FunnelChart stages={[...]} orientation="horizontal" />

Props: stages ({label, value, rate?, series?}[]), orientation ('vertical'|'horizontal'), showRates, showValues, formatValue, animate, title, id.

Donut Chart

Ring chart for proportional data with center metric and legend. Segments use stroke-dasharray on SVG circles — no complex path math needed.

<DonutChart
  data={[
    { label: 'Organic', value: 42 },
    { label: 'Direct', value: 28 },
    { label: 'Referral', value: 18 },
    { label: 'Social', value: 12 },
  ]}
  centerMetric={{ label: 'Sources', value: '100%' }}
/>

<!-- Explicit series colors -->
<DonutChart data={[
  { label: 'Done', value: 64, series: 2 },
  { label: 'Failed', value: 8, series: 4 },
]} />

Props: data ({label, value, series?}[]), size (default 200), maxSize, thickness (0–1, default 0.3), centerMetric ({label, value}), showLegend, formatValue, onselect, animated, title, id.

Sparklines

Compact inline trend lines for embedding in tables, lists, and cards. No axes or labels — just the shape of the data. All 8 categorical data-palette slots shown below — each derived from --energy-primary via OKLCH hue rotation.

<Sparkline data={[45, 52, 48, 61, 55, 67, 72]} />
<Sparkline data={trend} filled series={2} width={160} height={40} />

<!-- Series: 0–7 maps to --color-data-1 through --color-data-8 -->

Props: data (number[]), width (default 120), height (default 32), series (0–7), filled, fluid, animated, label (aria), id.

Progress Ring

Circular progress indicator with optional center value label. Uses stroke-dasharray for the arc fill. Supports all 8 data-palette colors (series 0–7), configurable size and thickness, and entry animation.

<ProgressRing value={75} />
<ProgressRing value={75} showValue series={2} scale="lg" />
<ProgressRing value={3} max={10} showValue
  formatValue={(v, m) => `${v}/${m}`}
/>

<!-- Scale: sm | md | lg | xl (default md) -->
<!-- Series: 0–7 maps to --color-data-1 through --color-data-8 -->

Props: value, max (default 100), scale (sm|md|lg|xl, default md), thickness (0–1, default 0.25), series (0–7), showValue, formatValue, animated, label (aria), id.