# Timeless UI

> 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`.

## Overview

- [Timeless documentation](https://timeless.build/docs.md): Framework-agnostic UI built on modern web standards.

## Getting started

- [The post-framework era](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.
- [Installation](https://timeless.build/docs/getting-started/installation.md): Install Timeless, load its CSS, and register the elements a route uses.
- [Quick start](https://timeless.build/docs/getting-started/quick-start.md): Build a Timeless interface from native HTML and explicit enhancement.
- [AI agents](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.
- [Editor setup](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.

## Styling

- [Loading CSS](https://timeless.build/docs/styling/css.md): The three CSS tiers, which two are required, and how to replace the theme with your own.
- [Theming](https://timeless.build/docs/styling/theming.md): Override Timeless styles with cascade layers, design tokens, and component variables.
- [Utility CSS and Tailwind](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.

## Frameworks

- [Vanilla](https://timeless.build/docs/frameworks/vanilla.md): Use Timeless directly from HTML and JavaScript.
- [React](https://timeless.build/docs/frameworks/react.md): Use custom elements directly with opt-in JSX types and no runtime wrapper.
- [Preact](https://timeless.build/docs/frameworks/preact.md): Use custom elements directly with opt-in JSX types and no runtime wrapper.
- [Astro](https://timeless.build/docs/frameworks/astro.md): Render Timeless anatomy on the server and register behavior in the browser.
- [Svelte](https://timeless.build/docs/frameworks/svelte.md): Use Timeless elements as native custom elements in Svelte.
- [Vue](https://timeless.build/docs/frameworks/vue.md): Configure Vue to treat ui elements as native custom elements.
- [Solid](https://timeless.build/docs/frameworks/solid.md): Render Timeless custom elements directly from Solid.

## Reference

- [Packages and entrypoints](https://timeless.build/docs/reference/packages.md): Every published import, what it contains, and whether it is safe on the server.
- [Browser support](https://timeless.build/docs/reference/browser-support.md): The platform features Timeless requires, and what happens where they are missing.
- [What Timeless does not ship](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.

## Components

49 components. Each link is the component's full contract as Markdown.

### Foundations

- [Separator](https://timeless.build/docs/components/separator.md): Separate related regions with native semantics.
- [Text and Code](https://timeless.build/docs/components/text-and-code.md): Readable links, keyboard hints, and code treatments.

### Actions

- [Button](https://timeless.build/docs/components/button.md): Tactile native actions with clear variants.
- [Copy Button](https://timeless.build/docs/components/copy-button.md): Copy a value to the clipboard, and say so.
- [Toggle](https://timeless.build/docs/components/toggle.md): A pressed-state button using native button behavior.
- [Toggle Group](https://timeless.build/docs/components/toggle-group.md): Coordinate single or multiple pressed controls.

### Forms

- [Checkbox Group](https://timeless.build/docs/components/checkbox-group.md): Coordinate a group of native checkboxes.
- [Combobox](https://timeless.build/docs/components/combobox.md): Filter an authored listbox from a native text input.
- [Field](https://timeless.build/docs/components/field.md): Connect labels, descriptions, errors, and native controls.
- [Fieldset](https://timeless.build/docs/components/fieldset.md): Group unrelated controls under one native legend.
- [File Input](https://timeless.build/docs/components/file-input.md): A native file input with consistent field anatomy.
- [Form](https://timeless.build/docs/components/form.md): Put server-side errors back onto the fields they came from.
- [Listbox](https://timeless.build/docs/components/listbox.md): Keyboard selection over authored options.
- [Native Select](https://timeless.build/docs/components/native-select.md): Style a native select while preserving platform behavior.
- [Number Stepper](https://timeless.build/docs/components/number-stepper.md): Enhance a native number input with increment controls.
- [OTP Field](https://timeless.build/docs/components/otp-field.md): A one-time code across native single-character inputs.
- [Radio Group](https://timeless.build/docs/components/radio-group.md): Coordinate a roving native radio group.
- [Range](https://timeless.build/docs/components/range.md): A readable native range control with an output.
- [Range Field](https://timeless.build/docs/components/range-field.md): Two native thumbs on one track, kept in order.
- [Select](https://timeless.build/docs/components/select.md): Enhance authored trigger, value, and listbox anatomy.
- [Switch](https://timeless.build/docs/components/switch.md): A native checkbox exposed as an immediate on or off setting.

### Navigation

- [Breadcrumb](https://timeless.build/docs/components/breadcrumb.md): A trail of links to the pages above this one. CSS only.
- [Context Menu](https://timeless.build/docs/components/context-menu.md): Open a menu at the pointer, or from the keyboard.
- [Menu](https://timeless.build/docs/components/menu.md): Roving keyboard navigation for commands.
- [Menu Button](https://timeless.build/docs/components/menu-button.md): Connect a command trigger to a native popover menu.
- [Pagination](https://timeless.build/docs/components/pagination.md): Page navigation as real links. CSS only.
- [Tabs](https://timeless.build/docs/components/tabs.md): Associate tabs and panels with native keyboard behavior.
- [Toolbar](https://timeless.build/docs/components/toolbar.md): Arrow-key navigation across a group of commands.

### Content

- [Avatar](https://timeless.build/docs/components/avatar.md): Identity fallback and presence indicators.
- [Card](https://timeless.build/docs/components/card.md): Flat structured content with public anatomy.
- [Collapsible](https://timeless.build/docs/components/collapsible.md): Style native disclosure groups without replacing details.
- [Group](https://timeless.build/docs/components/group.md): Arrange related controls with density and attachment options.
- [List](https://timeless.build/docs/components/list.md): Structured lists with titles and descriptions.
- [Table](https://timeless.build/docs/components/table.md): Responsive native tables with readable density.

### Feedback

- [Alert](https://timeless.build/docs/components/alert.md): Communicate status without replacing native live-region semantics.
- [Badge](https://timeless.build/docs/components/badge.md): Compact status and metadata labels.
- [Empty](https://timeless.build/docs/components/empty.md): Explain an empty state and offer one clear next action.
- [Meter](https://timeless.build/docs/components/meter.md): Display a scalar measurement within a known range.
- [Progress](https://timeless.build/docs/components/progress.md): Expose determinate or indeterminate task progress.
- [Skeleton](https://timeless.build/docs/components/skeleton.md): Reserve stable space while content loads.
- [Spinner](https://timeless.build/docs/components/spinner.md): Indicate a short operation without changing layout.
- [Toast](https://timeless.build/docs/components/toast.md): Announce transient status from an explicit toaster.

### Overlays

- [Dialog](https://timeless.build/docs/components/dialog.md): Enhance an authored native dialog with focus management.
- [Hover Card](https://timeless.build/docs/components/hover-card.md): Open supporting content from pointer or keyboard intent.
- [Popover](https://timeless.build/docs/components/popover.md): Connect an authored trigger to a native popover.
- [Sheet](https://timeless.build/docs/components/sheet.md): Present an authored native dialog from a viewport edge.
- [Tooltip](https://timeless.build/docs/components/tooltip.md): A concise tooltip built on the hover-card controller.

### Color

- [Color Picker](https://timeless.build/docs/components/color-picker.md): Edit modern color formats through authored controls.
- [Color Swatch](https://timeless.build/docs/components/color-swatch.md): Display and select a named color value.

## Optional

- [Full documentation](https://timeless.build/llms-full.txt): every guide and every contract in one file.
- [Using Timeless with AI agents](https://timeless.build/docs/getting-started/agents.md): the skill, the Markdown routes, and editor tooling.