# Timeless UI — full documentation

Every guide and every component contract. See https://timeless.build/llms.txt for the curated index, and
https://timeless.build/docs/getting-started/agents/ for how these files are meant to be used.

---

> Framework-agnostic UI components built on modern web standards. Most components are plain CSS over
> native HTML and need no JavaScript; the rest are Light-DOM custom elements, used only where
> keyboard coordination, focus management, or state synchronisation cannot be expressed accessibly
> in CSS. Targets Baseline 2025 browsers. Usable from plain HTML, React, Preact, Vue, Svelte, Solid,
> or Astro.

## How to author Timeless markup

Read this before writing any Timeless markup. The API is not prop-based, and guessing from React or
Tailwind conventions produces markup that does not work.

### The two kinds of component

Everything in the library is one of two things, and they are configured differently. Getting this
wrong is the single most common failure.

**CSS components** are a native element carrying a `ui-*` class. Configure them with `data-ui-*`
attributes. There is nothing to register and nothing to import beyond the stylesheet.

```html
<button class="ui-button" type="button" data-ui-variant="primary">Publish</button>
```

**Custom elements** are a registered `ui-*` tag wrapping your own markup. Configure them with plain
attributes, never `data-ui-*`. Register each element you use.

```html
<ui-tabs orientation="vertical" activation="manual">
  <!-- your own tablist and panels -->
</ui-tabs>
```

So:

- `<ui-button variant="primary">` is wrong twice — there is no `ui-button` element, and `variant` is
  not how a CSS component is configured. It is
  `<button class="ui-button" data-ui-variant="primary">`.
- `<ui-tabs data-ui-orientation="vertical">` is wrong — host configuration on a custom element uses
  plain attributes. It is `<ui-tabs orientation="vertical">`.

### Rules that apply to both kinds

- **Boolean attributes are presence-based. Author the attribute with no value, or omit it.**
  `invalid`, `wrap`, and `attached` are booleans. `invalid="true"` and `data-ui-invalid="true"` are
  not valid and will not match the stylesheet.
- **Component anatomy is authored by you and marked with a whitespace-separated `data-ui-part` token
  list, selected with `[data-ui-part~='name']`.** Parts documented as required must be present for
  the component to work — a tab set with no `[role='tablist']` has nothing to coordinate.
- **A few parts accept per-item input of their own, spelled `data-ui-*` on the part. Each component
  page lists them.** An option carries `data-ui-value` when its text is not the value it submits,
  and `data-ui-label` when its visible content is not what a reader would type to find it. A bare
  `value` works only on an element where HTML already defines it, which a `<div role="option">` is
  not.
- **Never author `data-ui-internal-*`. Those are private runtime hooks.** They are written by the
  component, they are not styleable, and they change without notice.
- **Native HTML semantics, ARIA, and platform pseudo-classes are authoritative for state. Do not add
  your own state classes, and do not use ARIA to replace behavior a real element provides.** Style
  `:disabled`, `[aria-expanded='true']`, `:state(--open)` and the like. Use a real `<button>`, a
  real `<dialog>`, a real `popover`.
- **Accessible names are always yours to supply.** Timeless wires relationships — `aria-controls`,
  `aria-expanded`, `id`, `hidden` — and never writes content. A `role="dialog"` surface still needs
  your `aria-labelledby`.
- **The markup you author is the markup that ships. Components are usable before JavaScript runs.**
  Never gate authored markup behind a loaded state, and never expect a component to generate visual
  anatomy for you.
- **Import stylesheets from `@timelessui/components/css/<file>` and register custom elements from
  `@timelessui/components/register/<tag>`, which registers as it is imported. `tokens.css` and
  `core/<component>.css` are required — core is behavior, not appearance — while
  `themes/atmosphere/<component>.css` is the optional look. Registration is per-element and
  explicit.** A CSS component has nothing to register. `register/<tag>` is a side-effect import and
  needs no call; `define/<tag>` is the same registration as a function you call yourself,
  `define<Name>Element()`, for when you need to control the timing or target another window.
  Importing `define/<tag>` and calling nothing registers nothing, which is the usual reason a custom
  element never upgrades.

### Finding the exact contract

Before guessing an attribute or a value, fetch the component contract rather than inferring it.
Every component's full contract — permitted attributes and values, authored parts, public state,
custom properties, the element API, keyboard behavior, and canonical markup — is at
`https://timeless.build/docs/components/<component>.md`. The index of every page is at
`https://timeless.build/llms.txt`.

---

# Timeless documentation

Source: https://timeless.build/docs.md

Framework-agnostic UI built on modern web standards.

import { CardGrid, LinkCard } from '@astrojs/starlight/components'
import { examples } from '@timelessui/examples'
import StoriesLink from '../../../components/docs/StoriesLink.astro'

export const componentCount = examples.filter((example) => example.domain !== 'recipes').length

Timeless is a UI library designed to outlast your framework. It is built from the browser's own
primitives — plain CSS over native HTML, with custom elements only where keyboard coordination,
focus, or state cannot be expressed accessibly in CSS. There is no framework runtime and no
third-party dependency, so the same components run in plain HTML, React, Preact, Vue, Svelte, Solid,
and Astro, and keep running when you move between them.

The markup you author is the markup that ships. It renders on the server as plain HTML and CSS and
is useful before any JavaScript loads, so there is no unstyled flash and no shell that rearranges
itself once a runtime boots — the few components the platform cannot express declaratively say so on
their own page. Your CSS overrides anything, because cascade layers put it above ours. And the whole
contract is published for coding agents to read: every documentation page at its own URL plus `.md`,
an `llms.txt` index, and a skill that ships in the package.

<CardGrid>
  <LinkCard
    title="Install and build something"
    description="Add the package, load the CSS, register an element."
    href="/docs/getting-started/installation/"
  />
  <LinkCard
    title="Use it with a coding agent"
    description="How to point a model at the contract, and what it reads when you do."
    href="/docs/getting-started/agents/"
  />
  <LinkCard
    title="Browse all components"
    description={`${componentCount} components, grouped by what they are for.`}
    href="/docs/components/"
  />
  <LinkCard
    title="Theme it"
    description="Cascade layers, design tokens, and component variables."
    href="/docs/styling/theming/"
  />
  <LinkCard
    title="Use it with your framework"
    description="Vanilla, React, Preact, Astro, Svelte, Vue, and Solid."
    href="/docs/frameworks/vanilla/"
  />
</CardGrid>

## How to read a component page

Every component page follows the same shape, so you can skip to what you need:

- **Anatomy** names each part you author, whether it is required, and the selector your CSS can
  target.
- **Attributes** lists every permitted value and the default. The build proves these against the
  stylesheets, so a documented value is a value that works.
- **Element API** appears for custom elements only, and covers the DOM properties and events added
  once the element upgrades.
- **Styling** separates the custom properties you may set from the global tokens the component
  reads.
- **Before JavaScript runs** says what the markup does on its own.

## What the contracts guarantee

Every published import except the stylesheets and the `register/*` entrypoints is side-effect free,
so class imports are safe during server rendering. Enhanced elements coordinate the markup you wrote
rather than replacing it, and they preserve native controls wherever those controls already provide
submission, labelling, reset, and validation.

<StoriesLink>Every component also has a StoryLite page</StoriesLink> with variants, live controls,
and manual testing.

---

# Core concepts

Source: https://timeless.build/docs/concepts.md

How an authored default differs from live state, and what happens to properties assigned before an element upgrades.

Two contracts are easy to get wrong because neither has a visible symptom until it matters: which
value survives a form reset, and what happens to a property you assign before the element definition
loads. Everything else about a component is on its own page — this covers the two rules that span
all of them.

## Authored defaults and live state

The `value` **attribute** you author is the default. The `value` **property** is live state. They
are separate storage, exactly as they are on a native `<input>`:

```html
<ui-select value="draft" name="status">…</ui-select>
```

```ts
const select = document.querySelector('ui-select')

select.value // 'draft'  — live state, currently equal to the default
select.value = 'published' // live state moves
select.defaultValue // 'draft'  — the authored attribute is untouched
select.getAttribute('value') // 'draft'
```

Two consequences follow.

**A form reset returns to the authored attribute, not to whatever was assigned last.**
Form-associated elements — Select, Combobox, Listbox, and OTP Field — implement `formResetCallback`
by restoring `defaultValue`, so `<button type="reset">` puts `status` back to `draft`.

**Assigning the property dispatches nothing.** `ui-before-change` and `ui-change` describe _user_
transitions and carry the originating event in `detail.originalEvent`. A programmatic assignment has
no originating event, so it updates the DOM silently. Code that assigns a value already knows it
did; if you need your own listeners to run, dispatch your own event.

To move the default itself — so a later reset returns somewhere new — set the attribute:

```ts
select.setAttribute('value', 'published')
```

The helpers the elements use to keep the two apart are exported from
[`@timelessui/components/value-state`](/docs/reference/packages/#entrypoints), if you are building
something on the same contract.

## Properties assigned before upgrade

A framework often has a reference to an element before `customElements.define` has run for it. An
assignment at that moment lands as an own property on the instance, shadowing the accessor the
definition will later install on the prototype. In most custom-element libraries the value is then
lost.

Timeless replays it. On connection, each declared attribute and property that exists as an own
property is deleted and re-assigned, which runs the real setter — and this happens _before_ the
component's own connection logic, so the element never observes a stale value:

```ts
const select = document.createElement('ui-select')
select.value = 'published' // no definition yet — a plain own property

await import('@timelessui/components/register/ui-select')
document.body.append(select) // upgrade, then replay, then connect

select.value // 'published'
```

This is why registration is safe to load late, and why a server-rendered page can hydrate and assign
state without ordering the registration import first. See
[Packages and entrypoints](/docs/reference/packages/#server-rendering) for the import-safety rules
and your framework's guide under [Frameworks](/docs/frameworks/vanilla/) for where the assignment
usually lives.

## Where the rest lives

- **Anatomy, attributes, parts, states, events** — each component's own page, generated from the
  contract the stylesheets are proven against.
- **The two kinds of component, and how each is configured** —
  [AI agents](/docs/getting-started/agents/).
- **Layers, tokens, and overriding styles** — [Theming](/docs/styling/theming/).
- **Import safety and server rendering** — [Packages and entrypoints](/docs/reference/packages/).
- **What the platform handles and what degrades** —
  [Browser support](/docs/reference/browser-support/).

---

# Astro

Source: https://timeless.build/docs/frameworks/astro.md

Render Timeless anatomy on the server and register behavior in the browser.

## Install

```sh
pnpm add @timelessui/components
```

## CSS and registration

Import component CSS in an Astro layout or page frontmatter:

```astro
---
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
---
```

Render the public anatomy as ordinary Astro markup, then load the definition as a processed client
script:

```astro
<ui-popover>
  <button data-ui-part="trigger" type="button" popovertarget="details">Open</button>
  <div id="details" popover="auto">Popover content</div>
</ui-popover>

<script>
  import '@timelessui/components/register/ui-popover'
</script>
```

## SSR and hydration

Astro renders the complete Light DOM on the server. A custom element does not need an Astro client
directive. The processed script registers it in the browser, then native custom-element upgrade
enhances the existing DOM. Class-only imports are SSR safe.

## Attributes, properties, events, and TypeScript

Use plain attributes for authored state. Assign live properties from a client script after selecting
the element. Listen for namespaced events with `addEventListener`, and import element or event
detail types from the matching package entrypoint when the script uses TypeScript.

Astro templates are HTML, not JSX, so no JSX declaration applies to them. Completion and hover
documentation for `ui-*` tags, their attributes, and their permitted values come from the shipped
editor data instead — see [Editor setup](/docs/getting-started/editor-setup/). If a page uses a
React, Preact, or Solid island, import that framework's declarations for the island's `.tsx` files.

CSS-only components are a root class plus `data-ui-*` on a native tag. Astro spreads attributes, so
the typed helper works directly in a template:

```astro
---
import { uiAttributes } from '@timelessui/components/attributes'
---

<button {...uiAttributes('button', { variant: 'primary' })} type="button">Publish</button>
```

---

# Preact

Source: https://timeless.build/docs/frameworks/preact.md

Use custom elements directly with opt-in JSX types and no runtime wrapper.

## Install and TypeScript

```sh
pnpm add @timelessui/components
```

Preact passes unknown props straight through to the DOM and registers any `on*` prop as an event
listener, so Timeless elements work without a wrapper on any recent version. Import the JSX
declarations once in your application types:

```ts
import '@timelessui/components/preact'
```

The declaration is types-only. It adds no runtime code, no Preact dependency, and no peer
dependency. With it imported, `ui-*` tags are known intrinsic elements and their attributes complete
and type-check:

```tsx
<ui-tabs orientation="vertical" activation="manual" />
```

`orientation` accepts only `horizontal` or `vertical`, and `activation` only `automatic` or
`manual`, because both are generated from the same declaration the stylesheets are proven against.

If you use `preact/compat` to run React libraries alongside Preact, import the React declarations
instead — `@timelessui/components/react` — because `preact/compat` aliases the `react` module that
those declarations augment.

## CSS and registration

Import CSS and registration from a client entrypoint:

```ts
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/tabs.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/tabs.css'
import '@timelessui/components/register/ui-tabs'
```

CSS, class, and `define/*` imports are safe during server rendering. Keep `register/*` imports in
code the browser loads, because that is where they call `customElements.define` — on the server they
are inert, so a server-only import registers nothing.

## Markup and hydration

Use the element directly. The markup you author is the markup that ships:

```tsx
export function ProjectTabs() {
  return (
    <ui-tabs value="details">
      <div role="tablist" aria-label="Project">
        <button type="button" role="tab" value="details">
          Details
        </button>
        <button type="button" role="tab" value="activity">
          Activity
        </button>
      </div>
      <section role="tabpanel">Project details</section>
      <section role="tabpanel">Recent activity</section>
    </ui-tabs>
  )
}
```

Preact hydrates the authored Light DOM, then the browser upgrades the custom element without
replacing that anatomy. Attributes carry the authored default; assign DOM properties for live state
after the element upgrades.

## Events

Preact turns an `on*` prop into an `addEventListener` call, so namespaced Timeless events bind
directly and arrive typed with the detail the element actually dispatches:

```tsx
<ui-tabs
  value="details"
  onui-change={(event) => {
    // event.detail is TabsChangeDetail
    console.log(event.detail.value, event.detail.reason)
  }}
/>
```

`onui-before-change` is cancelable: call `event.preventDefault()` to reject the transition and keep
the current value. Detail types are also importable from `@timelessui/components/events` and from
each element's own entrypoint.

## CSS-only components

Most Timeless components are plain CSS over native HTML and have no custom element at all. Those are
a root class plus `data-ui-*` attributes, which JSX cannot check per element without loosening every
element in your app. Use the typed helper instead:

```tsx
import { uiAttributes } from '@timelessui/components/attributes'

export function PublishButton() {
  return (
    <button {...uiAttributes('button', { variant: 'primary', size: 'lg' })} type="button">
      Publish
    </button>
  )
}
```

See [Editor setup](/docs/getting-started/editor-setup/) for why that gap exists and what completes
in each editor.

---

# React

Source: https://timeless.build/docs/frameworks/react.md

Use custom elements directly with opt-in JSX types and no runtime wrapper.

## Install and TypeScript

```sh
pnpm add @timelessui/components
```

React 19 supports custom-element properties on the client and primitive attributes during server
rendering. Import Timeless JSX declarations once in your application types:

```ts
import '@timelessui/components/react'
```

The declaration is types-only. Timeless does not add a runtime wrapper or React dependency.

## CSS and registration

Import CSS and registration from a client entrypoint:

```ts
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/listbox.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/listbox.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-listbox'
```

Load definition imports from a client entrypoint. CSS and class-only imports are safe during server
rendering.

## Markup and hydration

Use the element directly:

```tsx
export function StatusPicker() {
  return (
    <ui-listbox value="draft" role="listbox" aria-label="Status">
      <div role="option" data-ui-value="draft">
        Draft
      </div>
      <div role="option" data-ui-value="ready">
        Ready
      </div>
    </ui-listbox>
  )
}
```

Primitive values render as attributes on the server. Assign object or array properties after the
element upgrades when a component exposes them. React hydrates the authored Light DOM, then the
browser upgrades the custom element without replacing that anatomy.

## Events

Attach namespaced custom events with a ref and `addEventListener` when an application needs typed,
cancelable transition handling. `onui-change` and `onui-before-change` props are also declared and
carry the detail type the element actually dispatches, so a `ui-tabs` handler receives a
`CustomEvent<TabsChangeDetail>` rather than a generic one. Detail types import from
`@timelessui/components/events` and from each element's own entrypoint.

`on*` props on custom elements and non-string attribute values both require React 19. On React 18
the declarations still type your markup, but pass primitives as attributes and bind events with a
ref.

## CSS-only components

Most Timeless components are plain CSS over native HTML and have no custom element at all. Those are
a root class plus `data-ui-*` on a native tag, and JSX cannot check that per element without
loosening every element in your app. Use the typed helper:

```tsx
import { uiAttributes } from '@timelessui/components/attributes'

export function PublishButton() {
  return (
    <button {...uiAttributes('button', { variant: 'primary', size: 'lg' })} type="button">
      Publish
    </button>
  )
}
```

`variant` accepts only the seven button variants, and Card's `filled` is a type error on a Button.
See [Editor setup](/docs/getting-started/editor-setup/) for what each editor completes.

---

# Solid

Source: https://timeless.build/docs/frameworks/solid.md

Render Timeless custom elements directly from Solid.

## Install and TypeScript

```sh
pnpm add @timelessui/components
```

Import the Solid declarations once in your application types:

```ts
import '@timelessui/components/solid'
```

They extend Solid's `JSX.IntrinsicElements`, so every `ui-*` tag and every permitted attribute value
type-checks. Both event spellings are declared: `on:ui-change`, the namespaced form Solid recommends
for custom events, and `onui-change`. The declaration is types-only and adds no runtime code and no
Solid dependency.

## CSS and registration

Import CSS and the required definitions once:

```ts
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/choice-groups.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/choice-groups.css'
import '@timelessui/components/register/ui-radio-group'
```

## Markup

Solid forwards custom-element attributes and properties without a Timeless adapter:

```tsx
<ui-radio-group value="system" aria-label="Theme">
  <label>
    <input type="radio" name="theme" value="system" /> System
  </label>
  <label>
    <input type="radio" name="theme" value="dark" /> Dark
  </label>
</ui-radio-group>
```

## SSR, hydration, events, and TypeScript

SSR emits the authored attributes and Light DOM. Keep registration in client code so custom-element
upgrade happens after hydration. Bind namespaced events in JSX, and use a ref when you need to
assign live properties:

```tsx
<ui-radio-group
  value="system"
  aria-label="Theme"
  on:ui-change={(event) => setTheme(event.detail.value)}
>
  {/* radios */}
</ui-radio-group>
```

The handler receives a `CustomEvent<RadioGroupChangeDetail>`. Public classes and detail types are
available from the granular entrypoints.

CSS-only components are a root class plus `data-ui-*` on a native tag. Spread the typed helper
rather than writing those attributes by hand:

```tsx
import { uiAttributes } from '@timelessui/components/attributes'

export function PublishButton() {
  return (
    <button {...uiAttributes('button', { variant: 'primary' })} type="button">
      Publish
    </button>
  )
}
```

---

# Svelte

Source: https://timeless.build/docs/frameworks/svelte.md

Use Timeless elements as native custom elements in Svelte.

## Install and TypeScript

```sh
pnpm add @timelessui/components
```

Import the Svelte declarations once in your application types:

```ts
import '@timelessui/components/svelte'
```

They extend `svelteHTML.IntrinsicElements`, so `svelte-check` knows every `ui-*` tag and the values
each attribute accepts. Both event spellings are declared — Svelte 5 `onui-change` and Svelte 4
`on:ui-change` — so the same declaration checks either version. It is types-only and adds no runtime
code and no Svelte dependency.

## CSS and registration

Import CSS and definitions from a client module or layout:

```ts
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/tabs.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/tabs.css'
import '@timelessui/components/register/ui-tabs'
```

## Markup

Author the element normally:

```svelte
<ui-tabs value="details">
  <div role="tablist" aria-label="Project">
    <button role="tab" value="details">Details</button>
    <button role="tab" value="activity">Activity</button>
  </div>
  <section role="tabpanel">Project details</section>
  <section role="tabpanel">Recent activity</section>
</ui-tabs>
```

## SSR, hydration, properties, and events

SSR emits the complete Light DOM anatomy before the definition loads. Plain attributes express
authored defaults. Bind namespaced events directly, and use `bind:this` when you need to assign live
properties:

```svelte
<ui-tabs value="details" onui-change={(event) => console.log(event.detail.value)}>
  <!-- tablist and panels -->
</ui-tabs>
```

The handler receives a `CustomEvent<TabsChangeDetail>`, because each element declares the detail
type it dispatches rather than sharing one generic signature. Element classes and detail types
import into TypeScript without registering anything on the server.

CSS-only components are a root class plus `data-ui-*` on a native tag, which Svelte cannot check per
element. Spread the typed helper instead:

```svelte
<script lang="ts">
  import { uiAttributes } from '@timelessui/components/attributes'
</script>

<button {...uiAttributes('button', { variant: 'primary' })} type="button">Publish</button>
```

---

# Vanilla

Source: https://timeless.build/docs/frameworks/vanilla.md

Use Timeless directly from HTML and JavaScript.

## Install

```sh
pnpm add @timelessui/components
```

## CSS and registration

Import styles and definitions from an application module:

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/toggle.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/toggle.css'
import '@timelessui/components/register/ui-toggle-group'
```

Then author normal HTML:

```html
<ui-toggle-group selection="single" aria-label="Alignment">
  <button class="ui-button ui-toggle" value="left" aria-pressed="true">Left</button>
  <button class="ui-button ui-toggle" value="center" aria-pressed="false">Center</button>
</ui-toggle-group>
```

The same markup is emitted by a server or copied into a static HTML document. The complete Light DOM
is readable before registration, then the explicit definition upgrades it in the browser.

## Attributes, properties, and events

Properties are useful for live state. Attributes provide authored defaults and reset state:

```js
const group = document.querySelector('ui-toggle-group')
group.addEventListener('ui-before-change', (event) => {
  if (!canChange(event.detail.value)) event.preventDefault()
})
group.addEventListener('ui-change', (event) => save(event.detail.value))
```

Each element declares the detail type it dispatches, so `event.detail` is typed per element rather
than shared: a `ui-toggle-group` change carries `ToggleGroupChangeDetail`. No hydration runtime is
required.

## Editors and TypeScript

There is no JSX layer here, so nothing type-checks your HTML by default. Two things close that gap:

- Register the shipped editor data once, and `ui-*` tags, their attributes, and their permitted
  values complete in any `.html` file. See [Editor setup](/docs/getting-started/editor-setup/).
- For markup assembled in TypeScript, `@timelessui/components/attributes` gives CSS-only components
  a typed surface, and `@timelessui/components/validate` reports authored values that no contract
  permits:

```ts
import { uiAttributeString } from '@timelessui/components/attributes'

const markup = `<button ${uiAttributeString('button', { variant: 'primary' })} type="button">Publish</button>`

if (import.meta.env.DEV) {
  const { validateTimelessMarkup } = await import('@timelessui/components/validate')
  validateTimelessMarkup()
}
```

The validator walks the document and warns about a `data-ui-*` attribute no contract declares or a
value outside its permitted set — the class of typo that renders without complaint.

---

# Vue

Source: https://timeless.build/docs/frameworks/vue.md

Configure Vue to treat ui elements as native custom elements.

## Install and compiler configuration

```sh
pnpm add @timelessui/components
```

Tell the Vue compiler that `ui-` tags are custom elements:

```ts
// vite.config.ts
vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('ui-') } } })
```

Then import the Vue declarations once in your application types:

```ts
import '@timelessui/components/vue'
```

They register every `ui-*` tag on `GlobalComponents`, so `vue-tsc` checks attributes and their
permitted values in templates. Vue camelizes a dashed event name, so `ui-change` binds as
`@ui-change` in a template and is typed as `onUiChange`. The declaration is types-only and adds no
runtime code and no Vue dependency.

## CSS and registration

Import granular CSS and registration from a client entrypoint:

```ts
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/listbox.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/listbox.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-listbox'
```

## Markup and state

Use attributes for authored defaults and DOM properties for live state:

```vue
<ui-listbox ref="listbox" value="draft" role="listbox" aria-label="Status">
  <div role="option" data-ui-value="draft">Draft</div>
  <div role="option" data-ui-value="ready">Ready</div>
</ui-listbox>
```

## SSR, hydration, events, and TypeScript

Vue can hydrate the server-rendered Light DOM before the element definition upgrades it. Keep
registration in browser code. Use a typed template ref to assign properties, and bind namespaced
events in the template:

```vue
<ui-listbox value="draft" role="listbox" aria-label="Status" @ui-change="onChange">
  <div role="option" data-ui-value="draft">Draft</div>
</ui-listbox>
```

Each element's events carry the detail type it actually dispatches, so `onChange` receives a
`CustomEvent<ListboxChangeDetail>`. Public element classes and detail types import without
registering anything on the server.

For CSS-only components, which are a root class plus `data-ui-*` on a native tag, bind the typed
helper instead of writing the attributes by hand:

```vue
<script setup lang="ts">
import { uiAttributes } from '@timelessui/components/attributes'
</script>

<template>
  <button v-bind="uiAttributes('button', { variant: 'primary' })" type="button">Publish</button>
