AI agents

View as Markdown

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

File	Approximate tokens	When to use it
`/llms.txt`	3,531	Start here. The authoring grammar plus an index of every page.
`/llms-full.txt`	101,434	Every guide and every contract, for models with the context to hold it.

Start with /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 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 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:

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.

## Timeless UI

- Timeless has two kinds of component, configured differently. 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. 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-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">`.
- Boolean attributes are presence-based. Author the attribute with no value, or omit it.
- Component anatomy is authored by you and marked with a whitespace-separated `data-ui-part` token
  list, selected with `[data-ui-part~='name']`.
- A few parts accept per-item input of their own, spelled `data-ui-*` on the part. Each component
  page lists them.
- Never author `data-ui-internal-*`. Those are private runtime hooks.
- 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.
- Accessible names are always yours to supply.
- The markup you author is the markup that ships. Components are usable before JavaScript runs.
- 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.
- Before guessing an attribute or a value, fetch the component contract rather than inferring it. It
  is at `https://timeless.build/docs/components/<component>.md`, indexed at
  `https://timeless.build/llms.txt`.

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.

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.