@stnd/ui

Shared UI components for the Standard Ecosystem.

Most buttons/badges/cards should just be a CSS class on plain HTML (see @stnd/styles) — no JS, no import. This package is only for the handful of things that genuinely need interactivity: a dropdown that manages keyboard navigation, a confirm dialog you can await, a right-click menu. If you’re reaching for a component here and it’s not doing something stateful or ARIA-heavy, check whether a CSS class already does the job.

Use it (the confirm dialog, the most common one):

import { confirm } from "@stnd/ui/dialog.js";
const ok = await confirm({ title: "Delete this?", intent: "danger" });

Overview

@stnd/ui provides a collection of reusable, accessible, and high-quality UI components built for Astro and Svelte 5. These components are designed to work seamlessly with @stnd/styles and follow the Standard design principles.

🏛 The Philosophy: CSS First, Components Second

Standard is built on the philosophy of keeping the codebase as clean, fast, and static as possible. Before importing a component from @stnd/ui, ask yourself: Can this be done with just HTML and @stnd/styles?

Many UI elements you see in the Playground (like Buttons, Badges, Cards, and Inputs) are not components. They are simple CSS classes applied to standard HTML elements.

Why?

• Zero JavaScript overhead.
• Perfect semantic HTML.
• Maximum flexibility without passing dozens of props.

Example: Buttons & Badges (CSS Only)

You do not need a <Button> or <Badge> component. Just use the global classes provided by @stnd/styles:

<!-- Primary Button -->
<button class="btn">Save Changes</button>

<!-- Ghost Button -->
<button class="btn ghost">Cancel</button>

<!-- Success Badge -->
<span class="badge success">Active</span>

When to use @stnd/ui Components?

You should only import components from this package when you need:

1. Complex interactivity (e.g., Dropdown, ContextMenu).
2. State management (e.g., DialogManager, ComboBox).
3. Advanced Accessibility / ARIA management (e.g., Accordion).
4. Complex composition (e.g., Accordion, Scroller, TableOfContents).

Icons and Lottie animations are not in this package — they live in
@stnd/icon (import Icon from "@stnd/icon/Icon.astro"). See its README.

🧩 Component API Reference

Accordion

Is it accessible?

Yes. It adheres to the WAI-ARIA design pattern.

Is it styled?

Yes. It comes with default styles that matches the other components' aesthetic.

Is it animated?

Yes. It's animated by default, but you can disable it if you prefer.

Avatar

Badge

PrimarySecondaryOutlineDestructive

BadgeAlert

89920+

LinkLinkLinkLink

Breadcrumb

1. Home
5. Components
7. Breadcrumb

Card

Login to your account

Enter your details below to login to your account

Email

PasswordForgot your password?

Meeting Notes

Transcript from the meeting with the client.

Client requested dashboard redesign with focus on mobile responsiveness.

1. New analytics widgets for daily/weekly metrics
2. Simplified navigation menu
3. Dark mode support
4. Timeline: 6 weeks
5. Follow-up meeting scheduled for next Tuesday

Is this an image?

This is a card with an image.

Content Only

Content

Header and Content

This is a card with a header and a content.

Content only.

Header + Content + Footer

This is a card with a header, content and footer.

Content

Skeleton

Table

A list of your recent invoices.

Invoice	Status	Method	Amount
INV001	Paid	Credit Card	$250.00
INV002	Pending	PayPal	$150.00
INV003	Unpaid	Bank Transfer	$350.00
INV004	Paid	Paypal	$450.00
INV005	Paid	Credit Card	$550.00
INV006	Pending	Bank Transfer	$200.00
INV007	Unpaid	Credit Card	$300.00
Total			$2,500.00

Tooltip

TopRightBottomLeft

Toast

Lightweight notification system. Dispatches a custom toast event — no framework needed. The Toast component listens globally and renders items in a fixed container at the top of the viewport.

SuccessErrorWarningInfoDefault (long)

Scroller

A fixed scroll-progress bar at the very top of the page. It's already active on this page — scroll down and watch the thin line fill. No configuration needed; it's mounted automatically by the Base layout.

The bar at the top of this page is the Scroller. It uses window.scrollY and the document height to compute a 0–100% fill width, rendered as a glassmorphic strip with a glow shadow.

Example: 60% through page

Astro Components (Zero JS)

<Accordion />

Accessible, collapsible content sections.

• open (boolean): Sets the initial open state.

Svelte 5 Components (Hydrated)

<Alert />

Semantic feedback banners.