</template>
```

---

# AI agents

Source: https://timeless.build/docs/getting-started/agents.md

Markdown routes, llms.txt, and a packaged skill, so a coding agent authors Timeless markup correctly instead of guessing from React conventions.

import { Aside } from '@astrojs/starlight/components'
import AgentSurfaceSizes from '../../../../components/docs/AgentSurfaceSizes.astro'
import AgentsBlock from '../../../../components/docs/AgentsBlock.astro'

Timeless is not prop-based. A model that has read a lot of React will reach for
`<ui-button variant="primary">`, and that is not a component — it is
`<button class="ui-button" data-ui-variant="primary">`. The files on this page exist to correct that
before an agent writes markup, rather than after.

Everything here is generated from the same declaration the stylesheets are validated against, so a
value an agent reads is a value the CSS implements.

## Any page as Markdown

Append `.md` to any documentation URL to get its Markdown source:

```
https://timeless.build/docs/components/tabs.md
https://timeless.build/docs/styling/theming.md
```

Every page also carries a **View as Markdown** link next to its title.

Component pages are the ones worth fetching. Each one is the component's full contract — permitted
attributes and their values, authored parts and their selectors, public state, custom properties,
the element API, keyboard behavior, and copyable canonical markup — at roughly a tenth the tokens of
the rendered page.

## llms.txt

<AgentSurfaceSizes />

Start with [`/llms.txt`](/llms.txt). It opens with the authoring grammar — the two kinds of
component and how each is configured — then indexes every guide and component with a link to its
`.md` file. It is written to be read in full alongside real work, and the build fails if it grows
past its token budget.

[`/llms-full.txt`](/llms-full.txt) is every guide and every contract concatenated. Reach for it only
when the model has the context to hold it.

## A packaged skill

`@timelessui/components` ships an [agent skill](https://code.claude.com/docs/en/skills) at
`skills/using-timeless-ui/`. It states the authoring grammar and carries a generated reference table
of every root in the library, so an agent working in your project has the contract without fetching
anything.

Because it ships inside the package, it is always the version you installed. Link it into your agent
with one of the community tools that read the convention:

```bash
npx skills-npm
```

That scans `node_modules/**/skills/*/SKILL.md` and symlinks what it finds into the skill directories
your agents read. You can also point your agent at the file directly, or copy it — it is plain
Markdown.

<Aside type="tip" title="No skill runner?">
  If you would rather not install anything, paste the block below into your project's `AGENTS.md`.
  Claude Code, Codex, Cursor, Copilot, and most other agents read that file automatically.
</Aside>

<AgentsBlock />

## Editor tooling

Agents that read your editor's language services benefit from the same data your editor does — tag,
attribute, and value completion in plain HTML and CSS, from shipped custom-data files and a Custom
Elements Manifest. See [Editor setup](/docs/getting-started/editor-setup/).

## MCP

There is no first-party MCP server yet.

The shipped `custom-elements.json` is a standard Custom Elements Manifest and is declared through
the `customElements` field in `package.json`, so community MCP and language servers built on that
format discover it without configuration. Be aware of the coverage boundary: a manifest describes
custom elements, so those tools see the registered `ui-*` elements and not the CSS-only components,
which are around half the library. For full coverage use the Markdown routes or the skill, both of
which are generated from the contracts rather than the manifest.

---

# Editor setup

Source: https://timeless.build/docs/getting-started/editor-setup.md

Register the shipped editor data so tags, attributes, values, and tokens complete in plain HTML and CSS.

Timeless ships four machine-readable descriptions of its public grammar. TypeScript covers React,
Preact, Solid, Vue, and Svelte through the [framework typings](/docs/reference/packages/). This page
covers everything TypeScript cannot reach: a `.html` file, an Astro template, the markup half of a
`.vue` or `.svelte` file, and CSS.

| File                           | Read by                                        |
| ------------------------------ | ---------------------------------------------- |
| `vscode.html-custom-data.json` | VS Code HTML, Astro, Vue, and Svelte templates |
| `vscode.css-custom-data.json`  | VS Code CSS, SCSS, and Less                    |
| `web-types.json`               | JetBrains IDEs, resolved automatically         |
| `custom-elements.json`         | Editors and generators that read the manifest  |

All four are generated from the same declaration the stylesheets are proven against, so a value that
completes is a value the CSS implements.

## VS Code

Point `html.customData` and `css.customData` at the shipped files in your workspace settings. Paths
are relative to the workspace root:

```json
// .vscode/settings.json
{
  "html.customData": ["./node_modules/@timelessui/components/vscode.html-custom-data.json"],
  "css.customData": ["./node_modules/@timelessui/components/vscode.css-custom-data.json"]
}
```

Reload the window. In any `.html` file you then get:

- Tag completion for every `ui-*` element, with its ARIA pattern and its events on hover.
- Attribute completion per tag — `ui-tabs` offers `activation`, `orientation`, and `value`.
- Value completion per attribute. Typing `<ui-tabs orientation="` offers `horizontal` and
  `vertical`, and nothing else.
- `data-ui-part` completion, with the selector each part is addressed by.

In CSS you get completion and hover documentation for every Atmosphere token and every component
custom property, including which root each property applies to.

## JetBrains IDEs

Nothing to configure. The package declares a `web-types` field, and WebStorm, IntelliJ IDEA, and
PhpStorm read it from `node_modules` automatically. Completion covers the same tags, attributes, and
values, in HTML and in JSX.

## Other editors

Any editor that reads the Custom Elements Manifest can consume `custom-elements.json`, exposed
through the package's `customElements` field.
[Packages and entrypoints](/docs/reference/packages/#custom-elements-manifest) lists what the
manifest declares.

## The one gap: CSS-only components

Most Timeless components are plain CSS over native HTML. Those have no tag of their own — they are a
root class plus `data-ui-*` attributes on a native element:

```html
<button class="ui-button" data-ui-variant="primary" data-ui-size="lg" type="button">Publish</button>
```

No editor completes that precisely, and the reason is structural rather than a missing feature.
Editor data and JSX both key completion off the tag name. The tag here is `button`, so the only hook
available is a global attribute — one that applies to every element in the document and merges the
values of every component sharing that attribute name. Declaring `data-ui-variant` globally would
offer Card's `filled` inside a Button and Button's `ghost` inside an Alert. That is worse than
offering nothing, so Timeless does not declare it.

What is offered instead:

- **Types.** `@timelessui/components/attributes` moves that surface into the type system:

  ```ts
  import { uiAttributes, uiAttributeString } from '@timelessui/components/attributes'

  uiAttributes('button', { variant: 'primary', size: 'lg' })
  // { class: 'ui-button', 'data-ui-variant': 'primary', 'data-ui-size': 'lg' }

  uiAttributeString('alert', { variant: 'danger' })
  // class="ui-alert" data-ui-variant="danger"
  ```

  The keys are the component's attributes and the values are its permitted set, so
  `uiAttributes('card', { size: 'md' })` and `uiAttributes('button', { variant: 'nope' })` are both
  type errors. `uiAttributeString` omits values that equal the contract default, because the default
  is the stylesheet's base rule and needs no attribute.

- **A runtime check.** `@timelessui/components/validate` walks real DOM and reports what neither the
  editor nor the stylesheet can:

  ```ts
  if (import.meta.env.DEV) {
    const { validateTimelessMarkup } = await import('@timelessui/components/validate')
    validateTimelessMarkup()
  }
  ```

  It warns on a `data-ui-*` attribute the component does not declare, a value outside its permitted
  set, a value on a presence-based boolean, and `data-ui-*` used as configuration on a `ui-*` host,
  where it is never correct. Both entrypoints are opt-in and neither is reachable from the default
  import.

## Keeping the data current

The editor data is regenerated and verified when the package is built, in the build, so it cannot
drift from the component registry. Reload your editor window after upgrading the package if
completions look stale.

---

# Installation

Source: https://timeless.build/docs/getting-started/installation.md

Install Timeless, load its CSS, and register the elements a route uses.

```bash
pnpm add @timelessui/components
```

That is the only package you install. There are no peer dependencies, no framework runtime, and no
configuration file.

## Load the CSS

Import the tokens plus the components a route renders:

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
```

Import `tokens.css` first — it declares the cascade-layer order that lets your own CSS override
component styles. For prototypes, `@timelessui/components/css/themes/atmosphere.css` loads
everything in one request. See [Loading CSS](/docs/styling/css/) for the trade-off and
[Theming](/docs/styling/theming/) for what you can override.

## Register the elements you use

CSS-only primitives such as Button, Alert, and Card need no JavaScript at all. Enhanced components
are custom elements, and registration is explicit — per element, never automatic:

```js
import '@timelessui/components/register/ui-popover'
```

`register/<tag>` is a side-effect import. It defines the element as the module evaluates, so it has
to run in code the browser actually loads — an import that only ever executes on the server
registers nothing, and the element never upgrades. `@timelessui/components/register` registers every
element in one import, which is convenient in a prototype and ships every component's behavior.

### Registering it yourself

The same registration is also a function, on the matching `define/` path:

```js
import { definePopoverElement } from '@timelessui/components/define/ui-popover'

definePopoverElement()
```

Reach for this when you need to control _when_ registration happens — after a feature check, inside
an `onMount`, behind a dynamic import — or to define into a window other than the current one, which
the optional `targetWindow` argument is for. `define/<tag>` has no side effect of its own: importing
it and calling nothing registers nothing.

Importing `@timelessui/components/popover` gives you the class and helpers without registering
anything either, which keeps that import safe during server rendering. Your framework's guide covers
when the upgrade happens relative to hydration — see [React](/docs/frameworks/react/),
[Vue](/docs/frameworks/vue/), [Svelte](/docs/frameworks/svelte/), or
[Solid](/docs/frameworks/solid/) — and [Packages and entrypoints](/docs/reference/packages/) lists
every import.

## Next

Build something with it in [Quick start](/docs/getting-started/quick-start/), or jump straight to a
component such as [Button](/docs/components/button/) or [Dialog](/docs/components/dialog/).

---

# The post-framework era

Source: https://timeless.build/docs/getting-started/post-framework.md

Why UI primitives outlive the frameworks they were written for, which browser features made that possible, and how Timeless differs from the other framework-agnostic libraries.

import { Aside } from '@astrojs/starlight/components'

The frontend ecosystem rearranges itself every few years. Your buttons, dialogs, and dropdowns do
not need to. The problem is that most component libraries make them, because the primitives are
coupled to a framework rather than to the platform underneath it.

This page is the reasoning behind the library. It is not required reading before
[Installation](/docs/getting-started/installation/) — but it explains why the markup on every
component page looks the way it does.

## The cost is transferability, not bundle size

A component library written for one framework is only reusable inside that framework. shadcn/ui is
React; using the same primitives in Vue or Svelte meant the community re-implementing them as
separate projects rather than importing them. That is the coupling made visible: the design work
transferred, the code could not.

So the cost of switching frameworks is not only the application. It is the layer underneath it — the
layer that had nothing framework-specific about it in the first place. A dialog needs a top layer, a
focus trap, Escape handling, and an accessible name. None of those are React opinions.

Timeless keeps that layer in the two languages every framework already renders: HTML and CSS. A
custom element is an HTML tag, so there is no adapter to write and no boundary to cross. The
[framework guides](/docs/frameworks/vanilla/) are about where the imports go, not about a different
implementation per framework.

## Why this became possible

Frameworks did not invent overlays and dark mode for fun. They shipped those features because the
platform had no version of them. Each row below was a genuine gap, and each has since closed:

| Once needed framework or library code            | Now a platform feature                    |
| ------------------------------------------------ | ----------------------------------------- |
| Positioning a surface next to its trigger        | CSS anchor positioning                    |
| Top layer, light dismiss, Escape, focus trapping | Popover API and `<dialog>`                |
| Dark mode through a theme provider and a class   | `light-dark()` and `color-scheme`         |
| Winning a specificity fight with library CSS     | Cascade layers                            |
| Component state a stylesheet can read            | `ElementInternals` states and `:state()`  |
| A click handler to open a dialog                 | Invoker Commands (`command`/`commandfor`) |
| A reusable tag that carries its own behavior     | Custom elements                           |

These were not framework ideas. They were framework workarounds, and a workaround outlives its
reason quietly. The exact versions each feature landed in, and what happens in a browser missing
one, are in [Browser support](/docs/reference/browser-support/).

## How the library uses that

There are 49 documented components, and they divide by whether the platform can express them
declaratively.

**26 are CSS over native HTML, with no JavaScript at all.** A class on real markup. There is no
runtime to boot and no hydration step, because there is nothing to hydrate — it is a stylesheet.

**23 are custom elements**, used where keyboard coordination, focus management, or ARIA
relationships genuinely cannot be expressed in CSS. Those elements enhance markup you already wrote;
they do not render it. Popover is the pattern all of them follow:

```html
<ui-popover>
  <button type="button" data-ui-part="trigger" popovertarget="menu">Menu</button>
  <div id="menu" popover="auto">The content</div>
</ui-popover>
```

That opens, closes, light-dismisses, and handles Escape with JavaScript disabled, because
`popovertarget` and `popover` are platform attributes. Registration then adds only what the platform
does not: `aria-controls`, `aria-expanded`, a default `aria-haspopup`, a surface `role`, and
anchored positioning. Nothing is created, so nothing can arrive late and rearrange the page.

The markup you author is the markup that ships. That is what removes the unstyled flash and the
shell that shifts once a bundle lands — there was never a moment when the DOM was wrong.

<Aside type="caution" title="Two components have no declarative shell">
  [Context Menu](/docs/components/context-menu/) needs pointer coordinates and [Copy
  Button](/docs/components/copy-button/) needs the clipboard. The platform offers no markup for
  either, so both require JavaScript to do anything. Each says so on its own page rather than
  leaving it to be discovered.
</Aside>

## What is different from the other framework-agnostic libraries

Framework-agnostic UI is not a new idea, and pretending otherwise would be dishonest — open-wc keeps
[a list of component libraries](https://open-wc.org/guides/community/component-libraries/) built on
the same standards. Several are excellent. Timeless makes three different trades.

**CSS-first rather than JavaScript-first.** In most web-component libraries the component renders
from JavaScript, so the element is empty until its bundle executes. Here more than half the library
has no JavaScript to execute, and the rest enhances existing markup instead of producing it.

**Light DOM rather than Shadow DOM.** Shadow DOM gives real style encapsulation, which is a
legitimate thing to want. It also means your stylesheet cannot reach inside, so styling happens
through whatever custom properties and `::part()` hooks the author remembered to expose. Timeless
keeps anatomy in the Light DOM as a `data-ui-part` token list, so your CSS — or your utility classes
— select it directly. Cascade layers put your rules above ours without a specificity fight.

**Server-rendered output that is already correct.** Declarative Shadow DOM has made SSR workable for
shadow-based libraries, so this is a narrowing gap rather than an absent capability. The distinction
that remains is what the first paint is worth: Timeless emits plain HTML and CSS that is styled and
operable before any script runs, rather than markup awaiting an upgrade.

The trade is deliberate. You give up style encapsulation, and you get markup you can inspect,
override, and server-render with no framework in the request path.

## What post-framework does not mean

It does not mean less rigor. It means the rigor moves out of a runtime and into the build.

Nothing here re-implements what the browser already does, so the discipline is in keeping the
boundaries honest. Every public attribute, part, state, and permitted value is declared once in a
component registry, and the build proves those values against the stylesheets in both directions — a
documented value is a value the CSS implements. The CSS ships in three tiers, and a script fails the
build if a `core/` stylesheet declares a colour or a theme stylesheet keeps a property core owns.
[Styling](/docs/styling/css/) covers what that split means when you replace the theme.

You still own accessibility, and so do we: the conformance target is WCAG 2.2 Level AA, every
interactive component declares its keyboard contract, and the end-to-end suite asserts each
component still reads correctly with the theme removed.

Frameworks were a loan taken against an unfinished platform. The platform shipped. This is what it
looks like to stop making payments — not less engineering, just less of it spent in your users'
browsers.

## Next

- [Installation](/docs/getting-started/installation/) — add the package, load the CSS, register an
  element.
- [Quick start](/docs/getting-started/quick-start/) — build an interface from native HTML and
  explicit enhancement.
- [What Timeless does not ship](/docs/reference/scope/) — where the boundary of "primitive" sits,
  per component.

---

# Quick start

Source: https://timeless.build/docs/getting-started/quick-start.md

Build a Timeless interface from native HTML and explicit enhancement.

Import CSS and the definition entrypoint:

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
import '@timelessui/components/register/ui-popover'
```

Author the anatomy in HTML. This is the minimum a Popover needs:

```html
<ui-popover>
  <button class="ui-button" data-ui-part="trigger" type="button" popovertarget="release">
    Release status
  </button>
  <div id="release" popover="auto">
    <h2>Ready to publish</h2>
    <p>All required checks passed.</p>
  </div>
</ui-popover>
```

`popovertarget` is what makes this work before JavaScript: the button opens the surface natively,
and the browser handles light dismiss and Escape. Registration then adds `aria-controls`,
`aria-expanded`, `aria-haspopup`, the surface `role`, and anchored positioning.

## Author the parts you own

Timeless never writes your content or your accessible names. When the surface is a dialog, name and
describe it yourself:

```html
<div
  id="release"
  popover="auto"
  role="dialog"
  aria-labelledby="release-title"
  aria-describedby="release-summary"
>
  <h2 id="release-title">Ready to publish</h2>
  <p id="release-summary">All required checks passed.</p>
</div>
```

The component pages show this fuller form, because an example should be correct on its own. The
**Attributes** and **Anatomy** tables on each page mark what you must author and what the element
adds for you.

---

# Browser support

Source: https://timeless.build/docs/reference/browser-support.md

The platform features Timeless requires, and what happens where they are missing.

Timeless targets Baseline 2025 browsers. The floor is the newest requirement in each engine, and two
features set it between them — `:state()` in Chrome and Firefox, `light-dark()` in Safari: **Chrome
and Edge 125, Safari 17.5, and Firefox 126.** There are no polyfills, so support tracks the platform
features below.

Versions are taken from [MDN browser-compat-data](https://github.com/mdn/browser-compat-data) and
record the first release of each feature, not a support promise. Check
[Baseline](https://web.dev/baseline) for current data.

## Required features

All Baseline, and all older than the floor above except the last two rows, which set it. A browser
missing any of these cannot render Timeless correctly.

| Feature                  | Chrome / Edge | Safari | Firefox | Used by                                                   |
| ------------------------ | ------------- | ------ | ------- | --------------------------------------------------------- |
| Custom elements          | 54            | 10.1   | 63      | Every enhanced component                                  |
| `<dialog>`               | 37            | 15.4   | 98      | Dialog, Sheet                                             |
| Cascade layers           | 99            | 15.4   | 97      | Every stylesheet                                          |
| `:has()`                 | 105           | 15.4   | 121     | Field, Choice, and Range layout                           |
| `color-mix()`            | 111           | 16.2   | 113     | Derived accent and danger fills                           |
| Popover API              | 114           | 17     | 125     | Popover, Hover Card, Menu, Context Menu, Select, Combobox |
| `light-dark()`           | 123           | 17.5   | 120     | Tokens and themed surfaces                                |
| `:state()` custom states | 125           | 17.4   | 126     | Sheet drag, Toast exit, Color Picker, and Copy Button     |

## Progressive features

All three are Baseline as well, but they landed much later than the floor, so a browser that is
current-but-not-latest may still be missing them. Each degrades to something usable.

| Feature                                | Chrome / Edge | Safari | Firefox | Without it                                                                                                                                                                     |
| -------------------------------------- | ------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@starting-style` and `allow-discrete` | 117           | 17.5   | 129     | Overlays appear and disappear without the enter and exit transition.                                                                                                           |
| CSS anchor positioning                 | 125           | 26     | 147     | Overlay surfaces stay in normal flow next to their trigger instead of being anchored to it. They still open, close, dismiss, and trap focus correctly.                         |
| Invoker Commands                       | 135           | 26.2   | 144     | A dialog or modal sheet trigger needs JavaScript to open its panel, because the component falls back to its click listener. Popovers are unaffected: they use `popovertarget`. |

One requirement is not a version at all. [Copy Button](/docs/components/copy-button/) needs
`navigator.clipboard`, which every target engine has shipped for years but which is undefined
outside a secure context and refuses the write without transient user activation. So the same build
works on `https://` and on `localhost` and does nothing over plain `http://` — a staging box, or a
LAN address during development. The component reports that as `unsupported` on `ui-copy` rather than
failing silently, and a trigger authored `hidden` is revealed only once the API is there.

Anchor positioning is the widest gap in practice: Firefox only shipped it in 147, well above the
Firefox 126 floor. It is a layout refinement rather than a functional requirement, so a popover in
an older Firefox is fully usable, just not tethered to its trigger.

Invoker Commands are the one place where the markup you author decides which path runs. Put
`command="show-modal"` and `commandfor` on a Dialog or modal Sheet trigger and the browser opens the
panel itself, before the bundle loads; add `command="close"` to a close button and the platform
closes it and copies the button's `value` into `returnValue`. Timeless reads those attributes and
stands down — it never writes them, since an attribute added during enhancement would be back to
needing JavaScript. Where the API is missing, the component's click listener does the same work, so
one set of markup is correct everywhere.

Two limits come from the platform rather than from Timeless. An invoker can only name an `id` that
exists in the markup, so an invoked `<dialog>` needs an explicit one rather than a generated one.
And there is no built-in command for `dialog.show()`, so a **non-modal** Sheet cannot be opened
declaratively; leave `command` off that trigger and the click listener opens it. Its close buttons
still work declaratively.

### Wide-gamut color

`oklch()`, `oklab()`, `lch()`, `lab()`, `hwb()`, and `color(display-p3 …)` are Baseline everywhere
Timeless runs — Chrome 111, Safari 15, Firefox 113 — so this is not a browser-support question. What
varies is the **display**: an out-of-gamut color is rendered clamped on an sRGB screen. Color Picker
parses and edits the value faithfully regardless, flags when a color falls outside the current
gamut, and offers an explicit clamp control so you can decide rather than guess.

## Unsupported capability

When a component needs a platform capability the browser lacks, enhancement stops and the authored
markup is left exactly as written. Nothing is hidden, no public diagnostic attribute is added, and
no polyfill is loaded. A Popover in a browser without the Popover API keeps its native trigger and
content; the surface simply does not become a top-layer popover.

This is why every component page documents markup that already works before JavaScript runs.

Two components are the exception, and both are platform gaps rather than support ones.
[Context Menu](/docs/components/context-menu/) has no declarative way to open a surface at pointer
coordinates, so with scripting off the browser shows its own context menu and the authored `ui-menu`
stays hidden. Nothing reachable only from a context menu is reachable at all, in any browser, until
the bundle loads. [Copy Button](/docs/components/copy-button/) has no declarative way to reach the
clipboard: `navigator.clipboard` is undefined outside a secure context and refuses the write without
a user gesture, and `document.execCommand('copy')` is deprecated. Author its trigger `hidden` and
registration reveals it once the API is there, so no dead control renders.
[Sheet](/docs/components/sheet/)'s swipe-to-dismiss is a gentler version of the same shape: a
gesture is an addition, so Escape and the close control stay, and the sheet is fully operable
without a pointer.

## What is tested

Automated coverage runs on every change:

- Chromium for the website and the component catalog.
- Firefox and WebKit for platform contracts: form association, native validation, dialog and popover
  behavior, and no-JavaScript rendering.
- axe WCAG 2.2 A and AA rules, plus reflow and text-spacing checks, on every documented route.

These are regression evidence, not a conformance claim. Keyboard, zoom, forced-colors, and
screen-reader review with real assistive technology still belong to your release process.

---

# Packages and entrypoints

Source: https://timeless.build/docs/reference/packages.md

Every published import, what it contains, and whether it is safe on the server.

## Packages

| Package                  | Role                                                                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@timelessui/components` | Everything a consumer needs to build an interface: CSS, custom elements, contracts, and utilities. This is the only package you install for components.                                               |
| `@timelessui/color`      | CSS color parsing, conversion, gamut, and contrast utilities. It depends on nothing, and arrives as a dependency of the components; install it directly only if you want the color math without them. |
| `@timelessui/core`       | The internal custom-element authoring layer the components are built on. It arrives as a dependency; you do not import it directly, and it is not part of the public API.                             |

```bash
pnpm add @timelessui/components
```

## Entrypoints

| Import                                                         | Contains                                                                                         | Side effects                  |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------- |
| `@timelessui/components`                                       | Contracts, design-token names, permitted attribute values, event types, and every element class. | None                          |
| `@timelessui/components/{element}`                             | One enhanced element's class and helpers, for example `@timelessui/components/dialog`.           | None                          |
| `@timelessui/components/register/ui-{element}`                 | Registers one custom element as it is imported.                                                  | Calls `customElements.define` |
| `@timelessui/components/register`                              | Registers every public custom element as it is imported.                                         | Calls `customElements.define` |
| `@timelessui/components/define/ui-{element}`                   | One `define{Element}Element()` function. Registers nothing until you call it.                    | None                          |
| `@timelessui/components/define`                                | Every define function, plus `defineTimelessElements()`. Registers nothing until you call it.     | None                          |
| `@timelessui/components/css/tokens.css`                        | The cascade-layer order and `color-scheme`. Required, and imported first.                        | Stylesheet                    |
| `@timelessui/components/css/core/{component}.css`              | One component's behavior: anchoring, box participation, scrolling, native resets. Required.      | Stylesheet                    |
| `@timelessui/components/css/core.css`                          | Every `core/` file. Required, and the tier you keep when you replace the theme.                  | Stylesheet                    |
| `@timelessui/components/css/themes/atmosphere/tokens.css`      | Every `--ui-*` value. Required by any Atmosphere component file, which carries no fallbacks.     | Stylesheet                    |
| `@timelessui/components/css/themes/atmosphere/{component}.css` | One component's look. Optional — this is the tier you replace.                                   | Stylesheet                    |
| `@timelessui/components/css/themes/atmosphere.css`             | The required tiers plus every Atmosphere stylesheet. The one import a prototype needs.           | Stylesheet                    |
| `@timelessui/components/collection`                            | Locale-aware matching and disabled-aware keyboard navigation.                                    | None                          |
| `@timelessui/color`                                            | Color parsing, serialization, conversion, gamut, and WCAG contrast. Its own package.             | None                          |
| `@timelessui/components/events`                                | Transition event and detail types.                                                               | None                          |
| `@timelessui/components/value-state`                           | Authored-default and live-value helpers.                                                         | None                          |
| `@timelessui/components/attributes`                            | Typed attribute builder for CSS-only components.                                                 | None                          |
| `@timelessui/components/validate`                              | Development-time check that authored markup matches the contracts.                               | None                          |
| `@timelessui/components/react`                                 | React 19 intrinsic-element declarations. Types only.                                             | None                          |
| `@timelessui/components/preact`                                | Preact intrinsic-element declarations. Types only.                                               | None                          |
| `@timelessui/components/solid`                                 | Solid intrinsic-element declarations. Types only.                                                | None                          |
| `@timelessui/components/vue`                                   | Vue `GlobalComponents` declarations. Types only.                                                 | None                          |
| `@timelessui/components/svelte`                                | Svelte `svelteHTML.IntrinsicElements` declarations. Types only.                                  | None                          |

Only enhanced elements have a class entrypoint. CSS-only primitives such as Button, Alert, and Card
are classes and attributes rather than JavaScript, so they have no per-component module at all —
their permitted values live on the root import instead. Two pairs share one module behind two
subpaths, so importing either name gives you both classes: `radio-group` and `checkbox-group` are
both `choice-group`, and `toaster` and `toast` are both `toast`.

## What an entrypoint weighs

Enhanced elements are composed, so an entrypoint pulls the modules it is built on. Select contains
Listbox, the option layer, Popover, and the anchoring layer, which is why it is the heaviest single
import in the package.

Bundled and minified, `@timelessui/components/select` is about 13.5 kB gzipped. Adding
`@timelessui/components/combobox` to the same page brings the pair to about 16 kB rather than to the
sum of the two, because everything under both of them is shared. Six enhanced elements — Select,
Combobox, Listbox, Popover, Menu, and Dialog — come to about 21 kB together. There is no framework
runtime underneath any of it, and a CSS-only component such as Button or Card adds no JavaScript at
all.

Those are measurements rather than budgets, taken with esbuild at default settings; your bundler
will land somewhere nearby. The package ships unminified so your own pipeline decides.

## Contracts and permitted values

The root import is the machine-readable version of every component reference page:

```ts
import { buttonVariants, componentContracts } from '@timelessui/components'

buttonVariants
// ['primary', 'secondary', 'outline', 'ghost', 'danger', 'danger-outline', 'link']

componentContracts.tabs.parts.filter((part) => part.required).map((part) => part.selector)
// ["[role='tablist']", "[role='tab']", "[role='tabpanel']"]
```

`componentContracts` records each component's root, stylesheets, attributes with their permitted
values and defaults, authored parts, public state, and events. Every attribute that takes a fixed
set of values also names the array that set is exported as, in its `set` field.

The build proves those values against the stylesheets in both directions: a value a stylesheet
selects must be declared, and a declared value must be selected or be the default, which is the base
rule and so has no selector of its own. `pnpm -F @timelessui/components run contracts:validate`
fails either way, which is why the reference tables cannot drift from the CSS.

Permitted values are also exported individually as `as const` arrays with matching union types, each
declared exactly once and generated from the same source as the contracts: `buttonVariants`,
`buttonSizes`, `alertVariants`, `spinnerVariants`, `badgeVariants`, `avatarShapes`,
`avatarStatuses`, `cardVariants`, `linkVariants`, `listVariants`, `separatorVariants`,
`separatorOrientations`, `skeletonShapes`, `skeletonWidths`, `groupOrientations`, `primitiveSizes`,
`primitiveDensities`, `compactDensities`, `tableAlignments`, `breadcrumbSeparators`,
`formControlSizes`, `fieldLayouts`, `formDensities`, `choiceGroupOrientations`,
`floatingPlacements`, `tabsOrientations`, `tabsActivations`, `dialogKinds`, `sheetPositions`,
`popoverRoles`, `hoverCardVariants`, `menuOrientations`, `toolbarOrientations`,
`collectionAlignments`, `optionFilterModes`, `toasterPlacements`, `toasterStacks`,
`toggleGroupOrientations`, `toggleGroupSelections`, and `colorPickerFormats`.

Arrays with identical values keep separate names because they are separate public exports.
`buttonSizes`, `primitiveSizes`, and `formControlSizes` are all `sm | md | lg`, and each names the
set its own components implement.

## Design tokens

`uiTokenGroups` names every public custom property, grouped by purpose, and `isUIToken` narrows a
string against the set. Both name the theme-neutral `--ui-*` vocabulary rather than Atmosphere,
which is one set of values for it. See [Theming](/docs/styling/theming/) for the values and how to
override them.

## Custom Elements Manifest

`@timelessui/components/custom-elements.json` is exposed through the package's `customElements`
field. It declares attributes with union types and defaults, reflecting properties under their real
names, events with the detail type each element actually dispatches, CSS custom properties, and
custom states — for editors, generators, and downstream tooling.

Authored parts appear under a namespaced `timeless:parts` key rather than the manifest's `cssParts`,
each with the selector it is addressed by. `cssParts` describes `::part()`, which only crosses a
shadow boundary; Timeless anatomy is Light DOM you author yourself, so `[data-ui-part~='trigger']`
is the real contract and claiming a shadow one would be wrong.

## Framework typings

Every framework typing is generated from the manifest and is types-only: importing one adds no
runtime code, no wrapper, and no dependency on that framework. Import the one you need once in your
application types.

| Import                          | Augments                                |
| ------------------------------- | --------------------------------------- |
| `@timelessui/components/react`  | `react` and `react/jsx-runtime` `JSX`   |
| `@timelessui/components/preact` | `preact` and `preact/jsx-runtime` `JSX` |
| `@timelessui/components/solid`  | `solid-js` `JSX`                        |
| `@timelessui/components/vue`    | `@vue/runtime-dom` `GlobalComponents`   |
| `@timelessui/components/svelte` | `svelteHTML.IntrinsicElements`          |

Each declares, per element, the attributes an author writes typed to their permitted values, the DOM
properties those attributes reflect under the element's real property names, and the element's own
events with its own detail type. `data-*` and `aria-*` stay open as an escape hatch.

Two boundaries worth knowing:

- **React 19 is required** for `on*` event props on custom elements and for non-string attribute
  values. On React 18 the declarations still type your markup; pass primitives as attributes and
  bind events with a ref.
- **Angular** has no type-level checking for unknown elements beyond `CUSTOM_ELEMENTS_SCHEMA`, which
  disables checking rather than adding it. There is nothing to ship for Angular, so nothing is
  shipped. Timeless elements work there; their attributes are simply unchecked.

Qwik is not covered. Its JSX module moved between major versions and its custom-event prop
convention differs from the frameworks above, so no declaration is published rather than one that
might be wrong.

## Authoring CSS-only components

`ui-*` tags are tags, so every typing above and the editor data complete them precisely. CSS-only
components are a root class plus `data-ui-*` on a native tag, which no editor can complete per
element. `@timelessui/components/attributes` is the typed answer: `uiAttributes` returns the
attribute object and `uiAttributeString` the serialized form, both keyed to each component's
permitted values. Neither is reachable from the default import.

See [Editor setup](/docs/getting-started/editor-setup/#the-one-gap-css-only-components) for why the
gap exists, worked examples, and the development-time validator.

## Server rendering

Every import above is side-effect free except the stylesheets and the `register/*` entrypoints.
Class imports and `define/*` imports never call `customElements.define`, so they are safe in server
code and test utilities — `define/*` hands you the function and leaves the calling to you.

`register/*` is the one that registers on import, and it is inert on the server, where there is no
`customElements` to define into. That is deliberate: a universal module can import it without
crashing the render, and the client bundle re-imports the same module and registers for real. The
consequence is worth stating plainly — a `register/*` import that only ever executes on the server
registers nothing at all, so it belongs in code the browser loads. When you would rather be explicit
about the timing, import `define/*` and call the function yourself.

See [Core concepts](/docs/concepts/) for what registration does in a browser realm.

---

# What Timeless does not ship

Source: https://timeless.build/docs/reference/scope.md

The components Timeless deliberately leaves out, the reasoning behind each one, and the one that is deferred rather than refused.

Timeless is a library of primitives over the web platform. That is a boundary as much as a goal:
some widely shipped components are outside it, and saying which ones is more useful than leaving the
question to be re-argued per pull request.

Each row below is a decision, not an omission. Two tests decide them. Does the platform already do
this in a line or two of CSS? Then a component would only be a worse way to reach the same
declaration. Does it need domain machinery — a locale database, a layout engine, a virtualiser? Then
it is a library in its own right, and wrapping one is not a primitive.

Everything here is buildable on top of Timeless. Nothing here is a gap someone needs to fill before
the library is usable.

## The platform already does it

| Not shipping     | Because                                                                                                                                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Aspect Ratio** | `aspect-ratio: 16 / 9` is one declaration. A component around it adds a class to learn and a stylesheet to load in exchange for nothing.                                                                                                                          |
| **Scroll Area**  | Custom scrollbars fight momentum scrolling, trackpad inertia, and platform conventions, and they routinely drop keyboard and assistive-technology access. `scrollbar-color`, `scrollbar-width`, and `scrollbar-gutter` are Baseline and keep the native scroller. |
| **Carousel**     | Almost every implementation wraps a third-party engine. CSS scroll snap with scroll-marker and scroll-button pseudo-elements is the platform answer, and it keeps native swipe, keyboard, and scroll-anchoring behavior.                                          |

## It is a library, not a primitive

| Not shipping   | Because                                                                                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chart**      | Scales, axes, ticks, legends, and stacking are a charting library's whole surface area. Timeless would either wrap one or reimplement it badly.                                   |
| **Data Table** | Sorting, filtering, column resizing, pagination, and virtualisation belong to a table library. The CSS [Table](/docs/components/table/) stays: it styles the markup one produces. |
| **Tree View**  | The hardest pattern in the ARIA Authoring Practices Guide — typeahead, expand/collapse, multi-select across levels — with the least reuse across products.                        |

The same test cuts both ways. OKLCH and OKLab parsing, gamut mapping, and contrast computation are a
color library, so they ship as `@timelessui/color` rather than from the components package.
[Color Picker](/docs/components/color-picker/) and [Color Swatch](/docs/components/color-swatch/)
stay components: they are primitives that depend on that library, the same way every component
depends on a platform capability. What decides the boundary is the domain machinery, not the subject
matter.

## It is composition, not a component

| Not shipping               | Because                                                                                                                                                                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sidebar and app shells** | A shell is a layout decision that belongs to the application. It is grid, [Separator](/docs/components/separator/), and whatever navigation the product needs.                                                                                                                                                                                       |
| **Chat and AI surfaces**   | Message lists, streaming indicators, and prompt composers are product surfaces. They are built out of primitives; they are not primitives.                                                                                                                                                                                                           |
| **Command palette**        | [Combobox](/docs/components/combobox/) inside a [Dialog](/docs/components/dialog/), which is composition rather than a new contract. It is [documented as a recipe](/docs/components/select/) rather than shipped as a component.                                                                                                                    |
| **Navigation menu**        | Several triggers, one panel open at a time. [Hover Card](/docs/components/hover-card/) per trigger already gives the intent delay, the anchored panel, the `aria-expanded` wiring, and Escape — and a nav of links must not be an APG menu, which is the mistake a component here would make easy. [Documented as a recipe](/docs/components/menu/). |

## Deferred, not refused

**Date Picker and Calendar.** `<input type="date">` covers the common case today with a native
picker, native validation, and native form behavior, and it is the right default for most forms. A
real calendar is a different project: month grids across locales, week-start rules, non-Gregorian
calendars, ranges, and the APG grid pattern's full keyboard contract. That is worth doing properly
or not at all, so it is on the list to revisit rather than ruled out.

Until then, use `<input type="date">` with [Field](/docs/components/field/) for labelling,
description, and error wiring.

---

# Loading CSS

Source: https://timeless.build/docs/styling/css.md

The three CSS tiers, which two are required, and how to replace the theme with your own.

import { Aside } from '@astrojs/starlight/components'

Timeless CSS ships as plain stylesheets in three tiers. There is no build step, no preprocessor, and
no configuration — but two of the three tiers are required, and it is worth knowing which.

| Tier                                      | Required | Holds                                                                    |
| ----------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `tokens.css`                              | Yes      | The cascade-layer order, and `color-scheme`                              |
| `core.css`, or `core/<component>.css`     | Yes      | Behavior: anchoring, box participation, scrolling, native control resets |
| `themes/atmosphere.css`, or per component | No       | The look: colour, type, spacing, shadow, radius, motion                  |

Core is the tier people are surprised by. It is not styling — it is the implementation of "the
surface opens beside its trigger", "the closed menu is not on screen", and "the filtered option is
gone". Without it a Select opens unanchored and a filtered option stays visible, which is a broken
component rather than an unstyled one.

## One stylesheet, or only what you use

For prototypes, documents, and anything where request granularity does not matter, import the theme
— it pulls in the two required tiers itself:

```js
import '@timelessui/components/css/themes/atmosphere.css'
```

For applications, import the required tiers plus the exact component a route renders:

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/dialog.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/dialog.css'
```

Both paths produce the same public classes, custom properties, layers, and state selectors. The only
difference is how much CSS reaches the browser. Each component page lists every stylesheet that
component needs under **Styling**, core files included.

There is no default theme. `themes/atmosphere.css` names the theme it loads, and a second theme
would be a sibling of the same shape — `themes/<name>.css` beside `themes/<name>/`.

## Always import tokens first

`tokens.css` declares the order of the three Timeless layers:

```css
@layer ui.tokens, ui.components, ui.utilities;
```

Layers are ordered by first encounter, so whichever stylesheet is parsed first gets the
lower-priority layers. Load a component stylesheet before `tokens.css` and the order is established
by that file instead, which is how a rule you wrote in `ui.utilities` ends up losing to a component.

`themes/atmosphere.css` imports tokens first on your behalf. When importing granularly, put
`tokens.css` first yourself.

`tokens.css` also sets `color-scheme: light dark`, which is what makes `light-dark()` resolve to the
branch the reader asked for. Drop it and every scheme-dependent token silently returns its light
value.

See [Theming](/docs/styling/theming/) for what those layers mean in practice and which tokens and
component variables you can override.

## Bringing your own theme

The theme tier is genuinely optional, and replacing it is the supported path — for a design system
of your own, for Tailwind, or for any utility-class or CSS-in-JS setup. Import the two required
tiers and nothing else:

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core.css'
```

Every component is then positioned, structurally intact, and operable, with no appearance of ours:
UA colours, no radius, no shadow, the browser's default face. Style the public anatomy with whatever
you like — [Theming](/docs/styling/theming/#styling-without-the-atmosphere-theme) covers the
selectors that are yours to target.

A colour, radius, shadow, or type utility can never lose to Timeless on this path, and not by
convention: core is forbidden from declaring any of those properties, and a build check proves it.
The only properties core does declare are the behavioural ones — `display`, `overflow`, `position`,
the `inset` family, `appearance` and friends — so those are the only conflicts possible, and they
are conflicts you would be picking deliberately.

<Aside type="caution" title="Tailwind v4: import Timeless first">
  Tailwind v4 emits native cascade layers. Because layers are ordered by first encounter, importing
  your Tailwind stylesheet before Timeless puts every Tailwind layer *below* `ui.components` — and
  layer order beats specificity, so a `flex` or `grid` utility silently loses to core with no error
  to explain it. Import Timeless first. Tailwind v3 emits unlayered rules and always wins, either
  way. [Utility CSS and Tailwind](/docs/styling/utility-css/) has the worked example and the rest of
  the interactions.
</Aside>

Two things to expect on this path. Sizing stays in the theme, so a few components sit at their
content size rather than a designed one — a Sheet panel is content-height instead of full-height
until you give it a size, and a Select surface is as wide as its widest option instead of as wide as
its trigger, because `min-inline-size: anchor-size(width)` is a design decision. And core carries no
affordances, so there is no hover highlight and no focus ring until you add them.

Target size comes with the sizing, which makes it yours. Without the theme, seven components fall
under the 24×24 CSS pixels
[WCAG 2.2 SC 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) asks for —
the colour picker's channel sliders, the number stepper's step buttons, pagination's page links, and
the recipes built from them. A control can still conform by being spaced rather than large, which is
why core does not force a floor on you: a dense tool that wants small targets is a legitimate
design, and picking between the two is exactly the kind of decision the theme tier holds. Whichever
you pick, decide it rather than inheriting it. `apps/e2e` records the seven and fails on an eighth,
so this list stays honest.

---

# Theming

Source: https://timeless.build/docs/styling/theming.md

Override Timeless styles with cascade layers, design tokens, and component variables.

import { Aside } from '@astrojs/starlight/components'
import TokenTable from '../../../../components/docs/TokenTable.astro'

Timeless ships CSS in three tiers — the layer order, behavior, and the look — and only the last is
optional. [Loading CSS](/docs/styling/css/) covers which is which. This page is about the last one:
how to change how Timeless looks, or replace its appearance entirely.

There are three styling surfaces, in order of how often you should reach for them:

1. **Design tokens** — global values every component reads. Change these to rebrand everything.
2. **Component variables** — per-component custom properties. Change these to restyle one component.
3. **Your own CSS** — public classes, plain attributes, and `data-ui-part` selectors. Change these
   when you want something the first two cannot express.

There is no configuration file and no build step. All three are plain CSS.

## Cascade layers come first

`tokens.css` opens with the layer order, so every Timeless rule lands in a named layer:

```css
@layer ui.tokens, ui.components, ui.utilities;
```

Unlayered CSS beats layered CSS, whatever the specificity. So your own stylesheet wins over
component styles by default — a single class overrides a Timeless rule with three selectors, and you
never need `!important`:

```css
/* Wins over .ui-button, no matter how specific the component rule is. */
.checkout-button {
  border-radius: 0;
}
```

Put your CSS in `ui.utilities` when you want it layered but still above the components, and import
Timeless styles before your own so the layer order is established first.

<Aside type="caution" title="Import order matters">
  `tokens.css` declares the layer order. If a component stylesheet loads first, its `@layer
  ui.components` block establishes the order instead and `ui.tokens` ends up last. Always import
  `tokens.css` before any component CSS.
</Aside>

## Design tokens

Tokens are CSS custom properties on `:root`, all prefixed `--ui-`. Redefine any of them in your own
`:root` block, or scope them to a subtree to theme part of a page:

```css
:root {
  --ui-accent: oklch(58% 0.19 265);
  --ui-radius-control: 0.25rem;
  --ui-font-sans: 'Inter Variable', system-ui, sans-serif;
}

