Getting started

AI agents

Give Claude, Cursor, Codex and other coding agents the context to use CodeAtlas UI correctly, through skills, llms.txt and the agent guide.

The API is designed so a language model gets it right on the first try. A component name says what the screen is (AppList, AppForm, AppSettings, PageShell), props are data, and snippets are the holes you fill. There are no styling decisions to guess: colors, spacing and radius come from --ca-* tokens.

Typed props are the first source of truth. The package ships TypeScript declarations for every component, so an agent with editor or svelte-check feedback sees the exact prop names, unions and defaults.

Machine-readable docs

This site publishes its documentation in plain text for tools that cannot render pages.

Resource	Content
`/llms.txt`	Index: one line per documentation page with title, link and description.
`/llms-full.txt`	Every page concatenated as markdown, with code fences intact, followed by the full `AGENTS.md`. Paste it, or let a tool fetch it, when you want everything in one context.
Agent guide	`AGENTS.md` in the repository: critical rules, spacing and token reference, page template patterns, store and theme setup.

Every page is also linked with <link rel="alternate" type="text/plain" href="/llms.txt"> in its head.

MCP server

ca-ui-mcp is a local Model Context Protocol stdio server that ships with the package. It reads the manifests generated from the component source at build time (components.json, tokens.json and guides.json), so it works offline and always matches the installed version.

Tool	Returns
`list_components`	Every component with its import path and a one-line description. Optional `query` filter.
`get_component`	One component’s import path, props (type, default, `bind:` or not, docs), snippets and public `ca-*` classes. The name is case-insensitive and forgives spaces, `-` and `_`: `get_component("app list")` finds `AppList`.
`get_export`	Signature and summary of any non-component export: functions, stores, constants and types of every entry point (`setLocale`, `toast`, `caErrorPlugin` from `/vite`, `createErrorHandler` and `nativeFeel` from `/kit`, `primeKeyboard` from `/actions`). Without a name it lists them all with their import path.
`search_tokens`	`--ca-*` design tokens matching a name, value or section, with light and dark values (the first 60 matches).
`list_surfaces`	The surface styles (`<html data-style>`: `glass`, `frosted`, `solid`, `flat`, `outlined`, `neumorphic`, `clay`, `tonal`, `chrome`) with the blur each draws (`full`, `reduced`, `none`), the tokens it rewrites and the design recipes that default to it, generated from the `[data-style]` selectors in `materials.css`. Optional `query` filter. The answer also carries the per-platform `defaultStyle` note: backdrop blur on Tauri for Linux (WebKitGTK) is `[INFERENCE: validate with feature detection]`.
`get_guide`	A documentation page as markdown, by slug (`getting-started/theming`) or title. Without a name it lists every guide.
`report_issue`	Drafts a sanitized GitHub issue when the library gets in the agent’s way: markdown body, the redactions applied, a prefilled form link and a `gh issue create` command. It never posts. See Reporting problems.

Prop names are never guessed: an agent asks the server and gets the types the compiler sees.

claude mcp add codeatlas-ui -- npx -y -p @codeatlasdev/ui ca-ui-mcp

{
  "mcpServers": {
    "codeatlas-ui": {
      "command": "npx",
      "args": ["-y", "-p", "@codeatlasdev/ui", "ca-ui-mcp"]
    }
  }
}

{
  "mcpServers": {
    "codeatlas-ui": {
      "command": "npx",
      "args": ["-y", "-p", "@codeatlasdev/ui", "ca-ui-mcp"]
    }
  }
}

If the package is already a dependency of your app, point the command at the local binary instead (node_modules/.bin/ca-ui-mcp) to skip the download and pin the version your code compiles against.

The same data is available as files: @codeatlasdev/ui/components.json (components under components, every other export under exports) and @codeatlasdev/ui/tokens.json (tokens).

Pick a demo by number

Every docs demo has a stable id #NNN (index: /api/v1/catalog.json, gallery: /gallery/). An id, a ?pick=012,045 link and pasted “I picked these N from the @codeatlasdev/ui gallery” text are the same selection.

Unknown id: search_demos({ query }) (MCP ca-ui-mcp). Known ids: get_demo({ ids }), at most 8 per call. Without MCP, fetch https://ui.codeatlas.com.br/api/v1/en/e/NNN.txt.
Port: keep component names, props, variants and motion tokens as in the reference; change only data, copy and theme. Keep the first comment line (license) of the reference in the file you write.
Report one line per demo: #NNN title → file, what changed, demo link.

get_demo takes ids as 12, 012, #012 or a docs URL ending in #<slug>. In Claude Code the plugin installs the skill and the MCP server in one line:

/plugin install codeatlas-ui --marketplace codeatlasdev/ui

Motion demos also carry Names (a canonical name and aliases, other languages included) and a Motion list with the exact property, duration, easing, delay, stagger or spring. search_demos matches a name or alias first, so “fade rise” finds #256 before any summary does. The prompt tells the agent to reproduce those values exactly and to render the final state under prefers-reduced-motion. See Motion.

Each reference carries a Spec list written from the demo’s literal values (props, snippets, state, counts, sizes), so the agent can check its port against it. get_demo and the /api/v1/en/e/NNN.txt page print it under What it shows and When to use.

