itsjavi/timeless/using-timeless-ui

Using Timeless UI

Timeless is not a prop-based component library. It has no runtime wrapper, no className merge helper, and no component functions to import. You write native HTML and add a class or a tag. Markup copied from a React library's conventions will not work here, so read the grammar below before writing any.

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.

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

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

reference/contracts.md, beside this file, lists every root in the library, which kind it is, its configuration attributes and the value set each names, its parts, and its stylesheets. It is generated from the same declaration the stylesheets are validated against. Value sets are also exported as as const arrays from the package root — import the array rather than retyping a list.

Verifying your markup

Before finishing, check the markup against reference/contracts.md:

1. Each root is spelled as the reference spells it, and configured the way its kind requires.
2. No data-ui-* on a custom-element host, and no plain configuration attribute on a class root.
3. No boolean attribute carries a value.
4. Every required part is present.
5. No data-ui-internal-* anywhere.
6. Every stylesheet is imported, and every custom element used is registered.