.marketing-section {
  --ui-bg-surface: #fffaf0;
}
```

The names and groups are exported as `uiTokenGroups` from `@timelessui/components`, so you can drive
a theme editor or a token audit from the same list this page is generated from. The export names the
vocabulary, not one theme's values: Atmosphere fills these names in, and a theme of your own fills
in the same ones.

### Color

<TokenTable group="color" />

### Control fills

<TokenTable group="controlFill" />

### Radius

<TokenTable group="radius" />

### Shadow

<TokenTable group="shadow" />

### Space

<TokenTable group="space" />

### Typography

<TokenTable group="typography" />

### Motion

<TokenTable group="motion" />

### Effects

<TokenTable group="effect" />

## Light and dark

`tokens.css` sets `color-scheme: light dark` and expresses every scheme-dependent token with
`light-dark()`:

```css
--ui-bg-surface: light-dark(#ffffff, #19191d);
```

That means the platform picks the scheme and no JavaScript is involved. To force one scheme, set
`color-scheme` on the root or on any subtree:

```css
/* Always light, even when the OS asks for dark. */
.invoice-preview {
  color-scheme: light;
}
```

When you override a scheme-dependent token, keep using `light-dark()` so both schemes stay correct:

```css
:root {
  --ui-bg-page: light-dark(#fdfdfd, #0d0d10);
}
```

Some tokens are deliberately scheme-independent — brand fills such as `--ui-bg-accent` are the same
in both schemes, and their hover and active steps are derived with `color-mix()` in OKLab:

```css
--ui-bg-accent-hover: color-mix(in oklab, #0064d8 78%, #0045b7);
```

## Component variables

Each component documents the custom properties it reads from its own root. They are listed in the
**Styling** section of every component page. Set them wherever you want the change to apply:

```css
/* Every button in the app. */
.ui-button {
  --ui-button-radius: 0.375rem;
}

/* One button. */
.checkout-button {
  --ui-button-bg: var(--ui-success);
  --ui-button-height: 3rem;
}
```

Component variables are the right tool when a token would be too broad: `--ui-radius-control` rounds
every control, while `--ui-button-radius` rounds only buttons.

## Styling without the Atmosphere theme

The theme is the optional tier. Import `tokens.css` and `core.css` and no theme at all, and every
component stays positioned, structurally intact, and operable while looking like nothing in
particular — which is exactly what you want when the look is yours to supply. See
[Loading CSS](/docs/styling/css/#bringing-your-own-theme) for the imports and the Tailwind caveat.

What you must keep is core. It is not a look: it is what anchors a Select surface to its trigger,
keeps a closed menu off screen, and keeps a filtered option hidden. Dropping it leaves components
that render but misbehave, which is worse than unstyled.

The public anatomy is the contract, and it is unchanged whether the theme is loaded or not:

- `.ui-*` classes identify CSS component roots.
- `data-ui-*` attributes carry contract-declared configuration on those roots.
- Plain attributes configure `ui-*` custom-element hosts.
- `data-ui-part` identifies authored anatomy.
- Native attributes, ARIA, and platform pseudo-classes carry state.

So a utility-class or CSS-in-JS project targets the same anatomy —
[Utility CSS and Tailwind](/docs/styling/utility-css/) works one through end to end:

```css
[data-ui-part~='trigger'] {
  /* your own trigger styling */
}

ui-tabs [role='tab'][aria-selected='true'] {
  /* your own selected-tab styling */
}
```

You can also replace the theme wholesale rather than opt out of it. `themes/atmosphere/` is one
directory of plain stylesheets, one per component, plus its own `tokens.css` holding the token
values this page documents. A second theme is a sibling of the same shape.

Never target `data-ui-internal-*`. Those are private runtime hooks and change without notice.

---

# Utility CSS and Tailwind

Source: https://timeless.build/docs/styling/utility-css.md

Style Timeless with Tailwind or any utility framework — the import order that decides who wins, a complete worked example, and the four conflicts that are possible.

import { Aside } from '@astrojs/starlight/components'

Utility CSS is a supported path, not a workaround. Timeless ships behavior and appearance in
separate tiers precisely so the appearance can be yours: import `tokens.css` and the core layer,
skip the theme, and every component is positioned, operable, and structurally intact with no look of
ours to fight. From there a `rounded-lg` or a `bg-white` is not overriding anything — there is
nothing to override.

One thing decides whether that works, and it fails silently when it is wrong: the import order.

## Import Timeless before Tailwind

Tailwind v4 emits native cascade layers, and CSS orders layers by first encounter. So whichever
stylesheet is parsed first gets the lower-priority layers, and layer order beats specificity
outright.

```css
/* Timeless first: `ui.*` registers first, so every Tailwind layer lands above it. */
@import '@timelessui/components/css/tokens.css';
@import '@timelessui/components/css/core.css';
@import 'tailwindcss';
```

That produces this layer order, which you can read in the compiled output:

```css
@layer ui.tokens, ui.components, ui.utilities;
@layer theme, base, components, utilities;
```

Invert the two imports and `ui.components` lands _after_ `utilities`. A utility for a property core
declares then loses, with no error and nothing in the console:

| Import order            | `overflow-visible` on a Popover surface | Result                     |
| ----------------------- | --------------------------------------- | -------------------------- |
| Timeless, then Tailwind | wins                                    | `overflow: visible`        |
| Tailwind, then Timeless | loses to `core/popover.css`             | `overflow: auto`, no error |

Only the properties core declares can conflict at all — `display`, `overflow`, `position`, the
`inset` family, `appearance`, and their neighbours. Core is forbidden from declaring a colour,
radius, shadow, type, or size property, and a build check proves it, so a `bg-*`, `rounded-*`,
`shadow-*`, or `text-*` utility cannot lose to Timeless whatever the order.

Tailwind v3 emits unlayered rules, which beat every layered rule regardless of order, so v3 wins
either way.

## A Popover, styled entirely in Tailwind

This is the whole thing: no theme CSS, one core stylesheet per component, and every visual decision
in a utility class.

```css
/* app.css */
@import '@timelessui/components/css/tokens.css';
@import '@timelessui/components/css/core/floating.css';
@import '@timelessui/components/css/core/popover.css';
@import 'tailwindcss';
```

```js
import { definePopoverElement } from '@timelessui/components/define/ui-popover'

definePopoverElement()
```

```html
<ui-popover>
  <button
    type="button"
    data-ui-part="trigger"
    popovertarget="panel"
    class="rounded-md bg-slate-900 px-4 py-2 text-sm font-medium text-white hover:bg-slate-700"
  >
    Menu
  </button>
  <div
    id="panel"
    popover="auto"
    aria-labelledby="panel-title"
    class="m-2 w-64 rounded-lg border border-slate-200 bg-white p-4 text-sm text-slate-900 shadow-lg"
  >
    <h2 id="panel-title" class="mb-1 font-semibold">Panel</h2>
    <p class="text-slate-600">Anchored by core CSS, styled by Tailwind utilities.</p>
  </div>
</ui-popover>
```

What each side contributes is worth being explicit about, because it is the same division for every
component:

- **The platform** opens and closes the surface, light-dismisses it, handles Escape, and puts it in
  the top layer. `popovertarget` and `popover` do that before any script runs.
- **Core CSS** gives the host `display: contents`, makes the panel scroll, and anchors it under the
  trigger with `position-area`.
- **Registration** adds what neither of those does: `aria-controls`, `aria-expanded`,
  `aria-haspopup`, and `role="dialog"` on the surface.
- **Your utilities** supply every pixel of the look, including the gap between trigger and surface —
  that is the `m-2`, which replaces the margin the theme would have set.

## Four conflicts, and what to do about them

Everything above is the happy path. These are the four places where utility CSS and the platform
interact in a way worth knowing in advance.

### The host already has a display; do not give it one

An unknown element defaults to `display: inline`, and Tailwind's Preflight does not reset custom
elements. Core does it for you — `ui-popover` is `display: contents`, `ui-combobox` is
`display: grid`, and so on — so there is nothing to hand-write.

The corollary follows from the import order above: because utilities win, a `block` or `flex`
utility _on the host_ defeats `display: contents` and puts a box between the trigger and its
surface. Style the parts, not the host.

### Style the surface's colour, not only its background

With no theme loaded, a `[popover]` or `<dialog>` takes the UA's `color: CanvasText` and
`background-color: Canvas`. `tokens.css` keeps `color-scheme: light dark` on purpose, so those
system colours follow the reader's preference — which means on a dark-preferring browser
`CanvasText` is white. A `bg-white` utility with no `text-*` alongside it gives you white text on a
white panel, in one theme only, which is a hard bug to catch.

Set both, as the example above does:

```html
<div id="panel" popover="auto" class="bg-white text-slate-900">…</div>
```

### Filtered options and `[hidden]`

Option filtering, paging, empty groups, and the pager all express themselves by setting the native
`hidden` attribute, and core hides them with `display: none`. A `display` utility on an option row
is therefore a rule about the same property as the rule that hides it.

Tailwind's Preflight already resolves this in your favour. It ships

```css
[hidden]:where(:not([hidden='until-found'])) {
  display: none !important;
}
```

so with the default `@import "tailwindcss"` a filtered option stays hidden even under `flex`. If you
import Tailwind without Preflight, that rule is gone, and a `flex` on an option row makes every
filtered option reappear. Guard the variant instead of the property:

```html
<div role="option" class="not-[[hidden]]:flex items-center gap-2">…</div>
```

### `:state()` has no built-in variant

A few components expose state through `ElementInternals` rather than an attribute — `ui-toast` has
`--closed`, `ui-color-picker` has `--copied` and `--contextual`, `ui-sheet` has `--dragging`.
Tailwind has no variant for `:state()`, but the arbitrary form compiles and matches:

```html
<ui-toast class="transition-opacity [&:state(--closed)]:opacity-0">…</ui-toast>
```

Everything else Timeless exposes is a native attribute, an ARIA attribute, or a platform
pseudo-class, all of which Tailwind already has variants for: `aria-expanded:*`, `aria-selected:*`,
`disabled:*`, `data-[ui-variant=primary]:*`, and arbitrary selectors such as
`[&[data-ui-part~='trigger']]:*` for authored anatomy. `open:*` is worth knowing on this library in
particular — in v4 it compiles to `:is([open], :popover-open, :open)`, so one variant covers an open
`<dialog>` and an open popover surface alike.

## What to target

The public anatomy is the same with or without a theme, so it is what your utilities and your own
CSS attach to: `.ui-*` roots, `data-ui-*` configuration on those roots, plain attributes on `ui-*`
hosts, `data-ui-part` for authored anatomy, and native attributes plus ARIA for state.
[Theming](/docs/styling/theming/#styling-without-the-atmosphere-theme) lists them with examples.

<Aside type="caution" title="Never target data-ui-internal-*">
  Those are private runtime hooks — the anchoring hooks among them — and they change without notice.
  Anchoring works because core owns those selectors; a utility aimed at one is a rule that will
  break.
</Aside>

Two more things to expect on the theme-free path, neither specific to Tailwind: sizing lives in the
theme, so a few components sit at their content size until you give them one, and core carries no
affordances, so there is no hover highlight and no focus ring until you add them.
[Loading CSS](/docs/styling/css/#bringing-your-own-theme) covers both.

---

# Alert

Communicate status without replacing native live-region semantics. (CSS only.)

Reference: https://timeless.build/docs/components/alert/

## Markup

```html
<section class="ui-alert" data-ui-variant="success" role="status">
  
  <div data-ui-part="content">
    <h2 data-ui-part="title">Package published</h2>
    <p data-ui-part="description">The component is available to downstream apps.</p>
    
  </div>
</section>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/alert.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/alert.css'
import '@timelessui/components/css/themes/atmosphere/link.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `icon` | No | `[data-ui-part~='icon']` | Decorative status icon. Mark it `aria-hidden="true"`. |
| `content` | No | `[data-ui-part~='content']` | Wrapper for the title and description. |
| `title` | No | `[data-ui-part~='title']` | Short summary line. |
| `description` | No | `[data-ui-part~='description']` | Supporting detail. |
| `actions` | No | `[data-ui-part~='actions']` | Container for one or two follow-up actions. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `neutral` · `accent` · `success` · `warning` · `danger` | `neutral` | Status intent. This is styling only — set `role="status"` or `role="alert"` yourself to control how assistive technology announces the message. |
| `data-ui-density` | `compact` · `normal` | `normal` | Internal spacing. |

## Styling

Root identity: `ui-alert`.
Required stylesheets: `tokens.css`, `core/alert.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/alert.css`, `themes/atmosphere/link.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (23), global and set at the theme level: `--ui-accent`, `--ui-accent-hover`, `--ui-accent-soft`, `--ui-bg-surface`, `--ui-danger`, `--ui-danger-soft`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-lg`, `--ui-radius-xs`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`, `--ui-success`, `--ui-success-soft`, `--ui-warning`, `--ui-warning-soft`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) from the ARIA Authoring Practices Guide.

The role is yours to choose, and it depends on when the alert appears. Something rendered with the page is not an alert at all — give it `role="status"`, or no role and a heading, because a live region announces *changes* and there is no change on first paint. Something inserted in response to what the user just did is a live region: `role="status"` to wait its turn, `role="alert"` to interrupt, and the latter only when the message cannot wait. The `icon` part is decorative and must be hidden from assistive technology; `data-ui-variant` carries no meaning on its own, so say in the text what the colour implies.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Avatar

Identity fallback and presence indicators. (CSS only.)

Reference: https://timeless.build/docs/components/avatar/

## Markup

```html
<span class="ui-avatar" data-ui-status="online" role="img" aria-label="Avery Stone, online">
  <span data-ui-part="fallback">AS</span>
  <span data-ui-part="status" aria-hidden="true"></span>
</span>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/avatar.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/avatar.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `image` | No | `[data-ui-part~='image']` | The `<img>`. Give it an empty `alt` when a label follows. |
| `fallback` | No | `[data-ui-part~='fallback']` | Initials or icon shown when no image loads. |
| `status` | No | `[data-ui-part~='status']` | Presence dot. Decorative; keep it `aria-hidden="true"`. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Avatar diameter. |
| `data-ui-shape` | `circle` · `rounded` · `square` | `circle` | Corner treatment. |
| `data-ui-status` | `online` · `away` · `busy` · `offline` | — | Presence indicator color. Omit the attribute to hide the indicator. The dot is decorative, so also expose the status in text. |

## Styling

Root identity: `ui-avatar`.
Required stylesheets: `tokens.css`, `core/avatar.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/avatar.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (11), global and set at the theme level: `--ui-bg-page`, `--ui-bg-surface-raised`, `--ui-danger`, `--ui-fg`, `--ui-fg-subtle`, `--ui-line`, `--ui-radius-lg`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-success`, `--ui-warning`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Badge

Compact status and metadata labels. (CSS only.)

Reference: https://timeless.build/docs/components/badge/

## Markup

```html
<span class="ui-badge" data-ui-variant="success"><span data-ui-part="dot" aria-hidden="true"></span>Stable</span>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/badge.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/badge.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `dot` | No | `[data-ui-part~='dot']` | Leading status dot. Decorative. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `neutral` · `accent` · `success` · `warning` · `danger` · `outline` | `neutral` | Status intent. |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Badge height and font size. |

## Styling

Root identity: `ui-badge`.
Required stylesheets: `tokens.css`, `core/badge.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/badge.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (14), global and set at the theme level: `--ui-accent-soft`, `--ui-bg-control-muted`, `--ui-danger`, `--ui-danger-soft`, `--ui-fg`, `--ui-line`, `--ui-radius-pill`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-success`, `--ui-success-soft`, `--ui-warning`, `--ui-warning-soft`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Breadcrumb

A trail of links to the pages above this one. CSS only. (CSS only.)

Reference: https://timeless.build/docs/components/breadcrumb/

> **Choosing between components.** A breadcrumb says where the current page sits in a hierarchy. For moving between siblings at the same level use [Tabs](/docs/components/tabs/), and for a list of pages in a sequence use [Pagination](/docs/components/pagination/).

> **Markup you author.** Give the `<nav>` an `aria-label` — a page can hold several landmarks of the same type, and an unnamed one is indistinguishable from the rest. Author the final crumb as a `<span data-ui-part="current" aria-current="page">` rather than a link: a link to the page you are already on goes nowhere. Author nothing between the crumbs; the separator is drawn.

## Markup

```html
<nav class="ui-breadcrumb" aria-label="Breadcrumb">
  <ol>
    <li data-ui-part="item"><a data-ui-part="link" href="/docs/">Documentation</a></li>
    <li data-ui-part="item"><a data-ui-part="link" href="/docs/components/">Components</a></li>
    <li data-ui-part="item"><span data-ui-part="current" aria-current="page">Breadcrumb</span></li>
  </ol>
</nav>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/breadcrumb.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/breadcrumb.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `item` | No | `[data-ui-part~='item']` | One crumb. Use `<li>`; the separator is drawn before every crumb but the first, so nothing is authored between them. |
| `link` | No | `[data-ui-part~='link']` | The link inside a crumb. Use `<a href>`. |
| `current` | No | `[data-ui-part~='current']` | The final crumb, which names the page you are already on. Author it as a `<span>` rather than a link — a link to here goes nowhere — and put `aria-current="page"` on it. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-separator` | `chevron` · `slash` | `chevron` | Which glyph is drawn between crumbs. Both are generated content rather than markup, so neither reaches the accessibility tree and neither is yours to author. For any other glyph, set `--ui-breadcrumb-separator` instead of asking for a new value here. |
| `data-ui-density` | `compact` · `normal` | `normal` | Gap between a crumb and its separator. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `current` | aria | Author `aria-current="page"` on the final crumb. Timeless never writes it: which page you are on is not something a stylesheet can know. |

## Styling

Root identity: `ui-breadcrumb`.
Required stylesheets: `tokens.css`, `core/breadcrumb.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/breadcrumb.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-breadcrumb-gap` | Gap between a crumb and its separator. |
| `--ui-breadcrumb-separator` | The separator glyph, as a CSS string. Comes from `data-ui-separator`; set it directly for a glyph the attribute does not offer. Keep the `/ ""` alternative text if you redeclare `content` yourself, or the glyph starts being announced. |

Design tokens this component reads (9), global and set at the theme level: `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-radius-xs`, `--ui-space-1`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) from the ARIA Authoring Practices Guide.

No keyboard behavior of its own, and the APG says so too: a breadcrumb is links in a labelled landmark, and `Tab` is the traversal. Author `<nav>` with an `aria-label`, an `<ol>` inside it, and the final crumb as an unlinked `<span aria-current="page">`. The separator is a `::before` pseudo-element with empty alternative text, so it is drawn but never announced — which is why there is no separator part to author and no `aria-hidden` to remember.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Button

Tactile native actions with clear variants. (CSS only.)

Reference: https://timeless.build/docs/components/button/

## Markup

```html
<button class="ui-button" type="button">Publish component</button>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
```

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `primary` · `secondary` · `outline` · `ghost` · `danger` · `danger-outline` · `link` | `primary` | Visual intent. Use `primary` for the main action in a view, `secondary` for neutral actions, `outline` when the action needs a stronger edge, `ghost` for low-emphasis toolbar actions, `danger` and `danger-outline` for destructive actions, and `link` for an action that should read as inline text. |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `disabled` | native | Native `disabled`, or `aria-disabled` on an anchor. |

## Styling

Root identity: `ui-button`.
Required stylesheets: `tokens.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-button-bg` | Resting background. |
| `--ui-button-bg-hover` | Hover background. |
| `--ui-button-bg-active` | Active background. |
| `--ui-button-fg` | Label color. |
| `--ui-button-fg-hover` | Hover label color. |
| `--ui-button-border` | Border color. |
| `--ui-button-shadow` | Resting shadow. |
| `--ui-button-shadow-hover` | Hover shadow. |
| `--ui-button-shadow-active` | Active shadow. |
| `--ui-button-height` | Minimum block size. |
| `--ui-button-padding-x` | Inline padding. |
| `--ui-button-gap` | Gap between icon and label. |
| `--ui-button-radius` | Corner radius. |

Design tokens this component reads (20), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-focus`, `--ui-radius-control`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-outline-control`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Card

Flat structured content with public anatomy. (CSS only.)

Reference: https://timeless.build/docs/components/card/

## Markup

```html
<article class="ui-card">
  <header data-ui-part="header">
    <p data-ui-part="meta">Reference</p>
    <h2 data-ui-part="title">Component contract</h2>
    <p data-ui-part="description">Review the public anatomy before publishing.</p>
  </header>
  <footer data-ui-part="footer">
    <div data-ui-part="actions">
      <a class="ui-link" href="#card">Open</a>
      <span class="ui-badge" data-ui-variant="success">Stable</span>
    </div>
  </footer>
</article>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/card.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/badge.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/badge.css'
import '@timelessui/components/css/themes/atmosphere/card.css'
import '@timelessui/components/css/themes/atmosphere/link.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `header` | No | `[data-ui-part~='header']` | Top region, usually the title and meta. |
| `body` | No | `[data-ui-part~='body']` | Main content region. |
| `footer` | No | `[data-ui-part~='footer']` | Bottom region, usually actions. |
| `title` | No | `[data-ui-part~='title']` | Card heading. Use a real heading element. |
| `description` | No | `[data-ui-part~='description']` | Supporting copy under the title. |
| `meta` | No | `[data-ui-part~='meta']` | Secondary metadata such as a category or date. |
| `actions` | No | `[data-ui-part~='actions']` | Container for card actions. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `surface` · `filled` · `ghost` | `surface` | Background and border treatment. |
| `data-ui-density` | `compact` · `normal` | `normal` | Internal spacing. |

## Styling

Root identity: `ui-card`.
Required stylesheets: `tokens.css`, `core/card.css`, `core/button.css`, `core/badge.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/badge.css`, `themes/atmosphere/card.css`, `themes/atmosphere/link.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (40), global and set at the theme level: `--ui-accent`, `--ui-accent-hover`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-danger`, `--ui-danger-soft`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-pill`, `--ui-radius-xs`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`, `--ui-success`, `--ui-success-soft`, `--ui-warning`, `--ui-warning-soft`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Checkbox Group

Coordinate a group of native checkboxes. (Custom element.)

Reference: https://timeless.build/docs/components/checkbox-group/

> **Choosing between components.** One component, two levels of behavior. `<ui-checkbox-group>` adds roving focus and a single change event over the group; the plain `<fieldset class="ui-choice-group">` below it is the same markup with no custom element, and it submits, resets, and takes keyboard input on its own. The element is an addition to native checkboxes, not a replacement for them, so it is never a choice between a CSS version and a JavaScript version.

## Markup

```html
<ui-checkbox-group aria-labelledby="features-label">
  <span id="features-label">Features</span>
  <label class="ui-choice">
  <input class="ui-checkbox" type="checkbox" name="features" value="documentation" checked>
  <span data-ui-part="body">Documentation</span>
</label>
  <label class="ui-choice">
  <input class="ui-checkbox" type="checkbox" name="features" value="playground">
  <span data-ui-part="body">Playground</span>
</label>
</ui-checkbox-group>
<fieldset class="ui-choice-group">
  <legend class="ui-label">Notifications</legend>
  
  <label class="ui-choice" for="notifications-product">
    <input class="ui-checkbox" id="notifications-product" name="notifications" type="checkbox" value="product" checked>
    <span data-ui-part="body">
      <span data-ui-part="title">Product updates</span>
      
    </span>
  </label>
  <label class="ui-choice" for="notifications-security">
    <input class="ui-checkbox" id="notifications-security" name="notifications" type="checkbox" value="security" checked>
    <span data-ui-part="body">
      <span data-ui-part="title">Security notices</span>
      
    </span>
  </label>
  
</fieldset>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/choice-groups.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/choice-groups.css'
import '@timelessui/components/register/ui-checkbox-group'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineCheckboxGroupElement } from '@timelessui/components/define/ui-checkbox-group'
defineCheckboxGroupElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-checkbox-group>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `choice` | Yes | `input[type='checkbox']` | One native checkbox input. Author `checked` for the initial state; the group reports every checked value. |

**ui-choice-group**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `description` | No | `[data-ui-part~='description']` | Group-level help text under the legend. |
| `error` | No | `[data-ui-part~='error']` | Group-level validation message. |

**ui-choice**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `body` | No | `[data-ui-part~='body']` | Wrapper for the title and description beside the control. |
| `title` | No | `[data-ui-part~='title']` | The choice label text. |
| `description` | No | `[data-ui-part~='description']` | Supporting copy under the choice label. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-checkbox-group>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `vertical` · `horizontal` | `vertical` | Layout and arrow-key axis. |

**ui-choice-group**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-orientation` | `vertical` · `horizontal` | `vertical` | Layout direction of the choices. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between choices. |

**ui-choice**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between the control and its label. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-checkbox-group>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'vertical' | 'horizontal'` | Reflects the `orientation` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<CheckboxGroupChangeDetail>` | Cancelable proposal dispatched before the set of checked boxes changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<CheckboxGroupChangeDetail>` | Dispatched after the set of checked boxes has changed. Bubbles and is composed. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | aria | Set `aria-invalid="true"` on the `<fieldset>` and describe the error. |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-checkbox-group`, `ui-choice-group`, `ui-choice`, `ui-checkbox`.
Required stylesheets: `tokens.css`, `core/choice-groups.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`, `themes/atmosphere/choice-groups.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) from the ARIA Authoring Practices Guide.

Every key comes from the native checkboxes: Tab reaches each one, Space toggles the focused box, and each box submits its own value. There is deliberately no roving `tabindex` and no arrow navigation — a checkbox group is a set of independent controls rather than one composite widget, so each being its own tab stop is the APG treatment. `ui-checkbox-group` adds only the group role, the orientation, and one change event for the set. A group that should be one tab stop is a [Listbox](/docs/components/listbox/) with `multiple`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Collapsible

Style native disclosure groups without replacing details. (CSS only.)

Reference: https://timeless.build/docs/components/collapsible/

> **Choosing between components.** One expandable region or a whole stack of them: both are `<details>` with `.ui-collapsible`, so there is no second component to choose. Give every `<details>` in a stack the same `name` to get an accordion where only one panel is open at a time — the browser closes the previous one, so no script is involved. Omit `name` and the panels open independently.

## Markup

```html
<div>
  <details class="ui-collapsible" name="catalog-collapsible" open>
    <summary>What ships?</summary>
    <div>
      <p>CSS, explicit element definitions, and public types.</p>
    </div>
  </details>
  <details class="ui-collapsible" name="catalog-collapsible">
    <summary>Does it need JavaScript?</summary>
    <div>
      <p>No. Native details and summary own the open state, the keyboard, and find-in-page.</p>
    </div>
  </details>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/collapsible.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/collapsible.css'
```

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` | `normal` | Summary and content padding. |

## Styling

Root identity: `ui-collapsible`.
Required stylesheets: `tokens.css`, `core/collapsible.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/collapsible.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-collapsible-line` | Divider color between rows. |
| `--ui-collapsible-trigger-min-block-size` | Minimum summary height. |
| `--ui-collapsible-trigger-padding-block` | Block padding inside the summary. |
| `--ui-collapsible-trigger-gap` | Gap between the summary text and the indicator. |
| `--ui-collapsible-panel-padding-block-end` | Block-end padding below the panel. |
| `--ui-collapsible-icon-size` | Size of the chevron indicator. |
| `--ui-collapsible-duration` | Indicator and panel transition duration. |

Design tokens this component reads (10), global and set at the theme level: `--ui-accent`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) from the ARIA Authoring Practices Guide.

Every key comes from native `<details>` and `<summary>`: Enter and Space toggle, Tab reaches the summary, and find-in-page opens a closed panel to reveal a match. Timeless adds no script and no ARIA, because the platform already exposes the button, its expanded state, and the region it controls. For an accordion where only one panel is open at a time, give every `<details>` in the stack the same `name`; the browser closes the previously open one, with no JavaScript involved.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Color Picker

Edit modern color formats through authored controls. (Custom element.)

Reference: https://timeless.build/docs/components/color-picker/

## Markup

```html
<ui-color-picker value="oklch(62% 0.18 32)" format="oklch" aria-label="Brand color">
  <div data-ui-part="preview">
    <div data-ui-part="preview-bar">
      <label data-ui-part="format-field">
        <span data-ui-part="input-label">Color format</span>
        <select data-ui-part="format">
          <optgroup label="Perceptual"><option value="oklch">oklch</option><option value="oklab">oklab</option><option value="lch">lch</option><option value="lab">lab</option></optgroup>
          <optgroup label="sRGB"><option value="hex">hex</option><option value="rgb">rgb</option><option value="hsl">hsl</option><option value="hwb">hwb</option></optgroup>
          <optgroup label="Wide gamut"><option value="p3">p3</option><option value="rec2020">rec2020</option></optgroup>
        </select>
      </label>
      <div data-ui-part="gamut-bar">
        <button data-ui-part="clamp" value="srgb" type="button" aria-label="Clamp to sRGB" hidden>&rarr; sRGB</button>
        <button data-ui-part="clamp" value="p3" type="button" aria-label="Clamp to P3" hidden>&rarr; P3</button>
      </div>
    </div>
    <div data-ui-part="readout">
      <span data-ui-part="gamut" aria-hidden="true"></span>
      <label>
        <span data-ui-part="input-label">Raw color value</span>
        <input data-ui-part="input" type="text" spellcheck="false" autocomplete="off" aria-describedby="brand-color-warning">
      </label>
      <button data-ui-part="copy" type="button" aria-label="Copy color value">
        <svg data-ui-part="copy-icon" viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
          <rect x="5.75" y="5.75" width="8.5" height="8.5" rx="2" />
          <path d="M10.25 3.5A1.75 1.75 0 0 0 8.5 1.75h-4.75A1.75 1.75 0 0 0 2 3.5v6.75" />
        </svg>
        <svg data-ui-part="copied-icon" viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
          <path d="M2.75 8.75 6.25 12.25 13.25 4.25" />
        </svg>
      </button>
    </div>
  </div>
  <div data-ui-part="channels">
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Lightness">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Lightness value">
    </div>
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Chroma">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Chroma value">
    </div>
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Hue">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Hue value">
    </div>
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Alpha">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Alpha value">
    </div>
    <p id="brand-color-warning" data-ui-part="warning" role="status" hidden></p>
  </div>
</ui-color-picker>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/color-picker.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/color-picker.css'
import '@timelessui/components/register/ui-color-picker'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineColorPickerElement } from '@timelessui/components/define/ui-color-picker'
defineColorPickerElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `preview` | No | `[data-ui-part~='preview']` | Region holding the format select, gamut controls, and readout. |
| `preview-bar` | No | `[data-ui-part~='preview-bar']` | Row above the readout. |
| `format-field` | No | `[data-ui-part~='format-field']` | Label wrapper around the format select. |
| `format` | Yes | `select` | Native `<select>` listing the supported color formats. |
| `gamut-bar` | No | `[data-ui-part~='gamut-bar']` | Row holding the clamp buttons. |
| `clamp` | No | `[data-ui-part~='clamp']` | Button that clamps an out-of-gamut color into sRGB or P3. Shown only when needed. |
| `readout` | No | `[data-ui-part~='readout']` | Row holding the swatch, raw input, and copy button. |
| `gamut` | No | `[data-ui-part~='gamut']` | Current-color swatch. Decorative. |
| `input` | Yes | `input[type='text']` | Raw CSS color value, editable as text. |
| `input-label` | No | `[data-ui-part~='input-label']` | Screen-reader label for the raw input or format select. |
| `copy` | No | `[data-ui-part~='copy']` | Copies the raw value to the clipboard. |
| `copy-icon` | No | `[data-ui-part~='copy-icon']` | Idle state of the copy button. Decorative. |
| `copied-icon` | No | `[data-ui-part~='copied-icon']` | Confirmed state of the copy button. Decorative. |
| `channels` | No | `[data-ui-part~='channels']` | Container for the per-channel rows. |
| `channel` | Yes | `[data-ui-part~='channel']` | One channel row. The picker rewrites the rows when `format` changes, so author one row per channel of the widest format you support. |
| `channel-label` | No | `[data-ui-part~='channel-label']` | Channel name. Written by the picker; decorative. |
| `channel-range` | Yes | `input[type='range']` | Slider for one channel. |
| `channel-input` | Yes | `input[type='number']` | Numeric entry for one channel. |
| `warning` | No | `[data-ui-part~='warning']` | Out-of-gamut or unparsable-value message. |
| `trigger` | No | `[data-ui-part~='trigger']` | Optional button when the picker lives inside a popover. |
| `content` | No | `[data-ui-part~='content']` | Optional popover surface wrapping the picker. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `format` | `oklch` · `oklab` · `lch` · `lab` · `hex` · `rgb` · `hsl` · `hwb` · `p3` · `rec2020` | `oklch` | Color space the channel controls edit and the raw input round-trips through. The picker converts the current value when this changes. |
| `value` | any `string` | — | Initial and form-reset color, in any CSS color syntax. Unlike the collection elements, the picker reflects one `value` property rather than a separate authored default. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-color-picker>`

| Property | Type | Notes |
| --- | --- | --- |
| `format` | `'oklch' | 'oklab' | 'lch' | 'lab' | 'hex' | 'rgb' | 'hsl' | 'hwb' | 'p3' | 'rec2020'` | Reflects the `format` attribute |
| `value` | `string` | Reflects the `value` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `input` | `Event` | Native `input` event dispatched while the color is being edited. |
| `change` | `Event` | Native `change` event dispatched when the edit is committed. |

## Styling

Root identity: `ui-color-picker`.
Required stylesheets: `tokens.css`, `core/color-picker.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/color-picker.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (24), global and set at the theme level: `--ui-bg-control`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-bg-surface-subtle`, `--ui-checkerboard`, `--ui-danger`, `--ui-disabled-opacity`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-font-mono`, `--ui-line`, `--ui-line-strong`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-floating`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-warning`, `--ui-warning-soft`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

The ARIA Authoring Practices Guide has no pattern for Colour channels. The contract below is a composition of behavior the platform already defines, not ARIA invented to fill the gap.

The APG has no colour-picker pattern, and this deliberately does not invent one: every control here is a native `input[type="range"]` or `input[type="number"]`, so each channel is its own labelled, tabbable slider or field with its own value announcement, and arrow keys, Home, End, and typing all come from the platform. Timeless names each channel from its definition and keeps the two representations of one channel in step. There is no two-dimensional saturation-value area, because that has no accessible keyboard model that a set of named channels does not already provide better. The generated swatch is decorative and hidden from assistive technology; the value the user is editing is the text of the raw field, and an unparseable draft is marked `aria-invalid` rather than being silently discarded. The channel sliders are 10px tall, which relies on SC 2.5.8 spacing rather than target size — keep the gap between them if you restyle it.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

## Popover Color Picker

Compose Color Picker and Popover.

```html
<ui-popover>
  <button class="ui-color-swatch" type="button" data-ui-part="trigger" aria-label="Edit Brand color" style="--ui-color-swatch: oklch(62% 0.18 32)">
    <span data-ui-part="chip" aria-hidden="true"></span>
    <span data-ui-part="label">Brand color</span>
    <span data-ui-part="value">oklch(62% 0.18 32)</span>
  </button>
  <ui-color-picker value="oklch(62% 0.18 32)" format="oklch" aria-label="Brand color" data-ui-part="content" popover role="dialog">
  <div data-ui-part="preview">
    <div data-ui-part="preview-bar">
      <label data-ui-part="format-field">
        <span data-ui-part="input-label">Color format</span>
        <select data-ui-part="format">
          <optgroup label="Perceptual"><option value="oklch">oklch</option><option value="oklab">oklab</option><option value="lch">lch</option><option value="lab">lab</option></optgroup>
          <optgroup label="sRGB"><option value="hex">hex</option><option value="rgb">rgb</option><option value="hsl">hsl</option><option value="hwb">hwb</option></optgroup>
          <optgroup label="Wide gamut"><option value="p3">p3</option><option value="rec2020">rec2020</option></optgroup>
        </select>
      </label>
      <div data-ui-part="gamut-bar">
        <button data-ui-part="clamp" value="srgb" type="button" aria-label="Clamp to sRGB" hidden>&rarr; sRGB</button>
        <button data-ui-part="clamp" value="p3" type="button" aria-label="Clamp to P3" hidden>&rarr; P3</button>
      </div>
    </div>
    <div data-ui-part="readout">
      <span data-ui-part="gamut" aria-hidden="true"></span>
      <label>
        <span data-ui-part="input-label">Raw color value</span>
        <input data-ui-part="input" type="text" spellcheck="false" autocomplete="off" aria-describedby="popover-brand-color-warning">
      </label>
      <button data-ui-part="copy" type="button" aria-label="Copy color value">
        <svg data-ui-part="copy-icon" viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
          <rect x="5.75" y="5.75" width="8.5" height="8.5" rx="2" />
          <path d="M10.25 3.5A1.75 1.75 0 0 0 8.5 1.75h-4.75A1.75 1.75 0 0 0 2 3.5v6.75" />
        </svg>
        <svg data-ui-part="copied-icon" viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
          <path d="M2.75 8.75 6.25 12.25 13.25 4.25" />
        </svg>
      </button>
    </div>
  </div>
  <div data-ui-part="channels">
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Lightness">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Lightness value">
    </div>
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Chroma">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Chroma value">
    </div>
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Hue">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Hue value">
    </div>
    <div data-ui-part="channel">
      <span data-ui-part="channel-label" aria-hidden="true"></span>
      <input data-ui-part="channel-range" type="range" aria-label="Alpha">
      <input data-ui-part="channel-input" type="number" inputmode="decimal" aria-label="Alpha value">
    </div>
    <p id="popover-brand-color-warning" data-ui-part="warning" role="status" hidden></p>
  </div>
</ui-color-picker>
</ui-popover>
```

```js
for (const popover of document.querySelectorAll('ui-popover')) {
  const picker = popover.querySelector('ui-color-picker')
  const trigger = popover.querySelector("[data-ui-part~='trigger']")
  if (!picker || !trigger) continue
  const value = trigger.querySelector("[data-ui-part~='value']")
  const sync = () => {
    trigger.style.setProperty('--ui-color-swatch', picker.value)
    if (value) value.textContent = picker.value
  }
  picker.addEventListener('input', sync)
  picker.addEventListener('change', sync)
}
```

---

# Color Swatch

Display and select a named color value. (CSS only.)

Reference: https://timeless.build/docs/components/color-swatch/

## Markup

```html
<div class="ui-color-swatch" style="--ui-color-swatch: oklch(62% 0.18 32)">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand red</span>
  <span data-ui-part="value">oklch(62% 0.18 32)</span>
  
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/color-swatch.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/color-swatch.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `chip` | No | `[data-ui-part~='chip']` | The color area. Set the color through `--ui-swatch-color`. |
| `label` | No | `[data-ui-part~='label']` | Human-readable color name. |
| `value` | No | `[data-ui-part~='value']` | The raw CSS color value. |
| `warning` | No | `[data-ui-part~='warning']` | Out-of-gamut or contrast warning. |

## Styling

Root identity: `ui-color-swatch`.
Required stylesheets: `tokens.css`, `core/color-swatch.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/color-swatch.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (18), global and set at the theme level: `--ui-accent`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-checkerboard`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-font-mono`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-sm`, `--ui-space-2`, `--ui-space-3`, `--ui-warning`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

## Color Palette

Lay several swatches out as a selectable grid across CSS color formats.

```html
<div style="display: grid; gap: 0.5rem; grid-template-columns: repeat(auto-fill, minmax(13rem, 1fr))">
  <button class="ui-color-swatch" type="button" aria-pressed="false" aria-label="Select Brand red, oklch(62% 0.18 32)" style="--ui-color-swatch: oklch(62% 0.18 32)">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand red</span>
  <span data-ui-part="value">oklch(62% 0.18 32)</span>
  
</button>
  <button class="ui-color-swatch" type="button" aria-pressed="false" aria-label="Select Brand amber, hwb(38 6% 8%)" style="--ui-color-swatch: hwb(38 6% 8%)">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand amber</span>
  <span data-ui-part="value">hwb(38 6% 8%)</span>
  
</button>
  <button class="ui-color-swatch" type="button" aria-pressed="false" aria-label="Select Brand lime, color(display-p3 0.63 0.86 0.2)" style="--ui-color-swatch: color(display-p3 0.63 0.86 0.2)">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand lime</span>
  <span data-ui-part="value">color(display-p3 0.63 0.86 0.2)</span>
  
</button>
  <button class="ui-color-swatch" type="button" aria-pressed="false" aria-label="Select Brand teal, lch(70% 45 190)" style="--ui-color-swatch: lch(70% 45 190)">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand teal</span>
  <span data-ui-part="value">lch(70% 45 190)</span>
  
</button>
  <button class="ui-color-swatch" type="button" aria-pressed="true" aria-label="Select Brand blue, #3366cc" style="--ui-color-swatch: #3366cc">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand blue</span>
  <span data-ui-part="value">#3366cc</span>
  
</button>
  <button class="ui-color-swatch" type="button" aria-pressed="false" aria-label="Select Brand violet, oklch(52% 0.24 300)" style="--ui-color-swatch: oklch(52% 0.24 300)">
  <span data-ui-part="chip" aria-hidden="true"></span>
  <span data-ui-part="label">Brand violet</span>
  <span data-ui-part="value">oklch(52% 0.24 300)</span>
  
</button>
</div>
```

---

# Combobox

Filter an authored listbox from a native text input. (Custom element.)

Reference: https://timeless.build/docs/components/combobox/

> **Choosing between components.** Combobox and [Select](/docs/components/select/) are the same ARIA pattern over the same option core, differing only in where you type. Reach for Combobox when the user should be able to type free text or filter from the control itself, and for a `searchable` Select when the trigger should stay a button that shows the chosen value.

> **Markup you author.** The input is both the trigger and the search field: Timeless wires `aria-expanded`, `aria-controls`, and `aria-activedescendant` onto it and leaves its editing behavior alone. Filtering sets `hidden` on non-matching options rather than removing them, which is also the extension point — set `filter="off"` and Timeless filters nothing, emits `ui-input` with the query, and lets you set `hidden` yourself. Navigation, the empty state, group collapse, and paging all keep working, because every one of them reads `hidden`.

## Markup

```html
<ui-combobox name="component">
  <label for="component-search">Component</label>
  <input id="component-search" role="combobox" type="text" aria-autocomplete="list" placeholder="Type to filter…">
  <div id="component-search-surface" data-ui-part="surface" popover="manual">
    <div id="component-search-listbox" data-ui-part="listbox" role="listbox" aria-label="Component">
      <div data-ui-part="option" role="option" data-ui-value="draft">Draft</div>
      <div data-ui-part="option" role="option" data-ui-value="ready">Ready</div>
      <div data-ui-part="option" role="option" data-ui-value="published">Published</div>
    </div>
    <p data-ui-part="empty" hidden>No component matches that filter.</p>
  </div>
</ui-combobox>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/combobox.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/combobox.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-combobox'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineComboboxElement } from '@timelessui/components/define/ui-combobox'
defineComboboxElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `input[role='combobox']` | The native text input. It is both the trigger and the search field: Timeless wires `aria-expanded`, `aria-controls`, and `aria-activedescendant` onto it and leaves its editing behavior alone. |
| `surface` | No | `[data-ui-part~='surface']` | The popover the listbox sits in. Author it whenever the surface also holds a `header`, a `footer`, or a pager: a `role="listbox"` may own only options and groups. With none of them, the `listbox` is its own surface and this part is unnecessary. |
| `listbox` | Yes | `[role='listbox']` | The option container. |
| `option` | Yes | `[role='option']` | One option. Its value comes from `value`, then `data-ui-value`, then its text. Mark unavailable options `aria-disabled="true"`. |
| `option-indicator` | No | `[data-ui-part~='option-indicator']` | Decorative affordance inside an option showing that it is selected. Style it from `[aria-selected="true"]`; it is hidden from assistive technology. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related options. Options inside it stay navigable, and the group collapses when every option it holds is filtered out. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator']` | A visual divider between options. Navigation and typeahead skip it. |
| `empty` | No | `[data-ui-part~='empty']` | Shown when no option is visible. Hidden again as soon as one is. |
| `status` | No | `[data-ui-part~='status']` | A `role="status" aria-live="polite"` region for result counts, loading, and errors. |
| `header` | No | `[data-ui-part~='header']` | Optional content at the top of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `footer` | No | `[data-ui-part~='footer']` | Optional content at the bottom of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `pager` | No | `[data-ui-part~='pager']` | Wraps the page controls. Hidden unless `page-size` is set and the options span more than one page. |
| `page-previous` | No | `[data-ui-part~='page-previous']` | Moves to the previous page. Stays focusable at the first page and takes `aria-disabled`, so the boundary is discoverable rather than gone. |
| `page-next` | No | `[data-ui-part~='page-next']` | Moves to the next page, with the same boundary behavior. |
| `page-status` | No | `[data-ui-part~='page-status']` | A `role="status" aria-live="polite"` region announcing the current page. |
| `chips` | No | `[data-ui-part~='chips']` | Container the selected values are rendered into under `multiple`. |
| `chip-template` | No | `template[data-ui-part~='chip-template']` | A `<template>` holding the markup for one chip. Timeless clones it per selected value and fills it in, so every element and class in a chip is yours. Without it a `chips` container receives a plain comma-separated summary instead. |
| `chip` | No | `[data-ui-part~='chip']` | One selected value, authored inside `chip-template`. |
| `chip-label` | No | `[data-ui-part~='chip-label']` | Where the selected label is written inside a chip. Omit it only when the chip has no other content. |
| `chip-remove` | No | `[data-ui-part~='chip-remove']` | Removes its chip. Author it as a real button; Timeless writes the value it removes onto it as `data-ui-value` and gives it an accessible name naming that value, since one shared template cannot. An `aria-label` you author wins. |
| `clear` | No | `[data-ui-part~='clear']` | Empties the whole selection. Marked `aria-disabled="true"` while there is nothing to clear, rather than `disabled`, so activating it cannot disable the control that holds focus. |

These parts also accept per-item input of their own. No stylesheet selects these
attributes — the component reads them.

| Part | Attribute | Description |
| --- | --- | --- |
| `option` | `data-ui-value` | The value this option submits, when its text is not the value. `value` wins over it, and its own text is the fallback. |
| `option` | `data-ui-label` | The text filtering and typeahead match against, when the visible content is not what a reader would type. `label` wins over it, then this, then `aria-label`, then the option text. None of the four change the accessible name. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `value` | any `string` | — | The option selected on load and after a form reset. Once the user commits a change the attribute stops applying, the way it does on a native input. |
| `align` | `start` · `end` | `start` | Which edge of the trigger the surface aligns to. The surface is never narrower than the trigger. |
| `filter` | `contains` · `starts-with` · `off` | `contains` | How typed text narrows the options. `off` hands visibility to you: listen for `ui-input` and set `hidden` yourself, and navigation, the empty state, group collapse, and paging all follow. |
| `multiple` | presence | absent | Present to allow more than one selected option. Selected values render as chips and submit one form entry each under the same `name`. |
| `name` | any `string` | — | Form field name. The element submits its own value through `ElementInternals`. |
| `required` | presence | absent | Present to block submission while nothing is selected, with `valueMissing`. |
| `disabled` | presence | absent | Present to disable the control. A control inside a disabled `<fieldset>` is disabled too, and submits nothing either way. |
| `page-size` | any `number` | — | Options to render per page. Absent means unpaged, which is the default and adds no pager. The resolved number is available on the read-only `pageCount` property. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-combobox>`

| Property | Type | Notes |
| --- | --- | --- |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |
| `align` | `'start' | 'end'` | Reflects the `align` attribute |
| `filter` | `'contains' | 'starts-with' | 'off'` | Reflects the `filter` attribute |
| `multiple` | `boolean` | Reflects the `multiple` attribute |
| `name` | `string` | Reflects the `name` attribute |
| `required` | `boolean` | Reflects the `required` attribute |
| `disabled` | `boolean` | Reflects the `disabled` attribute |
| `pageSize` | `string` | Reflects the `page-size` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<ComboboxChangeDetail>` | Cancelable proposal dispatched before the selected option changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<ComboboxChangeDetail>` | Dispatched after the selected option has changed. Bubbles and is composed. |
| `ui-open` | `CustomEvent<ComboboxToggleDetail>` | Dispatched after the listbox opens. |
| `ui-close` | `CustomEvent<ComboboxToggleDetail>` | Dispatched after the listbox closes. |
| `ui-input` | `CustomEvent<ComboboxInputDetail>` | Dispatched when the query text changes, before options are filtered. Under `filter="off"` this is where you set `hidden` yourself. |
| `ui-page` | `CustomEvent<ComboboxPageDetail>` | Dispatched after the rendered page of a paged list changes. |

## Styling

Root identity: `ui-combobox`.
Required stylesheets: `tokens.css`, `core/combobox.css`, `core/floating.css`, `core/options.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/combobox.css`, `themes/atmosphere/options.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-collection-surface-inline-size` | Minimum width of the listbox surface. The input width wins whenever it is larger. |
| `--ui-floating-offset` | Gap between the input and the surface. |

Design tokens this component reads (34), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow Down / Arrow Up` | Open the listbox, then move the active option. |
| `Home / End` | Move to the first or last matching option. |
| `Arrow Left / Arrow Right` | Move the text caret. They never move the highlight. |
| `Enter` | Commit the active option. |
| `Escape` | Close the listbox, then clear the filter on a second press. |
| `Backspace` | In an empty input under `multiple`, removes the last chip. |

Focus stays in the text input at all times; the active option is exposed with `aria-activedescendant`. Filtering hides non-matching options rather than removing them, so find-in-page and the DOM still show the full authored list. `header`, `footer`, and the pager sit outside arrow navigation and are reached with `Tab`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Context Menu

Open a menu at the pointer, or from the keyboard. (Custom element.)

Reference: https://timeless.build/docs/components/context-menu/

> **Choosing between components.** A context menu is the same surface as [Menu](/docs/components/menu/), opened by a secondary click over a region instead of by a control. Reach for [Menu Button](/docs/components/menu-button/) when the commands should have a visible trigger — a context menu is discoverable only by trying it, so it belongs to shortcuts for things reachable another way.

> **Markup you author.** Never put a command here that is not also reachable elsewhere. Give the `target` a role that supports `aria-haspopup` and an accessible name — in real markup it is usually something that already has both, like a table row or a treeitem — and Timeless adds the tab stop, the relationships, and the `Shift+F10` and Context Menu key routes in.

## Markup

```html
<ui-context-menu>
  <div data-ui-part="target" role="group" aria-label="hero-banner.avif">
    hero-banner.avif
  </div>
  <ui-menu id="asset-context-menu" role="menu" popover="auto" aria-label="Asset commands">
    <button role="menuitem" type="button">Open</button>
    <button role="menuitem" type="button">Rename</button>
    <hr data-ui-part="separator" role="separator">
    <div data-ui-part="group">
      <p data-ui-part="group-label">Share</p>
      <button role="menuitem" type="button">Copy link</button>
      <button role="menuitem" type="button">Invite reviewer</button>
    </div>
  </ui-menu>
</ui-context-menu>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/context-menu.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/menu.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/menu.css'
import '@timelessui/components/css/themes/atmosphere/context-menu.css'
import '@timelessui/components/register/ui-context-menu'
import '@timelessui/components/register/ui-menu'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineContextMenuElement } from '@timelessui/components/define/ui-context-menu'
defineContextMenuElement()
import { defineMenuElement } from '@timelessui/components/define/ui-menu'
defineMenuElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-context-menu>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `target` | Yes | `[data-ui-part~='target']` | The region a secondary click opens the menu over. Give it a role that supports `aria-haspopup` and make it focusable — Timeless adds `tabindex="0"` when it has none, because the keyboard path cannot exist without a tab stop. It then wires `aria-haspopup`, `aria-controls`, and `aria-expanded`; the role and the accessible name stay yours. |
| `menu` | Yes | `ui-menu[popover], [role='menu'][popover]` | The menu surface, a `ui-menu` authored as a popover. Every item, group, separator, and submenu inside it is the [Menu](/docs/components/menu/) contract, unchanged — this element only decides when and where it opens. |

**<ui-menu>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `menu` | Yes | `[role='menu']` | The menu container. Use `role="menubar"` for a persistent horizontal menu bar. |
| `item` | Yes | `[role^='menuitem']` | One command. A menu-item role is what makes an element an item — a bare `<button>` inside the menu is not one. Use `role="menuitem"`, or `menuitemcheckbox` / `menuitemradio` for a checkable command. Timeless manages roving `tabindex`, typeahead, and `aria-checked`. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related items. Items inside it stay navigable, and a `menuitemradio` clears only the radios in its own group. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator'], hr` | A divider between items or groups. Navigation and typeahead skip it, because it carries no menu-item role. |
| `submenu-trigger` | No | `[aria-haspopup='menu']` | An item that owns a submenu. You do not author this token: give the item `aria-controls` naming the submenu, or put the submenu immediately after it, and Timeless writes `aria-haspopup`, `aria-controls`, and `aria-expanded`. |
| `submenu` | No | `ui-menu[popover], [role='menu'][popover]` | A nested menu opened from a `submenu-trigger`. Author it as a popover so it stays hidden before enhancement; Timeless adds `popover="auto"` if you leave it off. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-menu>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `horizontal` · `vertical` | `vertical` | Arrow-key axis. Defaults to `horizontal` when the menu part is `role="menubar"`. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-context-menu>`

This element adds no public properties. Configure it with its attributes.

| Event | Detail | Description |
| --- | --- | --- |
| `ui-open` | `CustomEvent<ContextMenuToggleDetail>` | Dispatched after the context menu opens. |
| `ui-close` | `CustomEvent<ContextMenuToggleDetail>` | Dispatched after the context menu closes. |

### `<ui-menu>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'horizontal' | 'vertical'` | Reflects the `orientation` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<MenuCheckedDetail>` | Cancelable proposal dispatched before a checkable item changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<MenuCheckedDetail>` | Dispatched after a checkable item has changed. Bubbles and is composed. |

## Styling

Root identity: `ui-context-menu`, `ui-menu`.
Required stylesheets: `tokens.css`, `core/context-menu.css`, `core/floating.css`, `core/menu.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/menu.css`, `themes/atmosphere/context-menu.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-context-menu-x` | Horizontal position the surface opens at, written at runtime from the pointer or from the focused element. The stylesheet turns it into a clamped `left`. |
| `--ui-context-menu-y` | Vertical position, the same way. Together these are the whole positioning input: there is no anchor element, because a pointer is not an element. |
| `--ui-context-menu-inset` | Minimum gap kept between the surface and the viewport edge when the coordinates would push it off screen. |
| `--ui-menu-min-inline-size` | Minimum width of the menu surface. |

Design tokens this component reads (32), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

**<ui-context-menu>**

The ARIA Authoring Practices Guide has no pattern for Context Menu. The contract below is a composition of behavior the platform already defines, not ARIA invented to fill the gap.

| Key | Action |
| --- | --- |
| `Shift + F10` | Open the menu for the focused target. Some environments consume the shortcut before the page sees it, which is why the dedicated key below is also supported. |
| `Context Menu key` | Open the menu for the focused target. |
| `Escape` | Close the menu and return focus to the target. Handled by the Popover API and by Menu. |

The APG has no context-menu pattern, so this documents a composition rather than claiming one: a [Menu](/docs/components/menu/) surface, opened by a secondary click or by the keyboard. Everything inside is the menu pattern — roving focus, typeahead, submenu keys, checkable items. Escape, light dismiss, and top-layer stacking come from the Popover API. **This is the one Timeless component with no no-JavaScript fallback**: the platform has no declarative way to open a surface at pointer coordinates, so with scripting off the browser shows its own context menu and the authored `ui-menu` stays hidden. Never put a command here that is not also reachable another way.

**<ui-menu>**

Follows the [Menu and Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus between items along the `orientation` axis. |
| `Home / End` | Move focus to the first or last item. |
| `Enter / Space` | Activate the focused item, or open its submenu. |
| `Arrow Right` | Open the focused item's submenu and focus its first enabled item. Under `dir="rtl"` this is Arrow Left. |
| `Arrow Left` | Close the submenu and return focus to the item that opened it. From a first-level submenu of a menubar, move along the bar instead. Under `dir="rtl"` this is Arrow Right. |
| `Escape` | Close the menu and return focus to whatever opened it. |
| `Printable characters` | Typeahead: jump to the next item whose label starts with what you typed. |

The menu is one tab stop. Mark an unavailable command `aria-disabled="true"` rather than `disabled`: it stays reachable with the arrow keys, which is the APG treatment — a command you cannot use is easier to understand than one that is not there — while never taking the resting tab stop and never activating. An authored `disabled` item is honoured as written and simply skipped, because the platform makes it unfocusable and Timeless does not rewrite your markup. Activating a `menuitemcheckbox` toggles its `aria-checked`; activating a `menuitemradio` sets it and clears the other radios in its group. Both dispatch a cancelable `ui-before-change` first, so a consumer that already owns `aria-checked` can keep owning it. Typeahead matching is locale-aware. Submenus open on the keyboard and on click; there is deliberately no hover-with-intent opening.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Copy Button

Copy a value to the clipboard, and say so. (Custom element.)

Reference: https://timeless.build/docs/components/copy-button/

> **Choosing between components.** Use Copy Button whenever a value on the page is meant to be taken somewhere else — an install command, a token, an id. The alternative is a plain button and a click handler, which is the same three lines every time and usually skips the announcement. For a long or changing value reach for `from` rather than `value`: it is read at activation, so nothing has to be kept in sync and nothing is duplicated into an attribute. For anything a string cannot carry — an image, a blob, `text/html` — answer `ui-before-copy` with `respondWith`, and the confirmation still follows your write.

> **Markup you author.** Give the trigger an `aria-label` and mark the `idle` and `copied` labels `aria-hidden="true"`. A button whose accessible name changes while it holds focus is announced inconsistently across screen readers, so the visible confirmation and the name are deliberately separate. Author the `status` region too: it is where the confirmation is announced, and without it the copy is silent.

## Markup

```html
<code class="ui-code" id="install-command">pnpm add @timelessui/components</code>
<ui-copy-button from="install-command" copied-message="Install command copied">
  <button class="ui-button" data-ui-variant="secondary" data-ui-part="trigger" type="button" aria-label="Copy the install command">
    <span data-ui-part="idle" aria-hidden="true">Copy</span>
    <span data-ui-part="copied" aria-hidden="true">Copied</span>
  </button>
  <span data-ui-part="status" role="status"></span>
</ui-copy-button>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/code.css'
import '@timelessui/components/css/core/copy-button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/code.css'
import '@timelessui/components/css/themes/atmosphere/copy-button.css'
import '@timelessui/components/register/ui-copy-button'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineCopyButtonElement } from '@timelessui/components/define/ui-copy-button'
defineCopyButtonElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that copies. Author it as `<button type="button">` with an accessible name; the name must not change on copy, because a button renamed while it holds focus is announced inconsistently across screen readers. |
| `idle` | No | `[data-ui-part~='idle']` | Shown while nothing has been copied. Decorative — hide it from assistive technology with `aria-hidden="true"`. |
| `copied` | No | `[data-ui-part~='copied']` | Shown briefly after a successful copy. Decorative in the same way, and its text is the default announcement. |
| `status` | No | `[data-ui-part~='status']` | A `role="status"` region the confirmation is written into. Author it — Timeless writes text and never creates the element — and without it nothing is announced. It is clipped away by default, because the visible confirmation is the `copied` part; restyle it if you want it seen. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `value` | any `string` | — | The literal text to copy. Wins over `from` on presence rather than content, the way `value` does on an option: an explicit `value=""` is the author saying to copy nothing. |
| `from` | any `string` | — | Id of the element to read instead of `value`. An `input`, `textarea`, or `select` gives its current `value`; anything else gives its text. Read at activation rather than cached, so this is the one to reach for when the text is long or changes: it stays current on its own, and nothing is duplicated into an attribute. Assigning the `value` property works too, but a long string then reflects into the DOM. |
| `feedback-duration` | any `number` | `1800` | Milliseconds the `--copied` state persists after a successful copy, and with it the text in the `status` region — the two clear together, so copying the same value twice is announced twice. `0` clears both on the next task, which is short enough that a screen reader may miss the announcement. |
| `copied-message` | any `string` | — | What the `status` region announces after a successful copy. Falls back to the `copied` part’s text, so a button whose confirmation is a word needs no message at all and an icon-only one does. With neither, nothing is announced. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-copy-button>`

| Property | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Reflects the `value` attribute |
| `from` | `string` | Reflects the `from` attribute |
| `feedbackDuration` | `string` | Reflects the `feedback-duration` attribute |
| `copiedMessage` | `string` | Reflects the `copied-message` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-copy` | `CustomEvent<CopyProposalDetail>` | Cancelable proposal dispatched before anything is written, carrying the resolved `value`. Call `preventDefault()` to reject the copy, and no `ui-copy` follows. Or call `detail.respondWith(promise)` to perform the write yourself — which is how you copy an image, a blob, or `text/html`, since `writeText` carries a string and nothing else. The element then awaits your promise and drives `--copied`, the announcement, and `ui-copy` from its outcome, so a confirmation never claims a copy that did not happen. Call it synchronously, and call your own clipboard method synchronously too — the click’s transient user activation is the same one the element depends on. `ClipboardItem` accepts a promised blob, so `new ClipboardItem({ 'image/png': blobPromise })` starts the write immediately while the data resolves. |
| `ui-copy` | `CustomEvent<CopyDetail>` | Dispatched once per activation, on success and on every failure, unless a listener cancelled the proposal. The detail carries `status`, the resolved `value`, and a `reason` naming what went wrong: `empty` when nothing resolved, `unsupported` when there is no Clipboard API, `denied` when the browser refused the write, and `rejected` when a `respondWith` promise failed. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `--copied` | custom-state | Set for `feedback-duration` after a successful copy. Public: style `ui-copy-button:state(--copied)` yourself. |

## Styling

Root identity: `ui-copy-button`.
Required stylesheets: `tokens.css`, `core/button.css`, `core/code.css`, `core/copy-button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/code.css`, `themes/atmosphere/copy-button.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-focus`, `--ui-font-mono`, `--ui-line`, `--ui-radius-control`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-outline-control`, `--ui-space-2`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/) from the ARIA Authoring Practices Guide.

The trigger is a native button, so activation, focus, and the accessible name are the platform’s. Timeless adds only what the platform cannot: the `idle`/`copied` swap is decorative and stays hidden from assistive technology, and the confirmation reaches a screen reader through the authored `status` region rather than by renaming the button. Copying needs `navigator.clipboard`, which is absent outside a secure context; a trigger authored `hidden` is revealed only once the API is there, so a control that cannot work is never shown.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Dialog

Enhance an authored native dialog with focus management. (Custom element.)

Reference: https://timeless.build/docs/components/dialog/

> **Markup you author.** The trigger and the close buttons carry `command` and `commandfor`, so the dialog opens, closes, and reports a `returnValue` before any script runs. Those attributes are yours to write: Timeless reads them and leaves the invocation to the platform, because a generated `commandfor` would only work once the bundle had loaded. Give the `<dialog>` an explicit `id` for them to name — an invoker cannot reference a generated one. Where [Invoker Commands](/docs/reference/browser-support/) are missing, the component falls back to a click listener that does the same work, so the same markup is correct in every browser.

## Markup

```html
<ui-dialog>
  <button class="ui-button" data-ui-part="trigger" type="button" command="show-modal" commandfor="release-dialog">Open dialog</button>
  <dialog id="release-dialog" aria-labelledby="release-dialog-title" aria-describedby="release-dialog-description">
    <header>
      <h2 data-ui-part="title" id="release-dialog-title">Publish release?</h2>
      <p data-ui-part="description" id="release-dialog-description">Confirm the public package.</p>
    </header>
    <section>
      <p>Package checks have passed.</p>
    </section>
    <footer>
      <button class="ui-button" data-ui-variant="secondary" data-ui-part="close" type="button" command="close" commandfor="release-dialog" value="cancel">Cancel</button>
      <button class="ui-button" data-ui-part="close" type="button" command="close" commandfor="release-dialog" value="confirm">Confirm</button>
    </footer>
  </dialog>
</ui-dialog>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/dialog.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/dialog.css'
import '@timelessui/components/register/ui-dialog'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineDialogElement } from '@timelessui/components/define/ui-dialog'
defineDialogElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the dialog. Add `command="show-modal"` and `commandfor` naming the panel id to open it from markup, before any script runs. Timeless reads those attributes and stands down; it never writes them, because a generated attribute would only work once the bundle had loaded. |
| `panel` | Yes | `dialog` | The native `<dialog>` element. Author it, do not generate it. Give it an explicit `id` when a trigger or close button invokes it, since an invoker can only name an id the author wrote. |
| `close` | No | `[data-ui-part~='close']` | Optional explicit close button inside the panel. Add `command="close"` and `commandfor` to close it from markup; the platform then also copies the button `value` into `returnValue`. |
| `title` | No | `[data-ui-part~='title'], header > :where(h1, h2, h3)` | Names the dialog. Timeless points the panel's `aria-labelledby` at it, generating an id only if you left one off. A heading in the panel `<header>` counts without the token. An `aria-labelledby` you author always wins. |
| `description` | No | `[data-ui-part~='description'], header > p` | Supporting line under the title, wired with `aria-describedby` the same way. A `<p>` in the panel `<header>` counts without the token. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `kind` | `dialog` · `alert` | `dialog` | Whether the panel is a regular dialog or an alert dialog. `alert` resolves to `role="alertdialog"`, for a destructive confirmation the user must answer. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-dialog>`

| Property | Type | Notes |
| --- | --- | --- |
| `kind` | `'dialog' | 'alert'` | Reflects the `kind` attribute |

This element dispatches no component events.

## Styling

Root identity: `ui-dialog`.
Required stylesheets: `tokens.css`, `core/dialog.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/dialog.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (30), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the dialog. Handled by the native `<dialog>` element, not by Timeless. |

