AI Coding Assistants

A coding agent that has never seen theui-svelte guesses at the API, and the guesses fail quietly rather than loudly. The package ships the rules it cannot guess, and one command hands them to your agent — the difference between an agent that invents props and one that writes working components.

What Comes With The Package

Everything an agent needs is inside the installed package. The pages on this site are a convenience for tools that fetch URLs, not a dependency — an agent working offline has the whole contract locally.

node_modules/theui-svelte/AGENTS.md — the composition rules, the shared prop contract, which children throw outside their parent, and the behaviours that are easy to get wrong.
node_modules/theui-svelte/dist/**/*.d.ts — every prop name and type, for the exact version installed. These cannot drift from the code, so they are the better answer to what props does this take.
The same documentation as Markdown over HTTP, for tools that would rather read a URL. See further down.

Because the rules travel with the package, they describe the version you installed rather than whatever is newest, and they keep working when a future library is published under its own name.

Setting It Up

Agents look for instructions in a project root, and none of them promise to read anything from inside node_modules. So the rules that ship with the package have to be connected to the files your tools already read. One command does that:

Run this once, in your project root

npx theui ai

It writes a short block into whichever instruction files your project already has — AGENTS.md, CLAUDE.md, Copilot, Cursor, Windsurf, Gemini — each naming the path to the rules inside the package, then prints back which files it touched. The CLI reference covers every option and the exact block it writes.

It writes a pointer rather than a copy, which matters twice. It cannot overwrite rules you wrote yourself, because it only ever adds its own block between two markers. And it cannot go stale: upgrading the library upgrades what your agent reads, with nothing to refresh.

To do it by hand instead, add one line to your AGENTS.md, creating the file if you have none. That is the whole setup for every tool following the AGENTS.md convention, which is now a Linux Foundation standard rather than any one vendor's format:

AGENTS.md

## theui-svelte

Before writing or changing code that uses a theui-svelte component, read
`node_modules/theui-svelte/AGENTS.md`.

Commit whichever you choose, so everyone on the project works from the same rules. One tool needs a line of its own, and it is the one most Svelte developers use. That is next.

Claude Code

Claude Code reads AGENTS.md only as a fallback. If a CLAUDE.md exists in the directory or any directory above it, AGENTS.md is ignored completely — so a project that already has a CLAUDE.md never sees a root AGENTS.md at all.

This is the one case convention does not cover, so the command writes an extra line into CLAUDE.md itself: an @ import, which Claude Code resolves and pulls in rather than looking up later. By hand it is one line at the top, and nothing needs updating when you upgrade the library:

CLAUDE.md

@node_modules/theui-svelte/AGENTS.md

# My project
...your own notes...

If you have no CLAUDE.md at all, a root AGENTS.md is picked up on its own and there is nothing more to do — which is why the command creates that file but never creates a CLAUDE.md in a project that does not use Claude Code.

Every Other Tool

Most tools read the root AGENTS.md directly. The ones that keep their own instructions file do not need a second copy of the rules — a single line naming the path is enough, and it will not go stale. npx theui ai writes that line into each of the files below that your project already has, so this table is both what it does and what to do yourself if you would rather.

Tool	Where its instructions live	What to do
Codex	`AGENTS.md`	Nothing. Reads the root file, and a nested one wins for files beside it.
Cursor	`AGENTS.md`	Nothing. A root file carries the same weight as a project rule.
GitHub Copilot	`AGENTS.md`	Nothing, in the editor and in the coding agent.
VS Code, repository-wide	`.github/copilot-instructions.md`	Optional. VS Code already reads `AGENTS.md`; use this when you also want always-on rules of your own.
Cursor, path-scoped rules	`.cursor/rules/*.mdc`	Optional. The extension must be `.mdc` — a plain `.md` in that folder is skipped.
Claude Code	`CLAUDE.md`	Add `@node_modules/theui-svelte/AGENTS.md`. See above.
Gemini CLI	`GEMINI.md`	Add a line naming `node_modules/theui-svelte/AGENTS.md`.
Aider	`.aider.conf.yml`	Add `node_modules/theui-svelte/AGENTS.md` under `read:`, since Aider needs the file named explicitly.
Windsurf, Zed, Junie, Jules, Devin, Amp	`AGENTS.md`	Nothing.

For any file in the middle column, this is all it takes:

Pointing another instructions file at the rules

Follow the conventions in node_modules/theui-svelte/AGENTS.md when writing
theui-svelte components.

Tools change quickly, and this table will drift. The root AGENTS.md is the part that keeps working: it is a published standard, not a per-vendor setting.

The Stylesheet Is Two Lines

Tailwind CSS v4 finds classes by scanning files, and it skips node_modules. Until version 3.1.0 that meant a third line in your CSS pointing Tailwind back at the package, and forgetting it rendered every component unstyled with nothing logged — the single most common report that the library was broken.

The package registers its own markup now, so there is nothing to remember:

./src/app.css

     @import 'tailwindcss';
+    @import 'theui-svelte/style';

A project carrying the old @source "../node_modules/theui-svelte"; line is fine — it is redundant now rather than harmful, and can be deleted whenever convenient. If components still render unstyled, the thing to check is that @import 'theui-svelte/style' is there at all, because that import is how Tailwind reaches the library.

Fetch The Documentation As Markdown

Rendered HTML costs an agent a great deal of context for very little content, so every page here is published as Markdown too. These addresses are per library, which leaves room for others to be published beside this one.

/svelte/llms.txt — the index. Every page with a one-line description, preceded by the install steps and the rules most often got wrong. Small enough to paste into a prompt.
/svelte/llms-full.txt — the whole set in one file. Thorough, and large: for a tool that indexes the library once rather than on every request.
/docs/<name>.md — a single page. Append .md to any documentation address, as in /docs/button.md. This is the one to reach for when an agent needs one component, because it is a single request.
/llms.txt — the root index, which only says which libraries exist and where each one's index is.

Every page also advertises its Markdown twin with an alternate link tag, so a crawler finds it without being told. The props table survives the conversion, so a twin carries the same API reference as the page you are reading rather than a summary of it.

What The Rules Actually Say

These are the things a model gets wrong when it reasons from component names alone. They are in AGENTS.md and in the index, and they are worth knowing yourself.

Deep import paths are flat. AccordionItem sits in the Accordion folder but imports from theui-svelte/AccordionItem.svelte, never from a nested path.
Content holes are Svelte 5 snippets. There are no slots, no export let, no createEventDispatcher and no stores anywhere in the library.
The standalone prop of Accordion reads backwards. Its default of true means only one panel opens at a time; it does not mean an item works on its own.
Tabs defaults to pills rather than tabs, and a Tab pairs with its TabPanel by matching value instead of by order.
There is no Textarea component. It is an Input whose type is textarea.
Tooltip and Notification are page-level singletons. Render each once in your layout; a second instance doubles the listeners.
Popover takes the id of its trigger as a string, not a snippet, and stays silent when that id does not resolve.
A Table built from objects needs keys to fix the column order. Without it the rows render no cells, and nothing is logged.
DropdownItem belongs to Dropdown. Inside a NavDropdown use NavLink: they are two separate context systems, and mixing them throws.
Some children throw outside their parent rather than falling back: Tab, TabPanel, Slide, DropdownItem, and the whole Navbar family.

Build with the semantic color tokens and pair every color with a dark: counterpart, and generated pages follow your theme instead of hard-coding one.