• class (string): The semantic intent: success, warning, error, info. (Defaults to accent color).
• title (string): Optional bold title.
• icon (string): Optional string icon (e.g., ✓, ⚠).

<Alert class="warning" title="Watch out!" icon="⚠">
  This action cannot be undone.
</Alert>

<Dropdown />

Accessible, keyboard-navigable dropdown menus.

• align (string): Alignment of the menu (start, end). Defaults to start.
• label (string): Recommended accessible name for the native trigger button. When supplied, the trigger snippet contains only its content (not another button). triggerClass styles that button; open is bindable. Existing trigger snippets without label remain supported.
• Slots: trigger (the button that opens the menu), default (the menu items).
• Arrow keys and Home/End move among enabled items; Escape dismisses and restores trigger focus. Item activation closes the menu; Tab dismisses and continues focus navigation. Native button keyboard activation does not toggle twice.

Related Sub-components:

• <DropdownItem icon="ph:user" shortcut="⌘P">Profile</DropdownItem>
• <DropdownLabel label="My Account" />
• <DropdownSeparator />

<ContextMenu />

Viewport-aware right-click menus.

• Slots: default (the area that triggers the menu on right-click), content (the menu items).
• For delegated/virtualized targets, omit the default snippet and pass open, position={{ x, y }} (viewport coordinates), label, and onclose. open is bindable. The shared menu measures its actual content, clamps to the viewport, and scrolls oversized menus.
• Arrow keys and Home/End move among enabled items. Escape, Tab, outside clicks, viewport resize, and scrolling outside the menu dismiss it. Focus returns to the previous element when appropriate. Context-menu item components use native disabled state as well as ARIA.

<Dialog />

A general-purpose native modal shell for forms and other arbitrary content. This complements AlertDialog/confirm(); it does not add confirmation semantics.

<Dialog bind:open label="Preferences" onclose={discardDraft}
  style="--dialog-width: 580px; --dialog-max-height: 88vh">
  <!-- Form content and semantic buttons belong to the consumer. -->
</Dialog>

label is the accessible name; children supplies content; class and style customize the shell. onkeydown can implement a content-specific shortcut. The component owns showModal(), background inertness, native focus behavior, Escape/backdrop dismissal, and focus restoration. It stops keyboard propagation to application shortcut handlers. Use it for modal interactions, not for live nonmodal monitors or native OS windows.

<Popover />

An anchored, nonmodal popup for forms and mixed controls. Use Dropdown for menus of actions instead.

<Popover label="Display options" align="end">
  {#snippet trigger(attributes)}
    <button class="btn ghost" {...attributes}>Display</button>
  {/snippet}
  <!-- Native inputs and content-specific buttons. -->
</Popover>

Spread the trigger attributes onto a single native button; they supply its click behavior and ARIA relationship. Props: bindable open, required label, trigger and children snippets, align (start/end), side (bottom/top), optional wrapper class, and onclose. Escape restores trigger focus; outside click or focus leaving the popup/trigger dismisses it. Keyboard events inside the content do not reach application-wide shortcuts.

The shared menu geometry/navigation helpers have dependency-free tests: node --test packages/ui/menu.test.js from the repository root. Reveal’s browser UI regression suite also exercises controlled and wrapped context menus, dropdowns, popovers, and native dialogs with synthetic data; see Reveal UI validation.

🚨 Dialog Manager

The DialogManager allows you to trigger accessible confirmation dialogs programmatically from any script using a simple Promise-based API. This prevents littering your DOM with hidden modal HTML.

AlertDialog can also be composed directly inside an existing Dialog when confirmation belongs to that form. Its title provides the accessible dialog name, keyboard events stay within the confirmation instead of reaching parent form shortcuts, and a programmatic close after confirmation does not also call the cancellation callback.

1. Mount the Manager

Ensure <DialogManagerComponent client:load /> is mounted once in your root layout (Standard does this by default).

2. Call the API

import { confirm } from "@stnd/ui/dialog.js";

const isConfirmed = await confirm({
  title: "Delete this item?",
  description: "This action cannot be undone. Are you sure?",
  confirmLabel: "Yes, Delete",
  cancelLabel: "Cancel",
  intent: "danger" // "neutral" | "danger"
});

if (isConfirmed) {
  // Proceed with deletion
}

Notes / Observations

(jot down anything noticed here — quirks, gotchas, ideas)

Todo

• README is thin relative to the component count — Combobox, priority: 3 token_scale: 3 created: 2026-07-14 area: framework
  Panel, Pagination, Scroller, TableOfContents, Toast, CfImage, LauncherHint exist on disk but aren’t documented above. Worth a pass once this package settles.