Focus trapping, the backdrop, and the top layer all come from `showModal()`. Timeless moves initial focus into the panel and returns it to the trigger on close, and names the panel from its `title` and `description` parts. A dialog invoker gets no implicit `aria-expanded` from the platform, so Timeless keeps writing it on both the authored-command and click paths.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Empty

Explain an empty state and offer one clear next action. (CSS only.)

Reference: https://timeless.build/docs/components/empty/

## Markup

```html
<section class="ui-empty" aria-labelledby="empty-projects-title">
  <div data-ui-part="art" aria-hidden="true">◇</div>
  <h2 id="empty-projects-title">No projects yet</h2>
  <p>Create a project to start composing your interface.</p>
  <div data-ui-part="actions">
    <button class="ui-button" data-ui-variant="secondary" type="button">Create project</button>
  </div>
</section>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/empty.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/empty.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `art` | No | `[data-ui-part~='art']` | Decorative illustration or icon. |
| `actions` | No | `[data-ui-part~='actions']` | Container for the one clear next action. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Vertical rhythm of the empty state. |

## Styling

Root identity: `ui-empty`.
Required stylesheets: `tokens.css`, `core/empty.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/empty.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (25), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-radius-control`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-outline-control`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Field

Connect labels, descriptions, errors, and native controls. (CSS only.)