To choose pages without leaving the terminal, run the pick command. It opens the gallery, waits for you to press Send to AI, and prints the ids:

bunx @codeatlasdev/ui pick           # opens /gallery/, prints: #005 #012
bunx @codeatlasdev/ui pick 12 45     # same, with #012 and #045 already ticked

The command listens on 127.0.0.1 only, on a random port, and the callback link carries a random per-run token: a request without the token gets a 403 and the listener keeps waiting. It closes after the first valid pick, after --timeout <seconds> (600 by default) or on Ctrl-C, and exits with code 1 if nothing was picked. The gallery only shows Send to AI for a loopback cb address. --url <gallery> points it at another deployment.

When the library gets in the way

The agent writes a workaround marked // ca-ui-workaround(#<n>): <why> and drafts a sanitized issue with report_issue, with neutral names only. bunx @codeatlasdev/ui workarounds later lists the markers and which issues are closed. Details and the privacy rules: Reporting problems.

Set up and migrate with the CLI

bunx @codeatlasdev/ui init

init detects SvelteKit or Astro and wires up what the installation page describes: the theme file, the theme hook or integration, the global.css import, colorScheme.init() and a mobile-ready viewport meta. It creates files that are missing and never overwrites one that exists: it prints a diff instead, and --write applies it. --dir <path> runs it on another project directory. Running it twice changes nothing.

bunx @codeatlasdev/ui migrate          # print the diff
bunx @codeatlasdev/ui migrate --write  # apply it

migrate rewrites code for renamed APIs by parsing .svelte, .ts, .js and .astro files (it walks src by default, or the paths you pass), so only real references change (not strings or same-named identifiers from other packages). It renames the BrandPreset type to PresetDefinition and moves the deprecated GlassCard, GlassSurface and Row to Card, Surface and Flex; an element with a prop it cannot map is left as it was and listed at the end (file:line, reason, recipe). --strict exits with code 1 when anything was left.

Coming from React? The Migrate from React guide maps MUI, shadcn/Radix and Chakra components, hooks and themes onto this library, and tells the agent how to report what has no equivalent. In MCP it is get_guide("migrate-react").

Install the skills

The repository ships three agent skills that work with Claude Code, Cursor, Codex and other agents that support the skills format:

npx skills add codeatlasdev/ui

Skill	What it teaches
`codeatlas-ui`	Components, props, layout rules, AppShell and page template patterns, and the anti-patterns to avoid.
`codeatlas-dx`	File structure and size limits so the codebase stays clean.
`codeatlas-writing`	UI copy that does not read like a chatbot wrote it.

The skill follows main, not your installed version

npx skills add copies the skill and its API.md from the main branch, so they can describe props, tools and exports that your installed @codeatlasdev/ui does not have yet (with 4.1.0 installed, a skill from main already documented the icon snippet of DropdownMenuItem and the report_issue tool, both new in 4.2.0). API.md states the version it was generated for in its first lines. The package you installed is the source of truth: ca-ui-mcp ships inside it and answers for exactly that version, as does node_modules/@codeatlasdev/ui/dist/components.json. Pin the server to your version (npx -y -p @codeatlasdev/ui@<your version> ca-ui-mcp, or node_modules/.bin/ca-ui-mcp), and update the skill with npx skills update after you upgrade the package.

Point your agent at the docs

Claude Code. Install the skills above, or add a line to your CLAUDE.md:

This project uses @codeatlasdev/ui (Svelte 5). Docs for agents: https://ui.codeatlas.com.br/llms.txt
Read https://ui.codeatlas.com.br/llms-full.txt before writing UI. Never write layout CSS; use Grid, Flex, Stack and --ca-* tokens.

Cursor. Add https://ui.codeatlas.com.br/llms-full.txt as a custom doc source in Cursor’s settings, or put the same instructions in a project rule so every chat starts with them.
Other agents. Put the instructions in AGENTS.md (or your tool’s equivalent) at the root of your app, and let the agent fetch llms.txt when it needs a component.

Rules worth repeating to any agent

These come from the agent guide and prevent the most common mistakes:

Import everything from @codeatlasdev/ui, never from internal paths. Charts, DataTable and CodeSnippet come from the /charts, /table and /code subpaths.
Import global.css once, in the root layout, and call colorScheme.init() there.
No layout CSS and no hardcoded colors. Use Grid, Flex and Stack with a numeric gap, and --ca-* tokens.
No inline padding or margin. Inline styles are only for dynamic custom properties such as style="--bar-w:{pct}%".
Build pages with AppList, AppForm, AppSettings or PageShell, not hand-made wrappers. Put AppShellLayout only in authenticated route layouts.
Svelte 5 runes only ($state, $derived, $props). No stores from svelte/store, no svelte:component.
Never combine will-change: transform with backdrop-filter.
ca-* classes are public API: do not rename or remove them.

Tip

Ask the agent to run svelte-check after generating UI. Prop typos and wrong snippet names show up as type errors, which is the fastest feedback loop for both people and agents.

Why it works

Page-level components: the agent chooses a template, not forty primitives.
Closed prop vocabularies: variant, size and severity are string unions, not free-form classes.
One token system: there is one place for color, radius, spacing and type, so output stays consistent across generations.
Tested for accessibility: components are checked with axe, so generated pages start from an accessible baseline, see Accessibility.