# 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](#markdown). 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** ```bash 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](https://www.theui.dev/docs/cli) 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](https://agents.md) convention, which is now a Linux Foundation standard rather than any one vendor's format: **AGENTS.md** ```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** ```md @node_modules/theui-svelte/AGENTS.md # My project ...your own notes... ``` > **Note:** 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](#claude-code). | | 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** ```md 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** ```diff @import 'tailwindcss'; + @import 'theui-svelte/style'; ``` > **Note:** 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`](https://www.theui.dev/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`](https://www.theui.dev/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/.md` — a single page. Append `.md` to any documentation address, as in [`/docs/button.md`](https://www.theui.dev/docs/button.md). This is the one to reach for when an agent needs one component, because it is a single request. - [`/llms.txt`](https://www.theui.dev/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](https://www.theui.dev/svelte/llms.txt), 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`](https://www.theui.dev/docs/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`](https://www.theui.dev/docs/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`](https://www.theui.dev/docs/input) whose `type` is `textarea`. - [`Tooltip`](https://www.theui.dev/docs/tooltip) and [`Notification`](https://www.theui.dev/docs/notification) are page-level singletons. Render each once in your layout; a second instance doubles the listeners. - [`Popover`](https://www.theui.dev/docs/popover) takes the `id` of its trigger as a string, not a snippet, and stays silent when that id does not resolve. - A [`Table`](https://www.theui.dev/docs/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`](https://www.theui.dev/docs/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`](https://www.theui.dev/docs/navbar) family. Build with the [semantic color tokens](https://www.theui.dev/docs/colors) and pair every color with a `dark:` counterpart, and generated pages follow your theme instead of hard-coding one. --- Category: Guides Keywords: ai, agents.md, llms.txt, claude code, codex, cursor, copilot, vs code, coding agent, guide, theui-svelte, svelte, component-library Full documentation set: https://www.theui.dev/llms-full.txt