Reference: https://timeless.build/docs/components/field/

> **Markup you author.** One field is one label, one control, and whatever description or error belongs to it. `ui-input` and `ui-textarea` are the same field with a different control — both take `data-ui-size`, and the `<textarea>` keeps its own native resize handle.

## Markup

```html
<div class="ui-field">
  <label class="ui-label" for="email">Email</label>
  <div data-ui-part="control">
    <input class="ui-input" id="email" name="email" type="email" placeholder="you@example.com" aria-describedby="email-description">
    <p class="ui-description" id="email-description">Used for release notifications.</p>
  </div>
</div>
<div class="ui-field">
  <label class="ui-label" for="release-notes">Release notes</label>
  <div data-ui-part="control">
    <textarea class="ui-textarea" id="release-notes" name="notes" placeholder="What changed in this release?" aria-describedby="release-notes-description"></textarea>
    <p class="ui-description" id="release-notes-description">Shown on the release page.</p>
  </div>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

**ui-input**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. |

**ui-textarea**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-field`, `ui-label`, `ui-input`, `ui-textarea`, `ui-description`, `ui-error`.
Required stylesheets: `tokens.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Fieldset

Group unrelated controls under one native legend. (CSS only.)

Reference: https://timeless.build/docs/components/fieldset/

> **Choosing between components.** Use Fieldset to group controls that are not one field — an address block, a billing section. For a set of radios or checkboxes that answer one question, [Checkbox Group](/docs/components/checkbox-group/) and [Radio Group](/docs/components/radio-group/) sit on `.ui-choice-group`, which strips the native chrome because the set reads as a single field.

> **Markup you author.** Keep the `<legend>` the first child: that is what makes the browser treat it as the group name, and no ARIA substitutes for it. Native `disabled` on the `<fieldset>` disables and un-submits everything inside it, including form-associated custom elements, which is why the group needs no disabled attribute of its own.

## Markup

```html
<fieldset class="ui-fieldset" aria-describedby="billing-description">
  <legend>Billing address</legend>
  <p id="billing-description" data-ui-part="description">Used on every invoice for this workspace.</p>
  <div class="ui-field">
  <label class="ui-label" for="billing-street">Street</label>
  <div data-ui-part="control">
    <input class="ui-input" id="billing-street" name="street" type="text" placeholder="12 Copperfield Way">
    
  </div>
</div>
  <div class="ui-field">
  <label class="ui-label" for="billing-city">City</label>
  <div data-ui-part="control">
    <input class="ui-input" id="billing-city" name="city" type="text">
    
  </div>
</div>
  
</fieldset>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**ui-fieldset**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `legend` | Yes | `legend` | The native `<legend>`, which names the group. Keep it the first child, because that is what makes the browser treat it as the group label. |
| `description` | No | `[data-ui-part~='description']` | Group-level help text under the legend. |
| `error` | No | `[data-ui-part~='error']` | Group-level validation message. |

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-fieldset**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between grouped controls, and the padding around them. |

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

**ui-input**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | aria | Set `aria-invalid="true"` on the `<fieldset>` and point `aria-describedby` at the error part. |
| `disabled` | native | Native `disabled` on the `<fieldset>`, which the browser propagates to every control inside it. |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-fieldset`, `ui-field`, `ui-label`, `ui-input`, `ui-description`.
Required stylesheets: `tokens.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# File Input

A native file input with consistent field anatomy. (CSS only.)

Reference: https://timeless.build/docs/components/file-input/

## Markup

```html
<div class="ui-field">
  <label class="ui-label" for="manifest">Component manifest</label>
  <div data-ui-part="control">
    <input class="ui-file" id="manifest" name="manifest" type="file" accept=".json" aria-describedby="manifest-description">
    <p class="ui-description" id="manifest-description">Upload a Custom Elements Manifest.</p>
  </div>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |

## Styling

Root identity: `ui-file`, `ui-field`, `ui-label`, `ui-description`.
Required stylesheets: `tokens.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Form

Put server-side errors back onto the fields they came from. (Custom element.)

Reference: https://timeless.build/docs/components/form/

> **Choosing between components.** Reach for Form only when errors arrive from somewhere the browser cannot see — a server response, an async uniqueness check. Everything a `required`, a `type="email"`, or a `pattern` can decide is already decided by native constraint validation, and adding Form does not change it.

> **Markup you author.** Author an empty `error` part inside each field wrapper. Form resolves it as the single `error` part in the nearest wrapper holding no other named control, which is the shape `.ui-field`, `.ui-choice-group`, and `.ui-fieldset` already produce, then writes the message and points the field’s `aria-describedby` at it. A field with no wrapper gets no error element rather than someone else’s.

## Markup

```html
<ui-form>
  <form class="ui-form-demo-stack" id="workspace-form" action="#workspace" method="post" data-ui-part="form">
    <div class="ui-field">
      <label class="ui-label" for="workspace-slug">Workspace address</label>
      <div data-ui-part="control">
        <input class="ui-input" id="workspace-slug" name="slug" type="text" value="acme" aria-describedby="workspace-slug-description">
        <p class="ui-description" id="workspace-slug-description">Lowercase letters, numbers, and hyphens.</p>
        <p class="ui-error" data-ui-part="error"></p>
      </div>
    </div>
    <div class="ui-field">
      <label class="ui-label" for="workspace-owner">Owner email</label>
      <div data-ui-part="control">
        <input class="ui-input" id="workspace-owner" name="owner" type="email" value="ops@acme.test">
        
        <p class="ui-error" data-ui-part="error"></p>
      </div>
    </div>
    <div class="ui-form-demo-actions">
      <button class="ui-button" data-ui-variant="primary" id="workspace-save" type="button">Save</button>
      <button class="ui-button" data-ui-variant="secondary" id="workspace-clear" type="button">Clear errors</button>
    </div>
  </form>
</ui-form>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/form.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/register/ui-form'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineFormElement } from '@timelessui/components/define/ui-form'
defineFormElement()
```

## Consumer wiring

This example needs the following plain JavaScript beyond custom-element registration.

```js
const form = document.querySelector('ui-form')
if (form) {
  document.getElementById('workspace-save')?.addEventListener('click', () => {
    form.setErrors({
      slug: 'That workspace address is already taken.',
      owner: 'No account exists for this address.',
    })
  })
  document.getElementById('workspace-clear')?.addEventListener('click', () => form.clearErrors())
}
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-form>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `form` | Yes | `form` | The native `<form>`. Submission, `method`, `action`, reset, and constraint validation are all still its job; `ui-form` only writes messages onto the fields inside it. |
| `error` | No | `[data-ui-part~='error']` | The message element for one field, resolved as the single `error` part inside the nearest wrapper that holds no other named control. `.ui-field`, `.ui-choice-group`, and `.ui-fieldset` all produce that shape, so no pairing attribute is needed. `ui-form` writes its text and points the field’s `aria-describedby` at it. |

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

**ui-input**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-form>`

This element adds no public properties. Configure it with its attributes.

| Event | Detail | Description |
| --- | --- | --- |
| `ui-invalid` | `CustomEvent<FormInvalidDetail>` | Dispatched after `setErrors` has put at least one message on a control, naming the fields that matched. Clearing errors dispatches nothing. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-form`, `ui-field`, `ui-label`, `ui-input`, `ui-description`, `ui-error`.
Required stylesheets: `tokens.css`, `core/form.css`, `core/forms.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`, `themes/atmosphere/button.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (39), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-control`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-inset`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

The ARIA Authoring Practices Guide has no pattern for Form errors. The contract below is a composition of behavior the platform already defines, not ARIA invented to fill the gap.

There is no APG pattern for server-side error mapping. `ui-form` sets `aria-invalid` on each field it marks and points `aria-describedby` at the authored error text, then moves focus to the first field that took a message — which is what makes the error reachable rather than merely visible. Everything else, including the native validation bubble, stays with the platform.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Group

Arrange related controls with density and attachment options. (CSS only.)

Reference: https://timeless.build/docs/components/group/

## Markup

```html
<div class="ui-group" data-ui-attached>
  <button class="ui-button" data-ui-variant="secondary" type="button">Day</button>
  <button class="ui-button" data-ui-variant="secondary" type="button">Week</button>
  <button class="ui-button" type="button">Month</button>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/group.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/group.css'
```

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-orientation` | `horizontal` · `vertical` | `horizontal` | Layout direction of the grouped controls. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between grouped controls. |
| `data-ui-wrap` | presence | absent | Present to let the group wrap onto multiple lines. |
| `data-ui-attached` | presence | absent | Present to collapse the gap and join adjacent controls into one segmented control. |

## Styling

Root identity: `ui-group`.
Required stylesheets: `tokens.css`, `core/group.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/group.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (23), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-focus`, `--ui-radius-control`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Hover Card

Open supporting content from pointer or keyboard intent. (Custom element.)

Reference: https://timeless.build/docs/components/hover-card/

> **Choosing between components.** Use Hover Card for a surface holding content worth reading or clicking. For a single short label on hover or focus, [Tooltip](/docs/components/tooltip/) is the same element with `variant="tooltip"` and a box sized for one line.

## Markup

```html
<ui-hover-card>
  <button class="ui-button" data-ui-variant="secondary" data-ui-part="trigger" type="button" aria-controls="hover-reference" aria-expanded="false">Component contract</button>
  <div id="hover-reference" popover="manual" role="group" aria-labelledby="hover-reference-title" aria-describedby="hover-reference-description">
    <h2 id="hover-reference-title">Public contract</h2>
    <p id="hover-reference-description">Stable anatomy, attributes, and events.</p>
  </div>
</ui-hover-card>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
import '@timelessui/components/register/ui-hover-card'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineHoverCardElement } from '@timelessui/components/define/ui-hover-card'
defineHoverCardElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Element that receives hover and focus intent. |
| `content` | Yes | `[popover]` | The surface. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `anchor` | any `string` | — | Id of an element to anchor against instead of the trigger. Use it when the visual anchor differs from the control that opens the card. |
| `variant` | `tooltip` | — | Set `tooltip` for the compact tooltip treatment. Omit for the roomier hover-card surface. |
| `placement` | `bottom` · `top` · `right` · `left` | `bottom` | Preferred side of the anchor. |
| `open-delay` | any `number` | `180` | Milliseconds of hover or focus intent before opening. The resolved number is available on the read-only `openDelay` property. |
| `close-delay` | any `number` | `100` | Milliseconds after the pointer leaves before closing, so the user can cross the gap into the surface. The resolved number is available on the read-only `closeDelay` property. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-hover-card>`

| Property | Type | Notes |
| --- | --- | --- |
| `anchor` | `string` | Reflects the `anchor` attribute |
| `variant` | `'tooltip'` | Reflects the `variant` attribute |
| `placement` | `'bottom' | 'top' | 'right' | 'left'` | Reflects the `placement` attribute |
| `openDelayValue` | `string` | Reflects the `open-delay` attribute |
| `closeDelayValue` | `string` | Reflects the `close-delay` attribute |

This element dispatches no component events.

## Styling

Root identity: `ui-hover-card`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/popover.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/popover.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-floating-offset` | Gap between the anchor and the surface. |

Design tokens this component reads (30), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-shadow-tooltip`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the surface while the trigger has focus. |

The card opens on both pointer hover and keyboard focus, so it is reachable without a mouse, and clicking the trigger toggles it. `close-delay` keeps it open while the pointer crosses the gap into the surface, and focus moving into the surface cancels the close outright — so a link or a button inside it is reachable with `Tab`, not only with a pointer. Under `variant="tooltip"` the click toggle is dropped — a tooltip describes its trigger rather than disclosing a surface — while the gap-crossing behavior stays, because WCAG 2.2 SC 1.4.13 requires it. See [Tooltip](/docs/components/tooltip/). Never put the only copy of important content here.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# List

Structured lists with titles and descriptions. (CSS only.)

Reference: https://timeless.build/docs/components/list/

## Markup

```html
<ul class="ui-list">
  <li data-ui-part="item">
    <span data-ui-part="title">Install package CSS</span>
    <span data-ui-part="description">Import tokens and only the components you use.</span>
  </li>
  <li data-ui-part="item">
    <span data-ui-part="title">Author native markup</span>
    <span data-ui-part="description">Keep behavior available when CSS is absent.</span>
  </li>
  <li data-ui-part="item">
    <span data-ui-part="title">Style public anatomy</span>
    <span data-ui-part="description">Use class hooks and namespaced data attributes.</span>
  </li>
</ul>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/list.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/list.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `item` | No | `[data-ui-part~='item']` | One row. Use `<li>`. |
| `title` | No | `[data-ui-part~='title']` | Primary row text. |
| `description` | No | `[data-ui-part~='description']` | Secondary row text. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `plain` · `divided` · `inset` | `plain` | Row treatment. Numbering is the element's job, not the attribute's: use `<ol class="ui-list">` for a numbered list and `<ul class="ui-list">` for an unnumbered one. |
| `data-ui-density` | `compact` · `normal` | `normal` | Row padding. |

## Styling

Root identity: `ui-list`.
Required stylesheets: `tokens.css`, `core/list.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/list.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-list-gap` | Gap between rows. `divided` collapses it to zero. |
| `--ui-list-item-padding-block` | Block padding of a `divided` row. |
| `--ui-list-item-padding-inline` | Inline padding of a `divided` row. |

Design tokens this component reads (9), global and set at the theme level: `--ui-bg-surface`, `--ui-fg`, `--ui-fg-muted`, `--ui-line`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Listbox

Keyboard selection over authored options. (Custom element.)

Reference: https://timeless.build/docs/components/listbox/

> **Choosing between components.** Listbox is the inline core [Select](/docs/components/select/) and [Combobox](/docs/components/combobox/) compose: the same option semantics, selection, groups, typeahead, and paging, without a trigger or a popover. Use it directly when the choices should always be visible, and reach for one of the other two when they should not.

> **Markup you author.** The host carries `role="listbox"` and scrolls its own options. Add an `empty` region, a `status` region, or a pager and those cannot sit inside it — a listbox may own only options and groups — so wrap the options in an inner `listbox` part and let the host be the frame around it.

## Markup

```html
<ui-listbox id="status-list" value="ready" name="status" role="listbox" aria-label="Status">
  <div data-ui-part="option" role="option" data-ui-value="draft">Draft</div>
  <div data-ui-part="option" role="option" data-ui-value="ready">Ready</div>
  <div data-ui-part="option" role="option" data-ui-value="published">Published</div>
</ui-listbox>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/listbox.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/listbox.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-listbox'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineListboxElement } from '@timelessui/components/define/ui-listbox'
defineListboxElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `listbox` | Yes | `[role='listbox']` | The option container, which is the host itself. |
| `option` | Yes | `[role='option']` | One option. Its value comes from `value`, then `data-ui-value`, then its text. Mark unavailable options `aria-disabled="true"`. |
| `option-indicator` | No | `[data-ui-part~='option-indicator']` | Decorative affordance inside an option showing that it is selected. Style it from `[aria-selected="true"]`; it is hidden from assistive technology. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related options. Options inside it stay navigable, and the group collapses when every option it holds is filtered out. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator']` | A visual divider between options. Navigation and typeahead skip it. |
| `empty` | No | `[data-ui-part~='empty']` | Shown when no option is visible. Hidden again as soon as one is. |
| `status` | No | `[data-ui-part~='status']` | A `role="status" aria-live="polite"` region for result counts, loading, and errors. |
| `header` | No | `[data-ui-part~='header']` | Optional content at the top of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `footer` | No | `[data-ui-part~='footer']` | Optional content at the bottom of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `pager` | No | `[data-ui-part~='pager']` | Wraps the page controls. Hidden unless `page-size` is set and the options span more than one page. |
| `page-previous` | No | `[data-ui-part~='page-previous']` | Moves to the previous page. Stays focusable at the first page and takes `aria-disabled`, so the boundary is discoverable rather than gone. |
| `page-next` | No | `[data-ui-part~='page-next']` | Moves to the next page, with the same boundary behavior. |
| `page-status` | No | `[data-ui-part~='page-status']` | A `role="status" aria-live="polite"` region announcing the current page. |

These parts also accept per-item input of their own. No stylesheet selects these
attributes — the component reads them.

| Part | Attribute | Description |
| --- | --- | --- |
| `option` | `data-ui-value` | The value this option submits, when its text is not the value. `value` wins over it, and its own text is the fallback. |
| `option` | `data-ui-label` | The text filtering and typeahead match against, when the visible content is not what a reader would type. `label` wins over it, then this, then `aria-label`, then the option text. None of the four change the accessible name. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `multiple` | presence | absent | Present to allow more than one selected option, submitting one form entry per value under the same `name`. |
| `value` | any `string` | — | The option selected on load and after a form reset. Assign the `value` property for live changes; once the user commits a change the attribute stops applying, the way it does on a native input. |
| `name` | any `string` | — | Form field name. The element submits its own value through `ElementInternals`. |
| `required` | presence | absent | Present to block submission while nothing is selected, with `valueMissing`. |
| `disabled` | presence | absent | Present to disable the control. A control inside a disabled `<fieldset>` is disabled too, and submits nothing either way. |
| `page-size` | any `number` | — | Options to render per page. Absent means unpaged, which is the default and adds no pager. The resolved number is available on the read-only `pageCount` property. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-listbox>`

| Property | Type | Notes |
| --- | --- | --- |
| `multiple` | `boolean` | Reflects the `multiple` attribute |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |
| `name` | `string` | Reflects the `name` attribute |
| `required` | `boolean` | Reflects the `required` attribute |
| `disabled` | `boolean` | Reflects the `disabled` attribute |
| `pageSize` | `string` | Reflects the `page-size` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<ListboxChangeDetail>` | Cancelable proposal dispatched before the selection changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<ListboxChangeDetail>` | Dispatched after the selection has changed. Bubbles and is composed. |
| `ui-page` | `CustomEvent<ListboxPageDetail>` | Dispatched after the rendered page of a paged list changes. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `selected` | aria | `aria-selected="true"` on selected options. |

## Styling

Root identity: `ui-listbox`.
Required stylesheets: `tokens.css`, `core/listbox.css`, `core/options.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/listbox.css`, `themes/atmosphere/options.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-collection-surface-inline-size` | Minimum width of an option surface. On the anchored Select and Combobox surfaces the trigger width wins whenever it is larger. |

Design tokens this component reads (15), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-lg`, `--ui-radius-sm`, `--ui-shadow-floating`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus to the previous or next option, following the orientation and skipping disabled ones. |
| `Home / End` | Move focus to the first or last enabled option. |
| `Enter / Space` | Select the focused option, or toggle it when `multiple` is present. |
| `Printable characters` | Typeahead: jump to the next option whose text starts with what you typed. |

Roving `tabindex` moves real focus between options, so selection follows `aria-selected` and never the focus ring. Options inside a `group` stay in one flat navigation order. `header`, `footer`, and the pager sit outside that order and are reached with `Tab`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Menu

Roving keyboard navigation for commands. (Custom element.)

Reference: https://timeless.build/docs/components/menu/

> **Choosing between components.** A Menu is a set of **commands** — `role="menu"` means roving focus, where the whole set is one Tab stop and the arrow keys move inside it. A site navigation of **links** is not that: links are individually tabbable, and `Tab` is the traversal a reader expects. Timeless ships no navigation-menu element because none is needed; the composition below is the whole recipe. Use [Breadcrumb](/docs/components/breadcrumb/) for where the current page sits in a hierarchy, and [Toolbar](/docs/components/toolbar/) for a row of controls rather than a surface of commands.

> **Markup you author.** Wrap related items in a `group` with a `group-label` and Timeless writes the `role="group"` and the `aria-labelledby` between them. Checkable items need only the role and a starting `aria-checked`: activating a `menuitemcheckbox` toggles it, and activating a `menuitemradio` clears the other radios in its group. Both dispatch a cancelable `ui-before-change` first, so a consumer already writing `aria-checked` from its own state can keep doing exactly that.

## Markup

```html
<ui-menu role="menu" aria-label="Editor commands">
  <button role="menuitem" type="button">Duplicate</button>
  <button role="menuitem" type="button">Archive</button>
  <button role="menuitem" type="button" aria-disabled="true">Delete</button>
  <hr data-ui-part="separator" role="separator">
  <div data-ui-part="group">
    <p data-ui-part="group-label">View</p>
    <button role="menuitemcheckbox" type="button" aria-checked="true">Show grid</button>
    <button role="menuitemcheckbox" type="button" aria-checked="false">Show rulers</button>
  </div>
  <hr data-ui-part="separator" role="separator">
  <div data-ui-part="group">
    <p data-ui-part="group-label">Density</p>
    <button role="menuitemradio" type="button" aria-checked="true">Comfortable</button>
    <button role="menuitemradio" type="button" aria-checked="false">Compact</button>
  </div>
</ui-menu>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/menu.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/menu.css'
import '@timelessui/components/register/ui-menu'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineMenuElement } from '@timelessui/components/define/ui-menu'
defineMenuElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `menu` | Yes | `[role='menu']` | The menu container. Use `role="menubar"` for a persistent horizontal menu bar. |
| `item` | Yes | `[role^='menuitem']` | One command. A menu-item role is what makes an element an item — a bare `<button>` inside the menu is not one. Use `role="menuitem"`, or `menuitemcheckbox` / `menuitemradio` for a checkable command. Timeless manages roving `tabindex`, typeahead, and `aria-checked`. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related items. Items inside it stay navigable, and a `menuitemradio` clears only the radios in its own group. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator'], hr` | A divider between items or groups. Navigation and typeahead skip it, because it carries no menu-item role. |
| `submenu-trigger` | No | `[aria-haspopup='menu']` | An item that owns a submenu. You do not author this token: give the item `aria-controls` naming the submenu, or put the submenu immediately after it, and Timeless writes `aria-haspopup`, `aria-controls`, and `aria-expanded`. |
| `submenu` | No | `ui-menu[popover], [role='menu'][popover]` | A nested menu opened from a `submenu-trigger`. Author it as a popover so it stays hidden before enhancement; Timeless adds `popover="auto"` if you leave it off. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `horizontal` · `vertical` | `vertical` | Arrow-key axis. Defaults to `horizontal` when the menu part is `role="menubar"`. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-menu>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'horizontal' | 'vertical'` | Reflects the `orientation` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<MenuCheckedDetail>` | Cancelable proposal dispatched before a checkable item changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<MenuCheckedDetail>` | Dispatched after a checkable item has changed. Bubbles and is composed. |

## Styling

Root identity: `ui-menu`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/menu.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/menu.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-menu-min-inline-size` | Minimum width of the menu surface. |

Design tokens this component reads (32), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Menu and Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus between items along the `orientation` axis. |
| `Home / End` | Move focus to the first or last item. |
| `Enter / Space` | Activate the focused item, or open its submenu. |
| `Arrow Right` | Open the focused item's submenu and focus its first enabled item. Under `dir="rtl"` this is Arrow Left. |
| `Arrow Left` | Close the submenu and return focus to the item that opened it. From a first-level submenu of a menubar, move along the bar instead. Under `dir="rtl"` this is Arrow Right. |
| `Escape` | Close the menu and return focus to whatever opened it. |
| `Printable characters` | Typeahead: jump to the next item whose label starts with what you typed. |

The menu is one tab stop. Mark an unavailable command `aria-disabled="true"` rather than `disabled`: it stays reachable with the arrow keys, which is the APG treatment — a command you cannot use is easier to understand than one that is not there — while never taking the resting tab stop and never activating. An authored `disabled` item is honoured as written and simply skipped, because the platform makes it unfocusable and Timeless does not rewrite your markup. Activating a `menuitemcheckbox` toggles its `aria-checked`; activating a `menuitemradio` sets it and clears the other radios in its group. Both dispatch a cancelable `ui-before-change` first, so a consumer that already owns `aria-checked` can keep owning it. Typeahead matching is locale-aware. Submenus open on the keyboard and on click; there is deliberately no hover-with-intent opening.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

## Navigation Menu

A bar of links with panels, composed from Hover Card. No navigation-menu element, and no menu role.

```html
<nav aria-label="Main">
  <ul class="ui-group" data-ui-density="compact" data-ui-wrap>
    <li>
      <ui-hover-card open-delay="120" close-delay="100">
        <button class="ui-button" data-ui-variant="ghost" data-ui-part="trigger" type="button" aria-controls="nav-products" aria-expanded="false">Products</button>
        <div id="nav-products" popover="manual" role="group" aria-labelledby="nav-products-title">
          <h2 id="nav-products-title">Products</h2>
          <ul class="ui-list" data-ui-density="compact">
        <li data-ui-part="item"><a class="ui-link" href="/docs/components/">Components</a></li>
        <li data-ui-part="item"><a class="ui-link" href="/docs/styling/theming/">Styling</a></li>
          </ul>
        </div>
      </ui-hover-card>
    </li>
    <li>
      <ui-hover-card open-delay="120" close-delay="100">
        <button class="ui-button" data-ui-variant="ghost" data-ui-part="trigger" type="button" aria-controls="nav-resources" aria-expanded="false">Resources</button>
        <div id="nav-resources" popover="manual" role="group" aria-labelledby="nav-resources-title">
          <h2 id="nav-resources-title">Resources</h2>
          <ul class="ui-list" data-ui-density="compact">
        <li data-ui-part="item"><a class="ui-link" href="/docs/getting-started/installation/">Getting started</a></li>
        <li data-ui-part="item"><a class="ui-link" href="/docs/getting-started/agents/">Coding agents</a></li>
          </ul>
        </div>
      </ui-hover-card>
    </li>
    <li><a class="ui-button" data-ui-variant="ghost" href="/docs/reference/scope/">Scope</a></li>
  </ul>
</nav>
```

---

# Menu Button

Connect a command trigger to a native popover menu. (Custom element.)

Reference: https://timeless.build/docs/components/menu-button/

## Markup

```html
<ui-menu-button>
  <button class="ui-button" data-ui-part="trigger" type="button">Actions</button>
  <ui-menu id="actions" role="menu" popover="auto" aria-label="Actions">
    <button role="menuitem" type="button">Duplicate</button>
    <button role="menuitem" type="button">Archive</button>
  </ui-menu>
</ui-menu-button>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/menu.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/menu.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
import '@timelessui/components/register/ui-menu-button'
import '@timelessui/components/register/ui-menu'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineMenuButtonElement } from '@timelessui/components/define/ui-menu-button'
defineMenuButtonElement()
import { defineMenuElement } from '@timelessui/components/define/ui-menu'
defineMenuElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-menu-button>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the menu. |
| `content` | Yes | `[popover]` | The popover surface holding a `ui-menu`. |

**<ui-menu>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `menu` | Yes | `[role='menu']` | The menu container. Use `role="menubar"` for a persistent horizontal menu bar. |
| `item` | Yes | `[role^='menuitem']` | One command. A menu-item role is what makes an element an item — a bare `<button>` inside the menu is not one. Use `role="menuitem"`, or `menuitemcheckbox` / `menuitemradio` for a checkable command. Timeless manages roving `tabindex`, typeahead, and `aria-checked`. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related items. Items inside it stay navigable, and a `menuitemradio` clears only the radios in its own group. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator'], hr` | A divider between items or groups. Navigation and typeahead skip it, because it carries no menu-item role. |
| `submenu-trigger` | No | `[aria-haspopup='menu']` | An item that owns a submenu. You do not author this token: give the item `aria-controls` naming the submenu, or put the submenu immediately after it, and Timeless writes `aria-haspopup`, `aria-controls`, and `aria-expanded`. |
| `submenu` | No | `ui-menu[popover], [role='menu'][popover]` | A nested menu opened from a `submenu-trigger`. Author it as a popover so it stays hidden before enhancement; Timeless adds `popover="auto"` if you leave it off. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-menu-button>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `open` | presence | absent | Present to render the menu open on load. |
| `placement` | `bottom` · `top` · `right` · `left` | `bottom` | Preferred side of the trigger. |

**<ui-menu>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `horizontal` · `vertical` | `vertical` | Arrow-key axis. Defaults to `horizontal` when the menu part is `role="menubar"`. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-menu-button>`

| Property | Type | Notes |
| --- | --- | --- |
| `open` | `boolean` | Reflects the `open` attribute |
| `placement` | `'bottom' | 'top' | 'right' | 'left'` | Reflects the `placement` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-open` | `CustomEvent<MenuButtonToggleDetail>` | Dispatched after the menu opens. |
| `ui-close` | `CustomEvent<MenuButtonToggleDetail>` | Dispatched after the menu closes. |

### `<ui-menu>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'horizontal' | 'vertical'` | Reflects the `orientation` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<MenuCheckedDetail>` | Cancelable proposal dispatched before a checkable item changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<MenuCheckedDetail>` | Dispatched after a checkable item has changed. Bubbles and is composed. |

## Styling

Root identity: `ui-menu-button`, `ui-menu`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/menu.css`, `core/button.css`, `core/popover.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/menu.css`, `themes/atmosphere/popover.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-floating-offset` | Gap between the trigger and the menu surface. |
| `--ui-menu-min-inline-size` | Minimum width of the menu surface. |

Design tokens this component reads (35), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-shadow-tooltip`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

**<ui-menu-button>**

Follows the [Menu Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow Down` | Open the menu and focus its first item. |
| `Arrow Up` | Open the menu and focus its last item. |
| `Escape` | Close the menu and return focus to the trigger. |

Enter and Space open the menu before any script runs, because the trigger carries `popovertarget` — they are the platform's, which is why they are not listed above. The two arrows have no declarative equivalent, so those are the keys Timeless implements. Escape and outside-click dismissal come from the Popover API. The trigger carries `aria-haspopup="menu"` and `aria-expanded`.

**<ui-menu>**

Follows the [Menu and Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus between items along the `orientation` axis. |
| `Home / End` | Move focus to the first or last item. |
| `Enter / Space` | Activate the focused item, or open its submenu. |
| `Arrow Right` | Open the focused item's submenu and focus its first enabled item. Under `dir="rtl"` this is Arrow Left. |
| `Arrow Left` | Close the submenu and return focus to the item that opened it. From a first-level submenu of a menubar, move along the bar instead. Under `dir="rtl"` this is Arrow Right. |
| `Escape` | Close the menu and return focus to whatever opened it. |
| `Printable characters` | Typeahead: jump to the next item whose label starts with what you typed. |

The menu is one tab stop. Mark an unavailable command `aria-disabled="true"` rather than `disabled`: it stays reachable with the arrow keys, which is the APG treatment — a command you cannot use is easier to understand than one that is not there — while never taking the resting tab stop and never activating. An authored `disabled` item is honoured as written and simply skipped, because the platform makes it unfocusable and Timeless does not rewrite your markup. Activating a `menuitemcheckbox` toggles its `aria-checked`; activating a `menuitemradio` sets it and clears the other radios in its group. Both dispatch a cancelable `ui-before-change` first, so a consumer that already owns `aria-checked` can keep owning it. Typeahead matching is locale-aware. Submenus open on the keyboard and on click; there is deliberately no hover-with-intent opening.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Meter

Display a scalar measurement within a known range. (CSS only.)

Reference: https://timeless.build/docs/components/meter/

## Markup

```html
<div class="ui-meter-field">
  <label for="quality">Release readiness</label>
  <output for="quality">82 of 100</output>
  <meter id="quality" min="0" max="100" value="82" low="40" high="80" optimum="100">82%</meter>
  
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/meter.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/meter.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `hint` | No | `[data-ui-part~='hint']` | Supporting text under the meter. |

## Styling

Root identity: `ui-meter-field`.
Required stylesheets: `tokens.css`, `core/meter.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/meter.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (10), global and set at the theme level: `--ui-bg-control`, `--ui-danger`, `--ui-fg`, `--ui-fg-muted`, `--ui-font-mono`, `--ui-radius-pill`, `--ui-shadow-inset`, `--ui-space-2`, `--ui-success`, `--ui-warning`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Native Select

Style a native select while preserving platform behavior. (CSS only.)

Reference: https://timeless.build/docs/components/native-select/

> **Choosing between components.** Prefer Native Select. It is the platform control, so it needs no JavaScript and behaves correctly on every device. Choose [Select](/docs/components/select/) only when you need option markup the native control cannot render.

## Markup

```html
<div class="ui-field">
  <label class="ui-label" for="channel">Release channel</label>
  <div data-ui-part="control">
    <select class="ui-select" id="channel" name="channel">
      <option value="preview">Preview</option>
      <option value="stable" selected>Stable</option>
    </select>
    
  </div>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-select**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, font size, and the size of the drop-down indicator. |

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |

## Styling

Root identity: `ui-select`, `ui-field`, `ui-label`.
Required stylesheets: `tokens.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-select-indicator` | Width of the drop-down indicator, which also sets the end padding reserved for it. Timeless draws the mark itself with `appearance: none`, because the platform arrow sits at a fixed engine-chosen offset no author padding moves, and WebKit drops `padding` and `min-block-size` on a UA-drawn select entirely. The mark is two gradient halves rather than an icon asset, so it follows `currentColor`; redeclare `background-image` to replace it. The drop-down list itself is still UA-drawn, which is what `color-scheme` on the control is for. |

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Number Stepper

Enhance a native number input with increment controls. (Custom element.)

Reference: https://timeless.build/docs/components/number-stepper/

## Markup

```html
<ui-number-stepper aria-labelledby="quantity-label">
  <label id="quantity-label" for="quantity">Quantity</label>
  <button type="button" data-ui-part="decrement" aria-label="Decrease Quantity">−</button>
  <input id="quantity" type="number" value="2" min="1" max="10">
  <button type="button" data-ui-part="increment" aria-label="Increase Quantity">+</button>
</ui-number-stepper>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/number-stepper.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/number-stepper.css'
import '@timelessui/components/register/ui-number-stepper'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineNumberStepperElement } from '@timelessui/components/define/ui-number-stepper'
defineNumberStepperElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `input` | Yes | `input[type='number']` | The native number input. `min`, `max`, and `step` come from it, and native validation keeps working. |
| `decrement` | Yes | `[data-ui-part~='decrement']` | Button that steps down. Give it an accessible name. |
| `increment` | Yes | `[data-ui-part~='increment']` | Button that steps up. Give it an accessible name. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-number-stepper>`

This element adds no public properties. Configure it with its attributes.

| Event | Detail | Description |
| --- | --- | --- |
| `input` | `Event` | Native `input` event dispatched on the inner number input after each step. |
| `change` | `Event` | Native `change` event dispatched on the inner number input. |

## Styling

Root identity: `ui-number-stepper`.
Required stylesheets: `tokens.css`, `core/number-stepper.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/number-stepper.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (11), global and set at the theme level: `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-disabled-opacity`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-font-mono`, `--ui-line`, `--ui-radius-md`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) from the ARIA Authoring Practices Guide.

Every key comes from the native `input[type="number"]`, which is already a spinbutton: Arrow Up and Arrow Down step by `step`, Page Up and Page Down step further where the platform provides it, and Home and End reach `min` and `max`. Timeless adds no keyboard handling and no ARIA on top, because there is nothing missing — it writes `role="group"` on the host so the two buttons and the field read as one control, which is why the host needs your accessible name. At a bound the corresponding button takes `aria-disabled="true"` rather than `disabled`: a button that goes inert while it is being pressed would otherwise take focus to `<body>` with it, so it stays focusable and does nothing.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# OTP Field

A one-time code across native single-character inputs. (Custom element.)

Reference: https://timeless.build/docs/components/otp-field/

> **Choosing between components.** Without JavaScript the cells are still usable native inputs, but only the enhanced field submits the code, because the joined value belongs to the host. That is the same bar [Select](/docs/components/select/) and [Combobox](/docs/components/combobox/) meet.

> **Markup you author.** Author every cell. `autocomplete="one-time-code"` goes on the first cell only, so the platform offers the SMS code once rather than per cell; every cell needs `maxlength="1"`, `inputmode="numeric"` for the numeric keyboard, and an accessible name naming its position. The cells carry no `name` — the joined code submits under the host `name`.

## Markup

```html
<div class="ui-field">
  <span class="ui-label" id="signin-code-label">Verification code</span>
  <ui-otp-field id="signin-code" name="code" length="6" aria-labelledby="signin-code-label" aria-describedby="signin-code-description">
  <input class="ui-input" data-ui-part="cell" id="signin-code-1" type="text" inputmode="numeric" maxlength="1" autocapitalize="off" autocorrect="off" spellcheck="false" autocomplete="one-time-code" aria-label="Digit 1 of 6" value="">
  <input class="ui-input" data-ui-part="cell" id="signin-code-2" type="text" inputmode="numeric" maxlength="1" autocapitalize="off" autocorrect="off" spellcheck="false" autocomplete="off" aria-label="Digit 2 of 6" value="">
  <input class="ui-input" data-ui-part="cell" id="signin-code-3" type="text" inputmode="numeric" maxlength="1" autocapitalize="off" autocorrect="off" spellcheck="false" autocomplete="off" aria-label="Digit 3 of 6" value="">
  <span data-ui-part="separator" aria-hidden="true">–</span>
  <input class="ui-input" data-ui-part="cell" id="signin-code-4" type="text" inputmode="numeric" maxlength="1" autocapitalize="off" autocorrect="off" spellcheck="false" autocomplete="off" aria-label="Digit 4 of 6" value="">
  <input class="ui-input" data-ui-part="cell" id="signin-code-5" type="text" inputmode="numeric" maxlength="1" autocapitalize="off" autocorrect="off" spellcheck="false" autocomplete="off" aria-label="Digit 5 of 6" value="">
  <input class="ui-input" data-ui-part="cell" id="signin-code-6" type="text" inputmode="numeric" maxlength="1" autocapitalize="off" autocorrect="off" spellcheck="false" autocomplete="off" aria-label="Digit 6 of 6" value="">
  </ui-otp-field>
  <p class="ui-description" id="signin-code-description">Paste the whole code — it spreads across the cells.</p>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/core/otp-field.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/otp-field.css'
import '@timelessui/components/register/ui-otp-field'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineOtpFieldElement } from '@timelessui/components/define/ui-otp-field'
defineOtpFieldElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-otp-field>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `cell` | Yes | `[data-ui-part~='cell']` | One native input holding one character. Author `maxlength="1"`, `inputmode="numeric"`, an accessible name naming its position, and `autocomplete="one-time-code"` on the first cell only. Give it `class="ui-input"` to pick up the shared control styling. |
| `separator` | No | `[data-ui-part~='separator']` | Decorative mark between groups of cells, as in `123-456`. Hide it from assistive technology with `aria-hidden="true"`. |

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-otp-field>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `name` | any `string` | — | Form field name. The joined code submits as one entry through `ElementInternals`; the cells themselves carry no `name`. |
| `length` | any `number` | — | How many characters the code has. Defaults to the number of authored cells, and is what a partly filled field is measured against. |
| `value` | any `string` | — | The code on load and after a form reset. Assign the `value` property for live changes; once the user types, the attribute stops applying, the way it does on a native input. |
| `required` | presence | absent | Present to block submission while the field is empty, with `valueMissing`. |
| `disabled` | presence | absent | Present to disable the field. A field inside a disabled `<fieldset>` is disabled too, and submits nothing either way. |

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

**ui-input**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-otp-field>`

| Property | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Reflects the `name` attribute |
| `length` | `string` | Reflects the `length` attribute |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |
| `required` | `boolean` | Reflects the `required` attribute |
| `disabled` | `boolean` | Reflects the `disabled` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<OtpFieldChangeDetail>` | Cancelable proposal dispatched before the code changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<OtpFieldChangeDetail>` | Dispatched after the code has changed. Bubbles and is composed. |
| `ui-complete` | `CustomEvent<OtpFieldCompleteDetail>` | Dispatched once every character the field expects has been entered, which is where an auto-submit belongs. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-otp-field`, `ui-field`, `ui-label`, `ui-input`, `ui-description`.
Required stylesheets: `tokens.css`, `core/forms.css`, `core/otp-field.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`, `themes/atmosphere/otp-field.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-otp-cell` | Width of one cell. |

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

The ARIA Authoring Practices Guide has no pattern for One-time code. The contract below is a composition of behavior the platform already defines, not ARIA invented to fill the gap.

| Key | Action |
| --- | --- |
| `Printable characters` | Fill the focused cell and move focus to the next one. |
| `Backspace` | Clear the focused cell, or step back and clear the previous one when it is already empty. |
| `Arrow keys` | Move between cells. |
| `Home / End` | Move to the first or last cell. |
| `Paste` | Spread the pasted code across the cells from the focused one onward. |

There is no APG pattern for a one-time-code field, so the contract is a composition of things the platform already defines rather than invented ARIA: a named `role="group"` over native inputs, each independently tabbable and separately labelled by position. No roving `tabindex` is written, because every cell is a real tab stop. Autofill, the numeric keyboard, and paste come from the inputs themselves.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Pagination

Page navigation as real links. CSS only. (CSS only.)

Reference: https://timeless.build/docs/components/pagination/

> **Choosing between components.** This paginates *pages* — one URL each. To page through the options inside a [Listbox](/docs/components/listbox/), [Select](/docs/components/select/), or [Combobox](/docs/components/combobox/), set `page-size` on that element and author its `pager` parts instead; nothing navigates there, so links would be wrong.

> **Markup you author.** Give the `<nav>` an `aria-label`. Author every page but the current one as an `<a href>`, the current one as a `<span aria-current="page">`, and the ellipsis as `aria-hidden="true"`. Previous and Next need accessible names that say what they do, and at the first or last page they become `<span>` elements — an `<a aria-disabled="true">` still navigates, so it is a lie. Compose `<ul class="ui-group" data-ui-attached>` for a joined strip.

## Markup

```html
<nav class="ui-pagination" aria-label="Pagination">
  <ul>
    <li data-ui-part="item"><a data-ui-part="previous" href="?page=3" rel="prev">Previous</a></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=1" aria-label="Page 1">1</a></li>
    <li data-ui-part="item"><span data-ui-part="ellipsis" aria-hidden="true">&hellip;</span></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=3" aria-label="Page 3">3</a></li>
    <li data-ui-part="item"><span data-ui-part="link" aria-current="page">4</span></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=5" aria-label="Page 5">5</a></li>
    <li data-ui-part="item"><span data-ui-part="ellipsis" aria-hidden="true">&hellip;</span></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=12" aria-label="Page 12">12</a></li>
    <li data-ui-part="item"><a data-ui-part="next" href="?page=5" rel="next">Next</a></li>
  </ul>
</nav>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/pagination.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/pagination.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `item` | No | `[data-ui-part~='item']` | One cell wrapper. Use `<li>`. |
| `link` | No | `[data-ui-part~='link']` | A page cell. Use `<a href>` for every page but the one you are on, and a `<span aria-current="page">` for that one. |
| `previous` | No | `[data-ui-part~='previous']` | Steps back one page. Give it an accessible name that says so; `‹` alone names nothing. At the first page, render it as a `<span>` rather than a disabled link. |
| `next` | No | `[data-ui-part~='next']` | Steps forward one page, with the same two rules. |
| `ellipsis` | No | `[data-ui-part~='ellipsis']` | Stands for the pages omitted from a long range. Mark it `aria-hidden="true"`: the gap between page 3 and page 40 is not a page. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Cell height, padding, and font size. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `current` | aria | Author `aria-current="page"` on the cell for the page being shown. Timeless never writes it. |

## Styling

Root identity: `ui-pagination`.
Required stylesheets: `tokens.css`, `core/pagination.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/pagination.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-pagination-gap` | Gap between cells. |
| `--ui-pagination-cell-size` | Minimum height and width of a cell. |

Design tokens this component reads (17), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-surface`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-shadow-control-active`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

The ARIA Authoring Practices Guide has no pattern for Pagination. The contract below is a composition of behavior the platform already defines, not ARIA invented to fill the gap.

The APG has no pagination pattern, so this documents a composition: a `<nav>` with an `aria-label`, a list, and one link per page. They are links rather than buttons on purpose — a page is a URL, so it is shareable, middle-clickable, and in the back button’s history, none of which a click handler gives you. That has one consequence worth stating: **a disabled link is not a thing.** At the first or last page, render Previous or Next as a `<span>`, not an `<a aria-disabled="true">` that still navigates. Compose `<ul class="ui-group" data-ui-attached>` for a joined strip.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Popover

Connect an authored trigger to a native popover. (Custom element.)

Reference: https://timeless.build/docs/components/popover/

> **Choosing between components.** Popover opens from a click and can hold interactive content. For hover or focus intent, use [Hover Card](/docs/components/hover-card/); for a modal that blocks the page, use [Dialog](/docs/components/dialog/).

## Markup

```html
<ui-popover>
  <button class="ui-button" data-ui-part="trigger" type="button" popovertarget="release-popover" aria-controls="release-popover" aria-expanded="false" aria-haspopup="dialog">Release status</button>
  <div id="release-popover" popover="auto" role="dialog" aria-labelledby="release-popover-title" aria-describedby="release-popover-description">
    <h2 id="release-popover-title">Ready to publish</h2>
    <p id="release-popover-description">All required package checks passed.</p>
  </div>
</ui-popover>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
import '@timelessui/components/register/ui-popover'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { definePopoverElement } from '@timelessui/components/define/ui-popover'
definePopoverElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the surface. |
| `content` | Yes | `[popover]` | The surface. Author the `popover` attribute so it stays hidden before enhancement. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `placement` | `bottom` · `top` · `right` · `left` | `bottom` | Preferred side of the trigger. Positioning uses CSS anchor positioning, so the browser may flip the surface to keep it on screen. |
| `role` | `dialog` · `menu` · `listbox` · `tooltip` | `dialog` | Semantics applied to the surface, and the `aria-haspopup` value set on the trigger. Choose it from the interaction, not the appearance. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-popover>`

| Property | Type | Notes |
| --- | --- | --- |
| `placement` | `'bottom' | 'top' | 'right' | 'left'` | Reflects the `placement` attribute |
| `roleValue` | `'dialog' | 'menu' | 'listbox' | 'tooltip'` | Reflects the `role` attribute |

This element dispatches no component events.

## Styling

Root identity: `ui-popover`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/popover.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/popover.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-floating-offset` | Gap between the trigger and the surface. |

Design tokens this component reads (30), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-shadow-tooltip`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the surface. Handled by the Popover API, not by Timeless. |

Light dismiss, Escape, and top-layer stacking come from the Popover API. Timeless wires `popovertarget`, `aria-controls`, `aria-expanded`, and `aria-haspopup`, and gives the surface the `role` you asked for. Name the surface yourself when it is a dialog.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Progress

Expose determinate or indeterminate task progress. (CSS only.)

Reference: https://timeless.build/docs/components/progress/

## Markup

```html
<div class="ui-progress">
  <div data-ui-part="header">
    <label for="progress-documentation-build">Documentation build</label>
    <output for="progress-documentation-build" data-ui-part="output">68%</output>
  </div>
  <progress id="progress-documentation-build" max="100" value="68" aria-describedby="progress-documentation-build-hint"></progress>
  <p id="progress-documentation-build-hint" data-ui-part="hint">Generating component references.</p>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/progress.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/progress.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `header` | No | `[data-ui-part~='header']` | Row holding the label and output. |
| `output` | No | `[data-ui-part~='output']` | Live percentage or count. Use `<output>`. |
| `hint` | No | `[data-ui-part~='hint']` | Supporting text under the track. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Track thickness and label size. |
| `data-ui-density` | `compact` · `normal` | `normal` | Internal spacing. |

## Styling

Root identity: `ui-progress`.
Required stylesheets: `tokens.css`, `core/progress.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/progress.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (9), global and set at the theme level: `--ui-accent`, `--ui-bg-control-muted`, `--ui-fg`, `--ui-fg-muted`, `--ui-line`, `--ui-radius-pill`, `--ui-space-1`, `--ui-space-2`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Radio Group

Coordinate a roving native radio group. (Custom element.)

Reference: https://timeless.build/docs/components/radio-group/

> **Choosing between components.** One component, two levels of behavior. `<ui-radio-group>` adds roving focus and a single change event over the group; the plain `<fieldset class="ui-choice-group">` below it is the same markup with no custom element, and native radios already give it arrow-key selection and one-of-many semantics. The element is an addition, not a replacement, so it is never a choice between a CSS version and a JavaScript version.

## Markup

```html
<ui-radio-group value="system" aria-labelledby="theme-label">
  <span id="theme-label">Theme</span>
  <label class="ui-choice">
  <input class="ui-radio" type="radio" name="theme" value="system" checked>
  <span data-ui-part="body">System</span>
</label>
  <label class="ui-choice">
  <input class="ui-radio" type="radio" name="theme" value="light">
  <span data-ui-part="body">Light</span>
</label>
  <label class="ui-choice">
  <input class="ui-radio" type="radio" name="theme" value="dark">
  <span data-ui-part="body">Dark</span>
</label>
</ui-radio-group>
<fieldset class="ui-choice-group">
  <legend class="ui-label">Deploy target</legend>
  
  <label class="ui-choice" for="deploy-target-preview">
    <input class="ui-radio" id="deploy-target-preview" name="deploy-target" type="radio" value="preview" checked>
    <span data-ui-part="body">
      <span data-ui-part="title">Preview</span>
      
    </span>
  </label>
  <label class="ui-choice" for="deploy-target-production">
    <input class="ui-radio" id="deploy-target-production" name="deploy-target" type="radio" value="production">
    <span data-ui-part="body">
      <span data-ui-part="title">Production</span>
      
    </span>
  </label>
  
</fieldset>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/choice-groups.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/choice-groups.css'
import '@timelessui/components/register/ui-radio-group'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineRadioGroupElement } from '@timelessui/components/define/ui-radio-group'
defineRadioGroupElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-radio-group>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `choice` | Yes | `input[type='radio']` | One native radio input, sharing a `name` with the rest. Native form submission and reset keep working. |

**ui-choice-group**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `description` | No | `[data-ui-part~='description']` | Group-level help text under the legend. |
| `error` | No | `[data-ui-part~='error']` | Group-level validation message. |

**ui-choice**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `body` | No | `[data-ui-part~='body']` | Wrapper for the title and description beside the control. |
| `title` | No | `[data-ui-part~='title']` | The choice label text. |
| `description` | No | `[data-ui-part~='description']` | Supporting copy under the choice label. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-radio-group>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `vertical` · `horizontal` | `vertical` | Layout and arrow-key axis. |
| `value` | any `string` | — | The radio checked on load and after a form reset. Match one input’s `value`. Assign the `value` property for live changes. |

**ui-choice-group**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-orientation` | `vertical` · `horizontal` | `vertical` | Layout direction of the choices. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between choices. |

**ui-choice**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between the control and its label. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-radio-group>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'vertical' | 'horizontal'` | Reflects the `orientation` attribute |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<RadioGroupChangeDetail>` | Cancelable proposal dispatched before the checked radio changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<RadioGroupChangeDetail>` | Dispatched after the checked radio has changed. Bubbles and is composed. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | aria | Set `aria-invalid="true"` on the `<fieldset>` and describe the error. |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-radio-group`, `ui-choice-group`, `ui-choice`, `ui-radio`.
Required stylesheets: `tokens.css`, `core/choice-groups.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`, `themes/atmosphere/choice-groups.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus to the previous or next radio, following the orientation and skipping disabled ones. |
| `Home / End` | Move focus to the first or last enabled radio. |

Native radio semantics do the rest: one tab stop per group, checked state, form submission, and reset. Timeless adds roving focus and change events without replacing the inputs.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Range

A readable native range control with an output. (CSS only.)

Reference: https://timeless.build/docs/components/range/

## Markup

```html
<div class="ui-range">
  <label for="density">Density</label>
  <output for="density">60</output>
  <input id="density" name="density" type="range" min="0" max="100" value="60">
  
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/range.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/range.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `hint` | No | `[data-ui-part~='hint']` | Supporting text or the live `<output>` value. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Track thickness, thumb diameter, and label size. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-range`.
Required stylesheets: `tokens.css`, `core/range.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/range.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-range-track` | Track thickness. |
| `--ui-range-thumb` | Thumb diameter. |

Design tokens this component reads (8), global and set at the theme level: `--ui-bg-surface`, `--ui-fg`, `--ui-fg-muted`, `--ui-font-mono`, `--ui-line-strong`, `--ui-radius-pill`, `--ui-shadow-control`, `--ui-space-2`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Range Field

Two native thumbs on one track, kept in order. (Custom element.)

Reference: https://timeless.build/docs/components/range-field/

> **Choosing between components.** Use Range Field when the value is a span. For a single value, [Range](/docs/components/range/) is CSS over one native input and needs no JavaScript at all.

> **Markup you author.** Both thumbs are native range inputs with their own `name`, so the pair submits as two entries and resets natively with scripting off. Give each one its own accessible name saying which end it is; nothing else can tell them apart in a screen reader.

## Markup

```html
<div class="ui-field">
  <span class="ui-label" id="budget-label">Monthly budget</span>
  <ui-range-field id="budget" aria-labelledby="budget-label">
    <span data-ui-part="track">
      <input data-ui-part="from" type="range" name="budget-from" value="120" min="0" max="500" step="10" aria-label="Monthly budget, lower bound" aria-describedby="budget-description">
      <input data-ui-part="to" type="range" name="budget-to" value="380" min="0" max="500" step="10" aria-label="Monthly budget, upper bound" aria-describedby="budget-description">
    </span>
    <output data-ui-part="output">120 – 380</output>
  </ui-range-field>
  <p class="ui-description" id="budget-description">A thumb stops at its neighbour rather than swapping with it.</p>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/core/range-field.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
import '@timelessui/components/css/themes/atmosphere/range-field.css'
import '@timelessui/components/register/ui-range-field'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineRangeFieldElement } from '@timelessui/components/define/ui-range-field'
defineRangeFieldElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-range-field>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `track` | Yes | `[data-ui-part~='track']` | Wrapper around the two thumbs. It is the shared track: both inputs stack inside it, and the fill between them is drawn on it from measured bounds. |
| `from` | Yes | `input[type='range']` | The lower thumb, a native range input. Give it its own `name`, `min`, `max`, `step`, and accessible name; it submits and resets on its own, with no JavaScript. |
| `to` | Yes | `input[type='range']` | The upper thumb. Same contract as `from`, with its own `name` so the pair submits as two entries. |
| `output` | No | `[data-ui-part~='output']` | Live readout of the pair. Timeless writes the current values into it as text, so omit the part when you want to format them yourself. |

**ui-field**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `control` | No | `[data-ui-part~='control']` | Wrapper around the native control when one is needed. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-field**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-layout` | `stacked` · `inline` | `stacked` | Whether the label sits above the control or beside it. |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between label, control, description, and error. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-range-field>`

This element adds no public properties. Configure it with its attributes.

| Event | Detail | Description |
| --- | --- | --- |
| `ui-change` | `CustomEvent<RangeFieldChangeDetail>` | Dispatched after either thumb moves, carrying the clamped pair and which thumb moved. Bubbles and is composed. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `disabled` | native | Native `disabled` on either thumb. |
| `invalid` | aria | Set `aria-invalid="true"` on the control and point `aria-describedby` at the error part. |

## Styling

Root identity: `ui-range-field`, `ui-field`, `ui-label`, `ui-description`.
Required stylesheets: `tokens.css`, `core/forms.css`, `core/range-field.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`, `themes/atmosphere/range-field.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-range-track` | Track thickness. |
| `--ui-range-thumb` | Thumb diameter. |
| `--ui-range-fill` | Colour of the filled span between the two thumbs. |

Design tokens this component reads (27), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-font-mono`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Slider (Multi-Thumb) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys, Home / End, Page Up / Page Down` | Move the focused thumb. Handled by the native range input, not by Timeless. |

Each thumb is a native `input[type=range]` and therefore its own tab stop, with its own accessible name and its own value announcement. Timeless only keeps the pair ordered: a thumb stops at its neighbour rather than swapping with it, so the key you are holding never starts moving the other thumb.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Select

Enhance authored trigger, value, and listbox anatomy. (Custom element.)

Reference: https://timeless.build/docs/components/select/

> **Choosing between components.** Select and [Combobox](/docs/components/combobox/) are the same ARIA pattern over the same option core; they differ only in where you type. A Select types into a `search` field inside its surface, or not at all; a Combobox types into the trigger and accepts free text. Both replace the native control and cost JavaScript, so if plain text options are enough, [Native Select](/docs/components/native-select/) is still the better default.

> **Markup you author.** The trigger carries `popovertarget` naming the surface, so it opens, light-dismisses, and closes on Escape before any script loads. Give the surface an explicit `id` for it to name. Focus stays on the trigger and the active option travels through `aria-activedescendant`; add `searchable` to move that focus into a `search` field inside the surface instead. A surface that holds a search field, a header, a footer, or a pager needs a `surface` part around the `listbox`, because a `role="listbox"` may own only options and groups.

## Markup

```html
<ui-select value="ready" name="status">
  <label id="release-status-label">Release status</label>
  <button class="ui-button" data-ui-part="trigger" type="button" popovertarget="release-status-listbox" aria-labelledby="release-status-label release-status-value">
    <span data-ui-part="value" id="release-status-value">Ready</span>
  </button>
  <div id="release-status-listbox" data-ui-part="listbox" role="listbox" popover="auto" aria-label="Release status">
    <div data-ui-part="option" role="option" data-ui-value="draft">Draft</div>
    <div data-ui-part="option" role="option" data-ui-value="ready">Ready</div>
    <div data-ui-part="option" role="option" data-ui-value="published">Published</div>
  </div>
</ui-select>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/core/select.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/select.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-select'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineSelectElement } from '@timelessui/components/define/ui-select'
defineSelectElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the listbox. Timeless gives it `role="combobox"`, which the Select-Only Combobox pattern asks for; that role takes no name from its content, so give the trigger `aria-labelledby` or `aria-label` yourself. |
| `value` | No | `[data-ui-part~='value']` | Element inside the trigger that shows the selected label. Timeless writes its text and nothing else. |
| `search` | No | `[data-ui-part~='search']` | Text field inside the surface that filters the options under `searchable`. Left and Right move the caret rather than the highlight. |
| `surface` | No | `[data-ui-part~='surface']` | The popover the listbox sits in. Author it whenever the surface also holds a `search` field, a `header`, a `footer`, or a pager: a `role="listbox"` may own only options and groups, so those siblings belong beside the listbox rather than inside it. With none of them, the `listbox` is its own surface and this part is unnecessary. |
| `listbox` | Yes | `[role='listbox']` | The option container. |
| `option` | Yes | `[role='option']` | One option. Its value comes from `value`, then `data-ui-value`, then its text. Mark unavailable options `aria-disabled="true"`. |
| `option-indicator` | No | `[data-ui-part~='option-indicator']` | Decorative affordance inside an option showing that it is selected. Style it from `[aria-selected="true"]`; it is hidden from assistive technology. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related options. Options inside it stay navigable, and the group collapses when every option it holds is filtered out. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator']` | A visual divider between options. Navigation and typeahead skip it. |
| `empty` | No | `[data-ui-part~='empty']` | Shown when no option is visible. Hidden again as soon as one is. |
| `status` | No | `[data-ui-part~='status']` | A `role="status" aria-live="polite"` region for result counts, loading, and errors. |
| `header` | No | `[data-ui-part~='header']` | Optional content at the top of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `footer` | No | `[data-ui-part~='footer']` | Optional content at the bottom of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `pager` | No | `[data-ui-part~='pager']` | Wraps the page controls. Hidden unless `page-size` is set and the options span more than one page. |
| `page-previous` | No | `[data-ui-part~='page-previous']` | Moves to the previous page. Stays focusable at the first page and takes `aria-disabled`, so the boundary is discoverable rather than gone. |
| `page-next` | No | `[data-ui-part~='page-next']` | Moves to the next page, with the same boundary behavior. |
| `page-status` | No | `[data-ui-part~='page-status']` | A `role="status" aria-live="polite"` region announcing the current page. |
| `chips` | No | `[data-ui-part~='chips']` | Container the selected values are rendered into under `multiple`. |
| `chip-template` | No | `template[data-ui-part~='chip-template']` | A `<template>` holding the markup for one chip. Timeless clones it per selected value and fills it in, so every element and class in a chip is yours. Without it a `chips` container receives a plain comma-separated summary instead. |
| `chip` | No | `[data-ui-part~='chip']` | One selected value, authored inside `chip-template`. |
| `chip-label` | No | `[data-ui-part~='chip-label']` | Where the selected label is written inside a chip. Omit it only when the chip has no other content. |
| `chip-remove` | No | `[data-ui-part~='chip-remove']` | Removes its chip. Author it as a real button; Timeless writes the value it removes onto it as `data-ui-value` and gives it an accessible name naming that value, since one shared template cannot. An `aria-label` you author wins. |
| `clear` | No | `[data-ui-part~='clear']` | Empties the whole selection. Marked `aria-disabled="true"` while there is nothing to clear, rather than `disabled`, so activating it cannot disable the control that holds focus. |

These parts also accept per-item input of their own. No stylesheet selects these
attributes — the component reads them.

| Part | Attribute | Description |
| --- | --- | --- |
| `option` | `data-ui-value` | The value this option submits, when its text is not the value. `value` wins over it, and its own text is the fallback. |
| `option` | `data-ui-label` | The text filtering and typeahead match against, when the visible content is not what a reader would type. `label` wins over it, then this, then `aria-label`, then the option text. None of the four change the accessible name. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `open` | presence | absent | Present to render the listbox open on load. |
| `placement` | `bottom` · `top` · `right` · `left` | `bottom` | Preferred side of the trigger for the listbox surface. |
| `searchable` | presence | absent | Present to filter from a `search` field inside the surface. Focus moves into that field on open and stays there; the highlight travels through `aria-activedescendant`. |
| `value` | any `string` | — | The option selected on load and after a form reset. Once the user commits a change the attribute stops applying, the way it does on a native input. |
| `align` | `start` · `end` | `start` | Which edge of the trigger the surface aligns to. The surface is never narrower than the trigger. |
| `filter` | `contains` · `starts-with` · `off` | `contains` | How typed text narrows the options. `off` hands visibility to you: listen for `ui-input` and set `hidden` yourself, and navigation, the empty state, group collapse, and paging all follow. |
| `multiple` | presence | absent | Present to allow more than one selected option. Selected values render as chips and submit one form entry each under the same `name`. |
| `name` | any `string` | — | Form field name. The element submits its own value through `ElementInternals`. |
| `required` | presence | absent | Present to block submission while nothing is selected, with `valueMissing`. |
| `disabled` | presence | absent | Present to disable the control. A control inside a disabled `<fieldset>` is disabled too, and submits nothing either way. |
| `page-size` | any `number` | — | Options to render per page. Absent means unpaged, which is the default and adds no pager. The resolved number is available on the read-only `pageCount` property. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-select>`

| Property | Type | Notes |
| --- | --- | --- |
| `open` | `boolean` | Reflects the `open` attribute |
| `placement` | `'bottom' | 'top' | 'right' | 'left'` | Reflects the `placement` attribute |
| `searchable` | `boolean` | Reflects the `searchable` attribute |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |
| `align` | `'start' | 'end'` | Reflects the `align` attribute |
| `filter` | `'contains' | 'starts-with' | 'off'` | Reflects the `filter` attribute |
| `multiple` | `boolean` | Reflects the `multiple` attribute |
| `name` | `string` | Reflects the `name` attribute |
| `required` | `boolean` | Reflects the `required` attribute |
| `disabled` | `boolean` | Reflects the `disabled` attribute |
| `pageSize` | `string` | Reflects the `page-size` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<SelectChangeDetail>` | Cancelable proposal dispatched before the selected option changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<SelectChangeDetail>` | Dispatched after the selected option has changed. Bubbles and is composed. |
| `ui-open` | `CustomEvent<SelectToggleDetail>` | Dispatched after the listbox opens. |
| `ui-close` | `CustomEvent<SelectToggleDetail>` | Dispatched after the listbox closes. |
| `ui-input` | `CustomEvent<SelectInputDetail>` | Dispatched when the query text changes, before options are filtered. Under `filter="off"` this is where you set `hidden` yourself. |
| `ui-page` | `CustomEvent<SelectPageDetail>` | Dispatched after the rendered page of a paged list changes. |

## Styling

Root identity: `ui-select`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/options.css`, `core/select.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/select.css`, `themes/atmosphere/options.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-collection-surface-inline-size` | Minimum width of the listbox surface. The trigger width wins whenever it is larger. |
| `--ui-floating-offset` | Gap between the trigger and the surface. |

Design tokens this component reads (32), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Select-Only Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Enter / Space` | Open the listbox, or commit the active option when it is already open. |
| `Arrow keys` | Open the listbox from the closed trigger, or move the active option when it is already open. |
| `Home / End` | Move to the first or last option while the listbox is open. |
| `Escape` | Close the listbox without changing the value. |
| `Printable characters` | Typeahead over the option labels. On a closed Select this selects a match without opening, as the native control does. |
| `Backspace` | In an empty `search` field under `multiple`, removes the last chip. |

Timeless gives the trigger `role="combobox"`, which is what the Select-Only Combobox pattern asks for and what makes `aria-activedescendant` legal on it. Your own `role` wins over that, and the relationship follows the role: set one that cannot carry `aria-activedescendant`, such as `button`, and Timeless writes no relationship rather than an invalid one, while the active option is still highlighted — `checkMarkup` reports the role, because the degradation is otherwise silent. That role does not take its name from its content, so the trigger needs your `aria-labelledby` or `aria-label`; `checkMarkup` reports it when missing. Focus stays on the trigger and the active option is announced through `aria-activedescendant`; under `searchable` focus moves into the `search` field instead and the same mechanism carries the highlight. The trigger carries `popovertarget`, so it opens the surface before any script runs. Light dismiss and Escape come from the Popover API. `header`, `footer`, and the pager sit outside arrow navigation and are reached with `Tab`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Separator

Separate related regions with native semantics. (CSS only.)

Reference: https://timeless.build/docs/components/separator/

## Markup

```html
<hr class="ui-separator">
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/separator.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/separator.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `label` | No | `[data-ui-part~='label']` | Optional inline label rendered over the rule. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-orientation` | `horizontal` · `vertical` | `horizontal` | Rule direction. Also set `aria-orientation="vertical"` on an `<hr>` when you change this. |
| `data-ui-variant` | `default` · `strong` · `centered` | `default` | Line weight and label placement. `centered` positions the label part in the middle of the rule. |

## Styling

Root identity: `ui-separator`.
Required stylesheets: `tokens.css`, `core/separator.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/separator.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (7), global and set at the theme level: `--ui-fg-muted`, `--ui-line`, `--ui-line-strong`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Sheet

Present an authored native dialog from a viewport edge. (Custom element.)

Reference: https://timeless.build/docs/components/sheet/

> **Markup you author.** A `modal` sheet opens from markup: put `command="show-modal"` and `commandfor` on the trigger, naming the explicit `id` you gave the `<dialog>`. A non-modal sheet cannot, because the platform has no built-in command for `dialog.show()`, so leave `command` off that trigger and the click listener opens it. Close buttons take `command="close"` on either kind, and the platform copies the button `value` into `returnValue`. Timeless reads these attributes and never writes them, so a modal sheet still opens with JavaScript disabled.

## Markup

```html
<ui-sheet modal>
  <button class="ui-button" data-ui-part="trigger" type="button" command="show-modal" commandfor="settings-sheet">Open sheet</button>
  <dialog id="settings-sheet" aria-labelledby="settings-sheet-title" aria-describedby="settings-sheet-description">
  <div data-ui-part="drag-handle" aria-hidden="true"></div>
    <header>
      <h2 data-ui-part="title" id="settings-sheet-title">Settings</h2>
      <button class="ui-button" data-ui-variant="ghost" data-ui-size="sm" data-ui-part="close" type="button" aria-label="Close sheet" command="close" commandfor="settings-sheet">
        <svg aria-hidden="true" focusable="false" viewBox="0 0 16 16">
      <path d="m4.5 4.5 7 7m0-7-7 7" fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="1"/>
    </svg>
      </button>
      <p data-ui-part="description" id="settings-sheet-description">Configure this preview.</p>
    </header>
    <section>
      <p>Changes apply immediately.</p>
    </section>
    <footer>
      <button class="ui-button" data-ui-variant="secondary" data-ui-part="close" type="button" command="close" commandfor="settings-sheet" value="cancel">Cancel</button>
      <button class="ui-button" data-ui-part="close" type="button" command="close" commandfor="settings-sheet" value="done">Done</button>
    </footer>
  </dialog>
</ui-sheet>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/sheet.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/dialog.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/sheet.css'
import '@timelessui/components/css/themes/atmosphere/dialog.css'
import '@timelessui/components/register/ui-sheet'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineSheetElement } from '@timelessui/components/define/ui-sheet'
defineSheetElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the sheet. On a `modal` sheet, add `command="show-modal"` and `commandfor` naming the panel id to open it from markup, before any script runs. A non-modal sheet has no declarative equivalent: the platform has no built-in command for `dialog.show()`, so its trigger stays on the click listener. |
| `panel` | Yes | `dialog` | The native `<dialog>` element. Give it an explicit `id` when a trigger or close button invokes it, since an invoker can only name an id the author wrote. |
| `close` | No | `[data-ui-part~='close']` | Optional explicit close button. Add `command="close"` and `commandfor` to close it from markup, on modal and non-modal sheets alike; the platform then also copies the button `value` into `returnValue`. |
| `drag-handle` | No | `[data-ui-part~='drag-handle']` | Optional grab area for the swipe gesture. A swipe works anywhere on the panel that is not a scrollable region, so this is an affordance rather than a requirement — but it is the one place a drag always starts, which is what a bottom sheet over a scrolling body needs. Decorative: hide it from assistive technology and keep a real close control. |
| `title` | No | `[data-ui-part~='title'], header > :where(h1, h2, h3)` | Names the sheet. Timeless points the panel's `aria-labelledby` at it, generating an id only if you left one off. A heading in the panel `<header>` counts without the token. An `aria-labelledby` you author always wins. |
| `description` | No | `[data-ui-part~='description'], header > p` | Supporting line under the title, wired with `aria-describedby` the same way. A `<p>` in the panel `<header>` counts without the token. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `modal` | presence | absent | Present to open the sheet as a modal, trapping focus and blocking the page behind it. Omit for a non-modal sheet the user can interact around. |
| `open` | presence | absent | Present to render the sheet open on load. |
| `position` | `top` · `right` · `bottom` · `left` | `right` | Which viewport edge the sheet slides in from. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-sheet>`

| Property | Type | Notes |
| --- | --- | --- |
| `modal` | `boolean` | Reflects the `modal` attribute |
| `open` | `boolean` | Reflects the `open` attribute |
| `position` | `'top' | 'right' | 'bottom' | 'left'` | Reflects the `position` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-open` | `CustomEvent<SheetEventDetail>` | Dispatched after the sheet opens. |
| `ui-close` | `CustomEvent<SheetEventDetail>` | Dispatched after the sheet closes. |
| `ui-dismiss` | `CustomEvent<SheetEventDetail>` | Dispatched when the sheet closes through Escape, a backdrop click, or a swipe past the dismiss threshold, rather than through an explicit control. The detail names which. A swipe reports `swipe` and behaves exactly like a backdrop click, because that is what it is: a pointer gesture on the overlay rather than a command. |

## Styling

Root identity: `ui-sheet`.
Required stylesheets: `tokens.css`, `core/sheet.css`, `core/button.css`, `core/dialog.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/sheet.css`, `themes/atmosphere/dialog.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-sheet-drag-offset` | How far the panel has been dragged along its own axis, written as a length while a swipe is in progress and cleared on release. The stylesheet turns it into a `translate`; setting it yourself only moves the panel. |

Design tokens this component reads (31), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-pill`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the sheet. Handled by the native `<dialog>` element. |

A `modal` sheet traps focus through `showModal()`; without `modal` the page stays interactive and focus is not trapped. Timeless restores focus to the trigger either way, including after a swipe. Naming comes from the `title` and `description` parts. Swipe-to-dismiss is an addition, never the only way out: Escape and a close control both stay, so the sheet is fully operable without a pointer.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Skeleton

Reserve stable space while content loads. (CSS only.)

Reference: https://timeless.build/docs/components/skeleton/

## Markup

```html
<span class="ui-skeleton" data-ui-width="medium" aria-hidden="true"></span>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/skeleton.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/skeleton.css'
```

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Line height for the `text` shape, diameter for `circle`. |
| `data-ui-shape` | `text` · `circle` · `media` | `text` | Placeholder geometry. |
| `data-ui-width` | `full` · `medium` · `short` | `full` | Inline size, so a group of lines can look like real text. |

## Styling

Root identity: `ui-skeleton`.
Required stylesheets: `tokens.css`, `core/skeleton.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/skeleton.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (6), global and set at the theme level: `--ui-bg-surface-raised`, `--ui-ease-standard`, `--ui-fg`, `--ui-radius-lg`, `--ui-radius-pill`, `--ui-radius-sm`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Spinner

Indicate a short operation without changing layout. (CSS only.)

Reference: https://timeless.build/docs/components/spinner/

## Markup

```html
<span class="ui-spinner" role="status">
  <span data-ui-part="label">Loading preview</span>
</span>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/spinner.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/spinner.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `label` | No | `[data-ui-part~='label']` | Visible or screen-reader-only description of the wait. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Spinner diameter. |
| `data-ui-variant` | `neutral` · `accent` · `success` · `warning` · `danger` | `neutral` | Indicator color. |

## Styling

Root identity: `ui-spinner`.
Required stylesheets: `tokens.css`, `core/spinner.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/spinner.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (8), global and set at the theme level: `--ui-accent`, `--ui-danger`, `--ui-fg`, `--ui-fg-muted`, `--ui-radius-pill`, `--ui-space-2`, `--ui-success`, `--ui-warning`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Switch

A native checkbox exposed as an immediate on or off setting. (CSS only.)

Reference: https://timeless.build/docs/components/switch/

> **Choosing between components.** Use Switch for a setting that applies immediately. Use [Toggle](/docs/components/toggle/) when the control is a button whose pressed state is part of a toolbar.

## Markup

```html
<label class="ui-choice" for="dark-mode">
  <input class="ui-switch" id="dark-mode" name="dark-mode" type="checkbox" role="switch" checked aria-describedby="dark-mode-description">
  <span data-ui-part="body">
    <span data-ui-part="title">Dark mode</span>
    <span id="dark-mode-description" data-ui-part="description">Follow the documentation theme.</span>
  </span>
</label>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/forms.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/forms.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**ui-choice**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `body` | No | `[data-ui-part~='body']` | Wrapper for the title and description beside the control. |
| `title` | No | `[data-ui-part~='title']` | The choice label text. |
| `description` | No | `[data-ui-part~='description']` | Supporting copy under the choice label. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-choice**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` · `spacious` | `normal` | Gap between the control and its label. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `invalid` | native | Native `:invalid`, or `aria-invalid="true"`. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-switch`, `ui-choice`.
Required stylesheets: `tokens.css`, `core/forms.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/forms.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (26), global and set at the theme level: `--ui-accent`, `--ui-bg-control`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-danger`, `--ui-danger-soft`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-line`, `--ui-line-strong`, `--ui-radius-md`, `--ui-radius-pill`, `--ui-radius-sm`, `--ui-shadow-control`, `--ui-shadow-inset`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) from the ARIA Authoring Practices Guide.

A native `input[type="checkbox"]` with `role="switch"`, which is the whole component: Tab reaches it, Space toggles it, the checked state is `:checked`, and it submits and resets with the form. `role="switch"` changes only how it is announced — on or off rather than checked or unchecked — so use it when the control takes effect immediately and leave it off when the change needs saving. Label it as you would any checkbox, and do not add `aria-checked`; the native state is authoritative and the two can disagree.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Table

Responsive native tables with readable density. (CSS only.)

Reference: https://timeless.build/docs/components/table/

## Markup

```html
<div class="ui-table" role="region" aria-label="Primitive coverage table" tabindex="0">
  <table>
    <caption>
      <span data-ui-part="caption">Primitive coverage</span>
      <span data-ui-part="description">CSS-only component contracts in this milestone batch.</span>
    </caption>
    <thead>
      <tr>
        <th scope="col">Primitive</th>
        <th scope="col">Contract</th>
        <th scope="col" data-ui-align="end">Depth</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">Badge</th>
        <td><code class="ui-code">.ui-badge</code></td>
        <td data-ui-align="end">Flat</td>
      </tr>
      <tr>
        <th scope="row">Card</th>
        <td><code class="ui-code">.ui-card</code></td>
        <td data-ui-align="end">Flat</td>
      </tr>
    </tbody>
  </table>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/table.css'
import '@timelessui/components/css/core/badge.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/badge.css'
import '@timelessui/components/css/themes/atmosphere/table.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `caption` | No | `[data-ui-part~='caption']` | Table name. Use `<caption>`. |
| `description` | No | `[data-ui-part~='description']` | Supporting copy inside the caption. |
| `empty` | No | `[data-ui-part~='empty']` | Row shown in place of data when the table has none. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-density` | `compact` · `normal` | `normal` | Cell padding. |
| `data-ui-align` | `start` · `end` | `start` | Cell text alignment. Set it on a `<th>` or `<td>`, not on the table. `end` also enables tabular numerals. |

## Styling

Root identity: `ui-table`.
Required stylesheets: `tokens.css`, `core/table.css`, `core/badge.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/badge.css`, `themes/atmosphere/table.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (21), global and set at the theme level: `--ui-accent-soft`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-danger`, `--ui-danger-soft`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-lg`, `--ui-radius-pill`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`, `--ui-success`, `--ui-success-soft`, `--ui-warning`, `--ui-warning-soft`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Tabs

Associate tabs and panels with native keyboard behavior. (Custom element.)

Reference: https://timeless.build/docs/components/tabs/

## Markup

```html
<ui-tabs id="package-tabs" value="install">
  <div role="tablist" aria-label="Package details" aria-orientation="horizontal">
    <button id="package-tabs-install-tab" value="install" role="tab" aria-controls="package-tabs-install-panel" aria-selected="true" tabindex="0" type="button">Install</button>
    <button id="package-tabs-usage-tab" value="usage" role="tab" aria-controls="package-tabs-usage-panel" aria-selected="false" tabindex="-1" type="button">Usage</button>
  </div>
  <section id="package-tabs-install-panel" role="tabpanel" aria-labelledby="package-tabs-install-tab" tabindex="0">
    <p>Install @timelessui/components from npm.</p>
  </section>
  <section id="package-tabs-usage-panel" role="tabpanel" aria-labelledby="package-tabs-usage-tab" tabindex="0" hidden>
    <p>Author native Light DOM anatomy.</p>
  </section>
</ui-tabs>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/tabs.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/tabs.css'
import '@timelessui/components/register/ui-tabs'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineTabsElement } from '@timelessui/components/define/ui-tabs'
defineTabsElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `tablist` | Yes | `[role='tablist']` | Container for the tabs. |
| `tab` | Yes | `[role='tab']` | One tab. Use `<button type="button">` and give it a `value`; Timeless wires `id`, `aria-controls`, `aria-selected`, and `tabindex`. |
| `tabpanel` | Yes | `[role='tabpanel']` | One panel per tab, in the same order. Timeless wires `id`, `aria-labelledby`, and `hidden`. |

These parts also accept per-item input of their own. No stylesheet selects these
attributes — the component reads them.

| Part | Attribute | Description |
| --- | --- | --- |
| `tab` | `data-ui-value` | The value this tab selects, for a tab that cannot carry a bare `value` attribute. `value` wins over it, and the tab `id` is the last fallback. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `activation` | `automatic` · `manual` | `automatic` | Whether moving focus with the arrow keys selects the tab immediately (`automatic`) or waits for Enter or Space (`manual`). Use `manual` when selecting a tab is expensive. |
| `orientation` | `horizontal` · `vertical` | `horizontal` | Arrow-key axis. Mirrored onto `aria-orientation` on the tablist during enhancement. |
| `value` | any `string` | — | The tab selected on load and after a form reset. Match a tab’s `value` attribute. Assign the `value` property for live changes. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-tabs>`

| Property | Type | Notes |
| --- | --- | --- |
| `activation` | `'automatic' | 'manual'` | Reflects the `activation` attribute |
| `orientation` | `'horizontal' | 'vertical'` | Reflects the `orientation` attribute |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<TabsChangeDetail>` | Cancelable proposal dispatched before the selected tab changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<TabsChangeDetail>` | Dispatched after the selected tab has changed. Bubbles and is composed. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `selected` | aria | `aria-selected="true"` on the active tab. |

## Styling

Root identity: `ui-tabs`.
Required stylesheets: `tokens.css`, `core/tabs.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/tabs.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (12), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-md`, `--ui-space-2`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus between tabs along the `orientation` axis. |
| `Home / End` | Move focus to the first or last tab. |
| `Enter / Space` | Select the focused tab. Only needed when `activation` is `manual`; with `automatic` the arrow keys select as they move. |

The tablist is one tab stop: Tab moves into the selected tab, then out to the panel. Timeless manages roving `tabindex`, `aria-selected`, and panel `hidden`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Text and Code

Readable links, keyboard hints, and code treatments. (CSS only.)

Reference: https://timeless.build/docs/components/text-and-code/

## Markup

```html
<div class="ui-primitive-copy">
  <p>Use <a class="ui-link" href="#link">links</a>, <code class="ui-code">inline code</code>, and <kbd class="ui-kbd">Cmd</kbd><kbd class="ui-kbd">K</kbd> in dense interface text.</p>
  <pre class="ui-code" tabindex="0" aria-label="Component CSS import"><code>import '@timelessui/components/css/themes/atmosphere.css'</code></pre>
</div>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/code.css'
import '@timelessui/components/css/core/kbd.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/link.css'
import '@timelessui/components/css/themes/atmosphere/kbd.css'
import '@timelessui/components/css/themes/atmosphere/code.css'
```

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**ui-link**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `default` · `muted` · `danger` | `default` | Link color intent. |

## Styling

Root identity: `ui-link`, `ui-kbd`, `ui-code`.
Required stylesheets: `tokens.css`, `core/code.css`, `core/kbd.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/link.css`, `themes/atmosphere/kbd.css`, `themes/atmosphere/code.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (16), global and set at the theme level: `--ui-accent`, `--ui-accent-hover`, `--ui-bg-control-muted`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-danger`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-font-mono`, `--ui-line`, `--ui-radius-sm`, `--ui-radius-xs`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Toast

Announce transient status from an explicit toaster. (Custom element.)

Reference: https://timeless.build/docs/components/toast/

## Markup

```html
<ui-toaster role="region" aria-label="Notifications" placement="bottom-end" stack="overlap">
  <ui-toast role="status">
    <div data-ui-part="content">
      <h2 data-ui-part="title">Preview ready</h2>
      <p data-ui-part="description">The static example finished building.</p>
    </div>
    <button data-ui-part="close" type="button" aria-label="Dismiss notification">
      <svg aria-hidden="true" focusable="false" viewBox="0 0 16 16">
      <path d="m4.5 4.5 7 7m0-7-7 7" fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="1"/>
    </svg>
    </button>
  </ui-toast>
</ui-toaster>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/toast.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/toast.css'
import '@timelessui/components/register/ui-toaster'
import '@timelessui/components/register/ui-toast'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineToasterElement } from '@timelessui/components/define/ui-toaster'
defineToasterElement()
import { defineToastElement } from '@timelessui/components/define/ui-toast'
defineToastElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-toast>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `content` | No | `[data-ui-part~='content']` | Wrapper for the title and description. |
| `title` | No | `[data-ui-part~='title']` | Short summary line. |
| `description` | No | `[data-ui-part~='description']` | Supporting detail. |
| `close` | No | `[data-ui-part~='close']` | Dismiss button. Give it an accessible name. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-toaster>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `placement` | `top-start` · `top-center` · `top-end` · `bottom-start` · `bottom-center` · `bottom-end` | `bottom-end` | Corner or edge of the viewport the toasts stack against. |
| `stack` | `overlap` · `list` | `overlap` | Whether queued toasts overlap into a deck (`overlap`) or lay out as a full list (`list`). |

**<ui-toast>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `duration` | any `number` | `5000` | Milliseconds before the toast dismisses itself. `0` keeps it open until dismissed. |
| `persistent` | presence | absent | Present to disable auto-dismiss regardless of `duration`. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-toaster>`

| Property | Type | Notes |
| --- | --- | --- |
| `placement` | `'top-start' | 'top-center' | 'top-end' | 'bottom-start' | 'bottom-center' | 'bottom-end'` | Reflects the `placement` attribute |
| `stack` | `'overlap' | 'list'` | Reflects the `stack` attribute |

This element dispatches no component events.

### `<ui-toast>`

| Property | Type | Notes |
| --- | --- | --- |
| `duration` | `string` | Reflects the `duration` attribute |
| `persistent` | `boolean` | Reflects the `persistent` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-dismiss` | `CustomEvent<ToastDismissDetail>` | Dispatched when the toast is dismissed. The detail names the reason: a timeout, the close control, or the imperative API. |

## Styling

Root identity: `ui-toaster`, `ui-toast`.
Required stylesheets: `tokens.css`, `core/toast.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/toast.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-toaster-gap` | Gap between toasts in `list` mode. |
| `--ui-toaster-overlap` | Offset between stacked toasts in `overlap` mode. |

Design tokens this component reads (13), global and set at the theme level: `--ui-bg-control`, `--ui-bg-surface`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-shadow-floating`, `--ui-space-1`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

**<ui-toaster>**

Follows the [Alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) from the ARIA Authoring Practices Guide.

The toaster is the live region, and it is yours to name — author `role="region"` with an `aria-label`, or `role="status"` when the whole surface should announce. Timeless supplies both as a default and neither as a replacement for your own. Nothing here traps focus or steals it: a toast appears without moving the user, and is reached with Tab like anything else. Choose the role by urgency, not by appearance: `role="status"` on a toast is polite and waits its turn, `role="alert"` interrupts and should be rare.

**<ui-toast>**

Follows the [Alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) from the ARIA Authoring Practices Guide.

Give the toast the role its urgency deserves — `role="status"` for the ordinary case, `role="alert"` only when it must interrupt — and give the close control an accessible name. SC 2.2.1 is the criterion to hold in mind: `duration` defaults to 5000ms, and the timer stops while the toast is hovered or contains focus, so nobody loses the message they are reading or the control they are reaching for. `persistent`, or `duration="0"`, removes the limit outright, which is the right choice for anything the user must act on. Dismissing a toast that holds focus hands focus to a surviving toast, or back to wherever it came from, rather than dropping it on `<body>`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Toggle

A pressed-state button using native button behavior. (CSS only.)

Reference: https://timeless.build/docs/components/toggle/

> **Choosing between components.** Use Toggle for a button that stays pressed, such as bold in a toolbar. Use [Switch](/docs/components/switch/) for a setting that applies immediately, which is a checkbox rather than a button.

## Markup

```html
<button class="ui-button ui-toggle" type="button" aria-pressed="true">Bold</button>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/toggle.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/toggle.css'
```

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `primary` · `secondary` · `outline` · `ghost` · `danger` · `danger-outline` · `link` | `primary` | Visual intent, resolved by `themes/atmosphere/button.css`. Author `class="ui-button ui-toggle"` so the shared button styling applies. |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. Resolved by `themes/atmosphere/button.css`. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `pressed` | aria | Author `aria-pressed="true"` or `"false"`; never omit it. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-toggle`.
Required stylesheets: `tokens.css`, `core/toggle.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/toggle.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (24), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-control-hover`, `--ui-shadow-outline-control`, `--ui-space-2`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

This component declares no keyboard contract, because it has none of its own: the markup above
is native elements and native ARIA, and everything a keyboard or a screen reader does with it
comes from the platform. Nothing here manages focus, and nothing here adds a role you did not
author. So the accessibility of this component is the accessibility of the markup — which is why
the markup is the part worth copying exactly.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

---

# Toggle Group

Coordinate single or multiple pressed controls. (Custom element.)

Reference: https://timeless.build/docs/components/toggle-group/

## Markup

```html
<ui-toggle-group selection="single" orientation="horizontal" attached aria-label="Text alignment">
  <button class="ui-button ui-toggle" type="button" value="left" aria-pressed="true">Left</button>
  <button class="ui-button ui-toggle" type="button" value="center" aria-pressed="false">Center</button>
  <button class="ui-button ui-toggle" type="button" value="right" aria-pressed="false">Right</button>
</ui-toggle-group>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/toggle.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/toggle.css'
import '@timelessui/components/register/ui-toggle-group'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineToggleGroupElement } from '@timelessui/components/define/ui-toggle-group'
defineToggleGroupElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

**<ui-toggle-group>**

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `item` | Yes | `button[aria-pressed]` | One toggle button. Author `value` and `aria-pressed`; Timeless keeps the pressed set in sync. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

**<ui-toggle-group>**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `attached` | presence | absent | Present to join the buttons into one segmented control. Styling only, resolved by `themes/atmosphere/toggle.css`. |
| `orientation` | `horizontal` · `vertical` | `horizontal` | Layout and arrow-key axis. |
| `selection` | `single` · `multiple` | `single` | Whether pressing one button releases the others (`single`) or toggles independently (`multiple`). |

**ui-toggle**

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-variant` | `primary` · `secondary` · `outline` · `ghost` · `danger` · `danger-outline` · `link` | `primary` | Visual intent, resolved by `themes/atmosphere/button.css`. Author `class="ui-button ui-toggle"` so the shared button styling applies. |
| `data-ui-size` | `sm` · `md` · `lg` | `md` | Control height, padding, and font size. Resolved by `themes/atmosphere/button.css`. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-toggle-group>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'horizontal' | 'vertical'` | Reflects the `orientation` attribute |
| `selection` | `'single' | 'multiple'` | Reflects the `selection` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<ToggleGroupChangeDetail>` | Cancelable proposal dispatched before the pressed set changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<ToggleGroupChangeDetail>` | Dispatched after the pressed set has changed. Bubbles and is composed. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `pressed` | aria | Author `aria-pressed="true"` or `"false"`; never omit it. |
| `disabled` | native | Native `disabled`. |

## Styling

Root identity: `ui-toggle-group`, `ui-toggle`.
Required stylesheets: `tokens.css`, `core/toggle.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/toggle.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (24), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-control-hover`, `--ui-shadow-outline-control`, `--ui-space-2`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus to the previous or next button, following the orientation and skipping disabled ones. |
| `Home / End` | Move focus to the first or last enabled button. |

The Toolbar pattern rather than the Button pattern, which is what the host renders: `role="toolbar"`, roving `tabindex`, and the whole group as one tab stop. Each button keeps native activation, and `aria-pressed` carries the state — so an individual control is still a button, which is why the pattern link used to point there. With `selection="single"` pressing one button releases the others. Give the host an accessible name; a toolbar without one is indistinguishable from any other.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Toolbar

Arrow-key navigation across a group of commands. (Custom element.)

Reference: https://timeless.build/docs/components/toolbar/

## Markup

```html
<ui-toolbar aria-label="Formatting">
  <button class="ui-button" data-ui-variant="ghost" type="button">Bold</button>
  <button class="ui-button" data-ui-variant="ghost" type="button">Italic</button>
  <button class="ui-button" data-ui-variant="ghost" type="button">Underline</button>
  <button class="ui-button" data-ui-variant="ghost" type="button" disabled>Comment</button>
</ui-toolbar>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/toolbar.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/toolbar.css'
import '@timelessui/components/register/ui-toolbar'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineToolbarElement } from '@timelessui/components/define/ui-toolbar'
defineToolbarElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `item` | Yes | `button, a, input, select, textarea` | Any focusable control in the toolbar. Timeless makes the group one tab stop and moves focus with the arrow keys. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `horizontal` · `vertical` | `horizontal` | Arrow-key axis across the toolbar controls. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-toolbar>`

| Property | Type | Notes |
| --- | --- | --- |
| `orientation` | `'horizontal' | 'vertical'` | Reflects the `orientation` attribute |

This element dispatches no component events.

## Styling

Root identity: `ui-toolbar`.
Required stylesheets: `tokens.css`, `core/toolbar.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/toolbar.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (22), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-focus`, `--ui-radius-control`, `--ui-radius-md`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-outline-control`, `--ui-space-1`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow keys` | Move focus to the previous or next control, following the orientation and skipping disabled ones. |
| `Home / End` | Move focus to the first or last enabled control. |

The whole toolbar is one tab stop. Timeless manages roving `tabindex` so Tab moves past the group rather than through every control. A toolbar control is a real control rather than a command, so `disabled` is the right spelling here and the arrows skip it — unlike [Menu](/docs/components/menu/), where `aria-disabled` keeps an unavailable command discoverable. Give the host an accessible name; a toolbar without one is indistinguishable from any other.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

---

# Tooltip

A concise tooltip built on the hover-card controller. (Custom element.)

Reference: https://timeless.build/docs/components/tooltip/

> **Choosing between components.** Tooltip and [Hover Card](/docs/components/hover-card/) are one custom element with two boxes. `variant="tooltip"` gives a short non-interactive label that sizes to its content and never scrolls; omit it for a roomier surface holding content worth reading or clicking. Because both are `<ui-hover-card>`, the host attributes — `anchor`, `placement`, `open-delay`, `close-delay` — are the same for each and are documented once, on [Hover Card](/docs/components/hover-card/#attributes).

## Markup

```html
<button id="copy-tooltip-anchor" class="ui-button" data-ui-variant="secondary" data-ui-size="sm" type="button" aria-describedby="copy-tooltip" aria-expanded="false">Copy</button>
<ui-hover-card id="copy-tooltip" anchor="copy-tooltip-anchor" variant="tooltip" open-delay="0" close-delay="80" popover="manual" role="tooltip">
  <p>Copy canonical markup</p>
</ui-hover-card>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
import '@timelessui/components/register/ui-hover-card'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineHoverCardElement } from '@timelessui/components/define/ui-hover-card'
defineHoverCardElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Control the label describes. Point its `aria-describedby` at the surface. |
| `content` | Yes | `[popover]` | The label. One short, non-interactive line; give it `role="tooltip"`. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-hover-card>`

| Property | Type | Notes |
| --- | --- | --- |
| `anchor` | `string` | Reflects the `anchor` attribute |
| `variant` | `'tooltip'` | Reflects the `variant` attribute |
| `placement` | `'bottom' | 'top' | 'right' | 'left'` | Reflects the `placement` attribute |
| `openDelayValue` | `string` | Reflects the `open-delay` attribute |
| `closeDelayValue` | `string` | Reflects the `close-delay` attribute |

This element dispatches no component events.

## Styling

Root identity: `ui-hover-card[variant='tooltip']`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/popover.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/popover.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-tooltip-bg` | Surface background. Inverted against the page by default. |
| `--ui-tooltip-fg` | Label color, and the border tint is mixed from it. |

Design tokens this component reads (30), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-md`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-shadow-tooltip`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the label while the trigger has focus. |

A tooltip names or describes its trigger and nothing else. Point the trigger at it with `aria-describedby` and give the surface `role="tooltip"`; Timeless wires relationships, never content. It opens on hover and on keyboard focus, so it is reachable without a mouse, and closes when either leaves. It is deliberately not a disclosure: clicking the trigger does not toggle the label, so a trigger that is also a button keeps its own job on click. The pointer can still be moved onto the label without it disappearing, because WCAG 2.2 SC 1.4.13 requires hover-triggered content to be hoverable — reading a label is not interacting with it. Never put the only copy of anything here — for content the user may want to read at length or click, use Hover Card instead. Both variants share one `open-delay` / `close-delay` pair, documented once on Hover Card; a tooltip that should appear faster sets the attribute rather than getting a different default, because one attribute cannot have two.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.