# CodeAtlas UI: full documentation

> Open-source Svelte 5 component library (`@codeatlasdev/ui`). Index: https://ui.codeatlas.com.br/llms.txt

---

# Introduction

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/

CodeAtlas UI is an open-source Svelte 5 component library with a sober solid default, opt-in glass materials, an OKLCH theme engine and native-feeling mobile behavior.

CodeAtlas UI gives Svelte 5 apps full screens, not just bricks: page templates, an app shell, data tables, charts, forms and overlays, all built on a headless layer of our own and themed through CSS custom properties.

```svelte
<AppList title="Users" data={users} searchKeys={["name", "email"]}>
  {#snippet children(list)}
    <SimpleTable>
      {#each list.rows as u (u.id)}
        <tr><td><UserCell name={u.name} email={u.email} /></td></tr>
      {/each}
    </SimpleTable>
  {/snippet}
</AppList>
```

That is a whole users page: header, search, pagination and empty state, with no CSS written.

## What you get

- Page templates instead of primitives: `AppList`, `AppForm`, `AppSettings`, `PageShell` and `AppShellLayout` bring layout, spacing and empty states.
- Sober by default, glass on request: surfaces are solid and opaque out of the box. The `liquid` recipe (or `defaultStyle: "glass"`) brings back Liquid Glass, with five material tiers over a real `backdrop-filter` and opaque fallbacks for reduced transparency.
- A theme engine with eight OKLCH presets, brand presets from one hex color, nine surface styles, fifteen design-style recipes and no flash on load.
- Native feel on mobile: safe areas, keyboard handling, 44px touch targets, bottom sheets with swipe to dismiss and a browser chrome color that follows the page.
- Accessibility: WAI-ARIA keyboard and focus behavior, axe-tested components, reduced motion and reduced transparency support.
- Small bundles: Charts, DataTable and CodeSnippet are separate entry points with optional peers, so they stay out of your bundle unless imported.
- Agent-ready: closed prop vocabularies, typed props, an MCP server, `llms.txt` and installable skills.

## Install

## Start here

## Explore

---

# Installation

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/installation/

Install @codeatlasdev/ui and wire the theme into SvelteKit, Astro or plain Vite without a flash of the wrong theme.

CodeAtlas UI needs Svelte 5 (runes mode). In a SvelteKit or Astro app, `bunx @codeatlasdev/ui init` does the whole setup below for you (see [The `init` command](#the-init-command)). Setup is three things: import the stylesheet once, inject the theme script before first paint, and start the `colorScheme` store in your root layout.

The core bundle stays small. Heavy features are separate entry points with optional peer dependencies, so install only what you use:

| Feature | Import from | Also install |
|---|---|---|
| Charts | `@codeatlasdev/ui/charts` | `echarts` |
| DataTable | `@codeatlasdev/ui/table` | `@tanstack/svelte-table` |
| CodeSnippet | `@codeatlasdev/ui/code` | `shiki` |
| Masked and money fields | `@codeatlasdev/ui/forms` | nothing |
| Accessibility test helpers | `@codeatlasdev/ui/testing` | `axe-core` |
| Icons in your own code (`KpiCard`, `Chip`, `Button` and nav items take icon components) | `@lucide/svelte` | `@lucide/svelte` |
| Brand icons (`caBrandPlugin`) | `@codeatlasdev/ui/vite` | `@resvg/resvg-js` and `png-to-ico` |
| `migrate` command | `bunx @codeatlasdev/ui migrate` | `typescript` (resolved from the project; without it the command prints the install hint and exits 1) |

`@sveltejs/kit` and `astro` are optional peers too: install the one your app uses. Icons are `@lucide/svelte` components. The package depends on it for its own icons, but Bun's isolated linker (and pnpm) do not expose a dependency's dependency to your app, so `import { ArrowRight } from "@lucide/svelte"` fails until you run `bun add @lucide/svelte` yourself.

### Release channels

Releases are published by version tag (`@codeatlasdev/ui@X.Y.Z`), not from branches. The prerelease id in the version is the npm dist-tag.

| Version | Install | When to use it |
|---|---|---|
| `X.Y.Z` | `bun add @codeatlasdev/ui` (dist-tag `latest`) | Production. Semver: breaking changes only in a major. |
| `X.Y.Z-beta.N` | `bun add @codeatlasdev/ui@beta` | A prerelease of the next version. It never moves `latest`. Try it before it ships. |

A prerelease with another id (`X.Y.Z-alpha.N`, for example) is published under a dist-tag with that id. Pin an exact version (`bun add @codeatlasdev/ui@3.1.0-beta.2`) to keep a prerelease stable.

Every version is published from CI with an npm provenance statement, so you can check which commit and workflow built it (`npm audit signatures`).

## The `init` command

```sh
bunx @codeatlasdev/ui init [--write] [--dir <path>]
```

`init` detects the framework from `package.json` (`@sveltejs/kit` means SvelteKit, otherwise `astro` means Astro) and prints `Detected SvelteKit.` or `Detected Astro.`. With neither it prints an error and exits with code 1. Then it goes through the files of that framework, one line each:

| Line | Meaning |
|---|---|
| `create  <file>` | The file was missing and is now written (`--write`). |
| `would create  <file>` | The file is missing. Nothing is written until you re-run with `--write`. |
| `ok      <file> (already set up)` | Nothing to change. Running `init` again on a finished setup prints only `ok` lines. |
| `diff    <file> (exists, not modified)` | The file exists and needs a change. A unified diff follows; nothing is written until you re-run with `--write`. |
| `patch   <file>` | The change was applied (`--write`). |
| `manual  <file>: could not patch safely.` | `init` could not edit the file safely (no `plugins: [...]` array, an existing `handle` of your own, no `</body>`). It says what to add by hand and exits with code 1. |
| `skip    <file> (not found)` | The file does not exist and `init` does not create it (`vite.config.ts`, `src/app.html` and the Astro config). |
| `skip    <file>: the app already imports its theme from "<module>"` | `vite.config.ts`, `hooks.server.ts` (or the Astro config) already import `theme` from somewhere else, for example a shared workspace package. `init` does not create `src/lib/theme.ts` (`src/theme.ts` on Astro) and wires the files it adds to that import. |

| Flag | Effect |
|---|---|
| `--write` | Create the missing files and apply the proposed changes. Without it `init` is a dry run: nothing touches the disk. |
| `--dir <path>` | Project directory. Defaults to the current directory. |

When anything is pending it ends with `N change(s) not applied. Re-run with --write to create the files and apply the diffs above.` A clean run ends with `Done. Run your dev server: the theme paints on the first frame.`

## SvelteKit

`@codeatlasdev/ui` supports SvelteKit 2 (`^2.12`) and SvelteKit 3. The steps below are the same on both; the differences are in [SvelteKit 3](#sveltekit-3). `init` reads the installed Kit major (`node_modules/@sveltejs/kit`, or the range in `package.json` before `install` ran; anything it cannot parse counts as 2) and writes the right theme import.

### What `init` writes

For each file below, `init` creates it when it is missing, except `vite.config.ts` and `src/app.html`, which it only patches (it prints `skip` when they are not there). Without `--write` nothing is written: `init` prints `would create` for a missing file and a diff for an existing one. A file that already exists is never overwritten: its diff is applied only with `--write`. Re-running it changes nothing once the setup is complete.

| File | What `init` puts there | If the file exists |
|---|---|---|
| `src/lib/theme.ts` | the shared `theme` object (`defaultPreset: "amber"`, `defaultScheme: "system"`) | left alone |
| `vite.config.ts` | `caThemePlugin(theme)` and `caErrorPlugin({ scaffold: true, theme })`, appended to `plugins`, in one `@codeatlasdev/ui/vite` import (plus `import { theme } from "./src/lib/theme.ts"`) | adds only the plugin that is missing |
| `src/hooks.server.ts` | `handle = sequence(caThemeHandle(theme))` and `handleError = createErrorHandler()` | adds only what is missing; reports `manual` if you already define a `handle` of your own; never touches your `handleError` |
| `src/routes/+layout.svelte` | the stylesheet import, `colorScheme.init()` in `onMount` and a default `<Seo>` (title, canonical from `page.url`, `manifest="/manifest.webmanifest"`) | adds only what is missing; an existing `<Seo>` is kept |
| `src/app.html` | the viewport meta with `viewport-fit=cover, interactive-widget=resizes-content` | rewrites only the viewport meta; reports `manual` when there is none |
| `src/routes/manifest.webmanifest/+server.ts` | a prerendered manifest built with `manifest({ name, theme, icons })` | left alone |
| `src/routes/robots.txt/+server.ts`, `src/routes/sitemap.xml/+server.ts` | prerendered `robotsTxt()` (pointing at the sitemap) and `sitemapXml()` listing the static pages (no `[param]` routes, route groups dropped, no `/offline`) | left alone |
| `src/service-worker.ts` (Kit 2) or `src/service-worker/index.ts` (Kit 3), `src/routes/offline/` | the worker from [PWA](/docs/getting-started/pwa/#service-worker) and the prerendered offline page it falls back to | left alone |

After creating these, `init` prints what the app still has to provide: its public origin (`paths.origin`, otherwise sitemap, `robots.txt` and canonical URLs carry Kit's prerender placeholder), the manifest icons, and on Kit 3 the `src/service-worker` entry in the `exclude` of `tsconfig.json`. See [SEO](/docs/getting-started/seo/) and [PWA](/docs/getting-started/pwa/).

`caErrorPlugin({ scaffold: true, theme })` then creates `src/routes/+error.svelte` and `src/error.html` the first time Vite runs (dev or build), and never overwrites them. `src/error.html` takes its colors, default scheme and preset from the `theme` you pass (the same object as `caThemePlugin`), carries the theme init script in `<head>`, and has no inline handler or `javascript:` URL, so it works under a strict CSP. Its copy and `lang` follow `locale` (`caErrorPlugin({ scaffold: true, theme, locale: "pt-BR" })`; default `en`, with a build warning until you set it). The result is the setup below, which you can also write by hand.

### Full setup

1. **Register both Vite plugins.** `caThemePlugin` bundles the ESM-only dependencies for SSR (`@tanstack/svelte-table`, `shiki`) and warns at build time if the theme script is not injected. `caErrorPlugin` creates the error pages when they are missing (`scaffold: true`), or only warns without it. Import the theme **with its `.ts` extension**: Vite loads the config with Node's native loader, which does not resolve extensionless imports (Vite 8 warns about it). That needs `"allowImportingTsExtensions": true` in `tsconfig.json`; SvelteKit's generated base config already sets it.

```ts
// vite.config.ts
import { sveltekit } from "@sveltejs/kit/vite";
import { caErrorPlugin, caThemePlugin } from "@codeatlasdev/ui/vite";
import { defineConfig } from "vite";
import { theme } from "./src/lib/theme.ts";

export default defineConfig({
  plugins: [sveltekit(), caThemePlugin(theme), caErrorPlugin({ scaffold: true, theme })],
});
```

2. **Inject the theme script and sanitize server errors in the server hook.** `caThemeHandle` puts the brand presets and the init script right after `<head>` of every SSR and prerendered page, so the first paint already has the right scheme and preset. `createErrorHandler` turns every unexpected server error into `{ message, code, id }` without leaking the message of a 5xx; [pass a `locale` or a `report` callback](/docs/getting-started/i18n/#server-errors) when you need them.

```ts
// src/hooks.server.ts
import { sequence } from "@sveltejs/kit/hooks";
import { caThemeHandle, createErrorHandler } from "@codeatlasdev/ui/kit";
import { theme } from "$lib/theme";

export const handle = sequence(caThemeHandle(theme));
export const handleError = createErrorHandler();
```

3. **Define the theme once.** Both the hook and the plugin take the same object. An empty object is valid and gives you the built-in amber preset in dark mode.

```ts
// src/lib/theme.ts
import type { ThemeOptions } from "@codeatlasdev/ui/vite";

export const theme: ThemeOptions = {
  defaultScheme: "system",
};
```

4. **Import the stylesheet and start the store in the root layout.**

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import "@codeatlasdev/ui/styles/global.css";
  import { colorScheme } from "@codeatlasdev/ui";
  import { onMount } from "svelte";

  let { children } = $props();
  onMount(() => colorScheme.init());
</script>

{@render children()}
```

5. **Set the viewport meta in `src/app.html`.** See [Mobile](/docs/getting-started/mobile/) for what each part does.

```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
```

Neither plugin depends on where it sits in `plugins`. `caThemePlugin` is `enforce: "pre"`, so Vite runs it first wherever you put it, and it looks for SvelteKit in the resolved plugin list, not in the array you wrote. `caErrorPlugin` only reacts to `configResolved`, `buildStart` and the dev server start. Checked with SvelteKit 3.0.1 and Vite 8.3: building with `caThemePlugin` and `caErrorPlugin` before, after and around `sveltekit()` gives the same result (theme script injected, error pages scaffolded, `ssr.noExternal` set), and in plain Vite `caThemePlugin()` before or after `svelte()` injects the script once, in build and in dev. The examples differ (after `sveltekit()`, before `svelte()`) only by convention; `init` follows the SvelteKit one.

If you cannot use a hook, paste the script into `src/app.html` instead. `CA_THEME_SCRIPT_TAG` from `@codeatlasdev/ui/vite` is a ready-to-paste tag for the default theme; for a custom theme, use the hook.

### SvelteKit 3

Kit 3 changed three things this setup touches. `init` handles the third (the theme import in the hook) and, for the other two, prints a `note` line instead of rewriting `svelte.config.js` or `tsconfig.json`: it reports `svelte.config.js`/`.ts`/`.mjs` when one exists, and a `tsconfig.json` that does not mention `$app/tsconfig`. On a clean Kit 3 run you get no `Done.` line while a note is pending.

1. **Configuration moves into the Vite plugin.** `svelte.config.js` is ignored (`config_file_unsupported`) and the `kit` namespace is gone (`config_kit_namespace`). Pass the options directly to `sveltekit()`, next to the two plugins:

```ts
// vite.config.ts
import adapter from "@sveltejs/adapter-auto";
import { sveltekit } from "@sveltejs/kit/vite";
import { caErrorPlugin, caThemePlugin } from "@codeatlasdev/ui/vite";
import { defineConfig } from "vite";
import { theme } from "./src/lib/theme.ts";

export default defineConfig({
  plugins: [sveltekit({ adapter: adapter() }), caThemePlugin(theme), caErrorPlugin({ scaffold: true, theme })],
});
```

2. **`tsconfig.json` extends `$app/tsconfig`.** `.svelte-kit/tsconfig.json` is no longer generated (`tsconfig_extends_missing`):

```json
{ "extends": "$app/tsconfig" }
```

3. **`$lib` is removed** (`module_removed_lib`). Use the `#lib/*` import that `sv create` adds to `package.json` (`"imports": { "#lib/*": "./src/lib/*" }`), written with the extension. In the hook, import the theme as `#lib/theme.ts`:

```ts
// src/hooks.server.ts
import { theme } from "#lib/theme.ts";
```

   Without a `#lib` map, use a relative path (`./lib/theme.ts` from `src/hooks.server.ts`). Everything else (the layout, the stylesheet import, `colorScheme.init()` and the viewport meta) is identical to Kit 2.

## Astro

Use the integration together with `@astrojs/svelte`. `caUI` injects the theme into the `<head>` of every page and handles the SSR bundling. `bunx @codeatlasdev/ui init` sets this up for an Astro project:

| File | What `init` puts there | If the file exists |
|---|---|---|
| `src/theme.ts` | the shared `theme` object (`defaultPreset: "amber"`, `defaultScheme: "system"`) | left alone |
| `astro.config.mjs` (or `.ts`, `.js`, `.mts`) | `caUI(theme)` and `svelte()` first in `integrations`, with their imports | adds each one unless `caUI(` / `svelte(` is already there; reports `manual` when there is no `integrations: [` array. `init` cannot install `@astrojs/svelte`: when it is not in `package.json` it prints a `note` to run `npx astro add svelte` |
| the first `.astro` file in `src/layouts` that renders `<html>` | the stylesheet import, the viewport meta and a client `<script>` that calls `colorScheme.init()` | adds only what is missing; reports `manual` when there is no `</body>` for the script |
| `src/layouts/Base.astro` | created only when `src/layouts` has no layout that renders `<html>` | not applicable |

```sh
bun add @codeatlasdev/ui @astrojs/svelte svelte
```

```js
// astro.config.mjs
import svelte from "@astrojs/svelte";
import { caUI } from "@codeatlasdev/ui/astro";
import { defineConfig } from "astro/config";
import { theme } from "./src/theme.ts";

export default defineConfig({ integrations: [svelte(), caUI(theme)] });
```

```ts
// src/theme.ts
import type { ThemeOptions } from "@codeatlasdev/ui/astro";

export const theme: ThemeOptions = { defaultPreset: "amber", defaultScheme: "system" };
```

Import the stylesheet once in your base layout, add the viewport meta and start the store from a client script, so theme switches and OS scheme changes stay in sync on the page:

```astro
---
// src/layouts/Base.astro
import "@codeatlasdev/ui/styles/global.css";
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
    <title>My app</title>
  </head>
  <body>
    <slot />
    <script>
      import { colorScheme } from "@codeatlasdev/ui";
      colorScheme.init();
    </script>
  </body>
</html>
```

Components are Svelte islands. Add a client directive to anything interactive (`client:visible` or `client:load`); purely visual components render on the server with no JavaScript. Call `colorScheme.init()` once per page, from that layout script or from one island that is always present.

With `<ClientRouter />` (View Transitions) the theme survives navigation: `caUI` copies the injected `<style id="ca-theme">`, the runtime tokens, the `theme-color` meta and the `data-preset`, `data-style`, `data-ca-scheme`, `data-ca-style` attributes and the `dark` class onto each incoming page before Astro swaps it in. Nothing to configure.

Astro needs `astro` 5, 6 or 7 as a peer. Components that read `colorScheme` render correctly on the server because the init script sets `class="dark"` and `data-preset` before the stylesheet applies.

## Plain Vite

`caThemePlugin` also works without SvelteKit: it injects the theme head through `transformIndexHtml`.

```ts
// vite.config.ts
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { caThemePlugin } from "@codeatlasdev/ui/vite";
import { defineConfig } from "vite";

export default defineConfig({ plugins: [caThemePlugin(), svelte()] });
```

```ts
// src/main.ts
import "@codeatlasdev/ui/styles/global.css";
import { colorScheme } from "@codeatlasdev/ui";
import { mount } from "svelte";
import App from "./App.svelte";

colorScheme.init();
mount(App, { target: document.getElementById("app")! });
```

## Verify

```svelte
<script>
  import { Button, ThemeToggle } from "@codeatlasdev/ui";
</script>

<Button variant="filled">It works</Button>
<ThemeToggle />
```

Reload with the toggle on dark and check that there is no white flash. Continue with [Theming](/docs/getting-started/theming/).

---

# Theming

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/theming/

Define a theme with defineTheme, derive a brand preset from one hex color, switch schemes and surface styles, and override tokens through the cascade.

A theme is a plain object. The library compiles it to CSS once at build time (the same object always gives the same CSS) and injects it before any stylesheet, so there is no per-render style work and no flash.

```ts
// src/lib/theme.ts
import type { ThemeOptions } from "@codeatlasdev/ui/vite";

export const theme: ThemeOptions = {
  presets: [{ id: "acme", color: "#2563eb" }],
  defaultPreset: "acme",
  defaultScheme: "system",
  defaultStyle: "solid",
  fonts: { body: "Geist, system-ui, sans-serif" },
  radius: 0.8,
  density: "comfortable",
  overrides: { light: { "--ca-card-padding": "16px" } },
};
```

Pass the same object to `caThemeHandle` and `caThemePlugin` (SvelteKit), `caUI` (Astro) or `themeHead` (custom setups), see [Installation](/docs/getting-started/installation/). `ThemeOptions` is `Partial<ThemeDefinition>`, so every field is optional.

## Options

| Option | Default | Description |
|---|---|---|
| `presets` | `[]` | Brand presets generated from a hex color. Built-in presets are always available. |
| `defaultPreset` | `"amber"` | Preset used until the user picks one. Must be a built-in or one of `presets`. |
| `defaultScheme` | `"dark"` | `"light"`, `"dark"` or `"system"`. `bunx @codeatlasdev/ui init` scaffolds `"system"`. |
| `defaultStyle` | `"solid"` | Surface material: `"solid"`, `"flat"`, `"frosted"`, `"glass"`, `"outlined"`, `"neumorphic"`, `"clay"`, `"tonal"` or `"chrome"`. Solid is the sober default; glass is the opt-in [`liquid`](#the-liquid-recipe) look. |
| `fonts` | `{}` | `body`, `mono` and `display`. Each is a font stack string or a self-hosted font descriptor (`@font-face`, preload, metric-matched fallback), see [Performance](/docs/getting-started/performance/#fonts). They set `--ca-font-sans`, `--ca-font-mono` and `--ca-font-display`. |
| `radius` | `0.8` | Multiplier applied to the `--ca-radius-xs` to `--ca-radius-xl` scale (`0.8` makes `--ca-radius-md` 8px) and to `--ca-radius-round`, so `0` also squares swatches, active pips, dots and chips. |
| `density` | `"comfortable"` | `"compact"` (0.75), `"comfortable"` (1), `"airy"` (1.25) or a number. Scales the `--ca-space-*` tokens, so padding, gaps and page spacing follow. |
| `paper` | `"plain"` | Page background: `"plain"`, `"mesh"` (brand glow, drawn by the `glass` and `frosted` styles), `"grid"`, `"dots"` or `"lines"`. Flat patterns are drawn in `--ca-outline-subtle`, so they follow the preset and scheme. |
| `iconStroke` | `1.75` | Lucide stroke width. |
| `controlRadius` | `"md"` | Corner role of buttons, fields and chips: `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"` or `"pill"`. |
| `border` | `{ width: 1, strong: 2 }` | Border weights in px (`--ca-border-width`, `--ca-border-width-strong`). |
| `elevation` | `"soft"` | How shadows are drawn: `"soft"`, `"none"`, `"hard"` (offset, no blur) or `"glow"`. |
| `typography` | `{}` | `scale`, `weights` (`heading` defaults to `600`), `headingTracking`, `headingCase`, `labelTracking`, `labelCase`, `lineHeight` and `measure`. |
| `motion` | `{}` | `scale` (multiplier on every duration), `easing` (`"standard"`, `"emphasized"`, `"spring"`, `"linear"` or `"steps"`) and `enter` (`"default"` or `"none"`). `enter: "none"` makes dialogs, drawers, sheets, menus, popovers, tooltips and toasts appear and leave in place while hover and focus color transitions keep `scale` (it sets `--ca-enter-scale: 0`); `MotionStage` demos render their final state. |
| `noise` | `0` | Film-grain over the page background, from `0` to `0.12`. |
| `overrides` | `{}` | Raw `--ca-*` token overrides, per scheme (`light`, `dark`). Prefer preset role colors (below) for palettes. |

`defineTheme(options)` resolves the options (defaults, validation) and `themeCSS(resolved)` returns the CSS string. You rarely call them yourself; the integrations do. Invalid input fails the build: a preset `id` that clashes with a built-in, a color that is not `#rrggbb`, or a `defaultPreset` that does not exist.

## Presets

Eight OKLCH presets ship with the package: `amber`, `ocean`, `crimson`, `cyan`, `violet`, `emerald`, `rose` and `slate`. One attribute switches the whole app:

```html
<html data-preset="ocean" class="dark">
```

In code, use the store:

```ts
import { colorScheme } from "@codeatlasdev/ui";

colorScheme.setPreset("violet");
colorScheme.presets; // every valid id: built-ins plus your brand presets
```

### Brand preset from a hex color

Give the library your logo color and it derives hue, chroma and lightness in OKLCH, then emits the complete light and dark token set (brand, surfaces, text, outlines, glass tints). Charts use the hex as their first series color.

```ts
export const theme: ThemeOptions = {
  presets: [{ id: "acme", color: "#2563eb", label: "Acme" }],
  defaultPreset: "acme",
};
```

Values stored by the user that your theme does not know are discarded and removed from storage. If you rename or delete a brand preset, returning users fall back to `defaultPreset` instead of seeing a broken theme.

### Porting a palette by role

To bring an existing palette (a terminal or editor theme) into a preset, set role colors per scheme. Unset roles keep the generated value; a per-scheme `brand` regenerates that scheme's brand ramp, and `background` also drives `<meta name="theme-color">`. Roles are scoped to the preset, so switching presets and theme islands keep working.

```ts
presets: [{
  id: "tokyo",
  color: "#7aa2f7",
  colors: {
    light: { brand: "#34548a" },
    dark: { background: "#1a1b26", surface: "#232430", text: "#c0caf5", border: "#565f89", error: "#f7768e" },
  },
}],
```

Roles: `brand`, `background`, `sunken`, `surface`, `overlay`, `text`, `textSecondary`, `textHint`, `textDisabled`, `borderSubtle`, `border`, `borderStrong`, `success`, `warning`, `info`, `error`. Check contrast after overriding text or surfaces: the generated palette guarantees AA, hand-picked colors are yours to verify.

### Sketchbook style and hand-drawn marks

`designStyle("sketchbook", { ... })` is a journal look: grid paper, serif display, square outlined cards with hard shadows. It pairs with the opt-in marks stylesheet:

```ts
import "@codeatlasdev/ui/styles/marks.css";
```

```html
<span class="ca-mark-underline">already knows.</span>
<p class="ca-mark-note">A margin note with a sketched arrow.</p>
```

Marks are SVG masks painted with `--ca-mark-color` (brand by default); swap the shapes with `--ca-mark-scribble` and `--ca-mark-arrow`. In forced-colors mode they paint in `CanvasText`.

## Schemes

`defaultScheme: "system"` follows the operating system, including live changes while the page is open. The init script also keeps `<meta name="theme-color">` in sync with the preset's surface color.

```ts
colorScheme.preference; // "light" | "dark" | "system"
colorScheme.resolved;   // "light" | "dark" (system already resolved)
colorScheme.isDark;     // boolean
colorScheme.setPreference("system");
colorScheme.toggle();   // flips resolved light and dark
```

## Surface styles

`data-style` on `<html>` swaps the material of every surface at once.

| Style | Look |
|---|---|
| `solid` | Default. No blur, opaque surfaces, plain page, hairline edges, no glow. Keeps soft neutral shadows. |
| `flat` | No blur, no mesh, no glow, no drop shadows: separation comes from borders. |
| `frosted` | Less blur, calmer mesh background. |
| `glass` | Liquid Glass: strong blur and saturation, translucent tints, brand mesh, glow and rim light. Opt-in. |
| `outlined` | Border-defined opaque surfaces with no elevation. Used by the `swiss`, `brutalism`, `terminal` and `sketchbook` recipes. |
| `neumorphic` | One base color extruded by paired light and dark shadows. Low contrast: use it for showcases, not dense data UIs. |
| `clay` | Soft, inflated opaque surfaces. |
| `tonal` | Surfaces tinted with the brand hue and soft elevation (Material 3 style). |
| `chrome` | Glossy gradient with a metallic rim and brand glow. Blur stays on. |

```ts
colorScheme.setStyle("glass");
```

### The liquid recipe

Earlier versions looked like Liquid Glass: glass surfaces over a three-hue mesh, glow on selected states, round corners (10px controls), 2px icons, bold headings and hue-tinted shadows. That look is now the opt-in `liquid` recipe:

```ts
import { designStyle } from "@codeatlasdev/ui/vite";
import type { ThemeOptions } from "@codeatlasdev/ui/vite";

export const theme: ThemeOptions = designStyle("liquid", {
  presets: [{ id: "acme", color: "#2563eb" }],
  defaultPreset: "acme",
  defaultScheme: "dark",
});
```

`designStyle("default")` is the sober default. `designStyle`, `DESIGN_STYLES` and `mergeTheme` are plain data, so a `theme.ts` shared with `vite.config` imports them in Node from `@codeatlasdev/ui/vite` (`@codeatlasdev/ui/astro` exports them too). The root and `@codeatlasdev/ui/kit` also export them, but they pull in Svelte files that `vite.config` cannot load. To migrate an app that relied on the old defaults, use `designStyle("liquid", { ... })`, or set `defaultStyle: "glass"` yourself.

### Other design styles

`DESIGN_STYLES` maps each id to `{ id, label, description, taxonomy, theme }`. `designStyle(id, overrides)` returns that recipe's `theme` with your overrides merged on top, and `mergeTheme(a, b)` merges two partial themes (`b` wins). The ids are `default`, `liquid`, `swiss`, `brutalism`, `neumorphism`, `glassmorphism`, `material`, `fluent`, `apple`, `bento`, `claymorphism`, `y2k`, `editorial`, `terminal` and `sketchbook`. Each recipe only sets the design knobs from the options table (material, radius, border, elevation, typography, motion, icon stroke, paper).

Users on `prefers-reduced-transparency: reduce` get opaque surfaces regardless of the style.

## The colorScheme store

Call `colorScheme.init()` once in the root layout (inside `onMount`). It re-applies the state to `<html>`, follows OS scheme changes and keeps the browser chrome color in sync. It is idempotent and returns a cleanup function.

| Member | Description |
|---|---|
| `preference`, `resolved`, `preset`, `style`, `isDark`, `presets` | Reactive getters (Svelte 5 `$state`). |
| `setPreference(pref)`, `toggle()` | Change the scheme. |
| `setPreset(id)`, `setStyle(style)` | Change preset or surface style. |
| `setTokens(vars)` | Runtime token overrides, see below. |
| `init()` | Start listeners. Returns cleanup. |

All choices persist in `localStorage` (`ca-scheme`, `ca-preset`, `ca-style`). Storage errors in private mode are ignored, and the values are validated against the theme before use.

### Runtime tokens

`setTokens` writes your `--ca-*` variables to a single `<style id="ca-runtime-tokens">`, persists them and replays them in the init script before first paint. Use it for user-defined themes such as an imported editor theme. Keys must match `--ca-*`; values containing `{`, `}`, `<` or `;` are dropped.

```ts
colorScheme.setTokens({ "--ca-brand-main": "#ff5500", "--ca-radius-md": "14px" });
colorScheme.setTokens({}); // clear
```

## Theme islands

Put `data-theme-scope="light"` or `"dark"` on any element to re-apply that scheme's tokens inside it, regardless of the page scheme. Useful for a dark hero on a light page or a light preview inside a dark editor.

```svelte
<section data-theme-scope="dark">
  <!-- dark tokens here, on any page -->
</section>
```

Add `data-preset` to switch the palette as well, on the same element or on a wrapper. The nearest preset wins, even when the page uses your brand preset:

```svelte
<div data-preset="violet">
  <section data-theme-scope="dark"><!-- violet, dark --></section>
</div>
```

Islands also feed the browser chrome color when they touch the top edge, see [Mobile](/docs/getting-started/mobile/#browser-chrome-color).

## Cascade and overriding tokens

`global.css` declares its layers up front:

```css
@layer ca.reset, ca.tokens, ca.themes, ca.base, ca.materials, ca.utilities, ca.components;
```

Every component stylesheet is wrapped in `@layer ca.components`, the last kit layer. Your app CSS is **unlayered**, and unlayered rules beat every layer regardless of specificity or import order. Overriding therefore never needs `!important` or a doubled class, for tokens and for component rules alike:

```css
/* app.css: no !important, no .ca-btn.ca-btn */
:root {
  --ca-card-padding: 16px;
  --ca-radius-lg: 18px;
}
.ca-btn:disabled { opacity: 0.3; }
.ca-tf__wrap { border-radius: 4px; }
.ca-dialog__body { padding: 0; }
```

`ca.reset` is the first layer and holds one rule: `button, input, select, textarea { font: inherit }`, so native controls use the page font instead of the browser's (Arial on Chromium/Windows). Every component and every app rule outranks it.

If your own CSS lives in a layer (for example Tailwind's `@layer components`), declare it after the kit's order statement so it ranks higher: `@layer ca.reset, ca.tokens, ca.themes, ca.base, ca.materials, ca.utilities, ca.components, app;`.

A declaration marked `!important` inside a layer outranks an unlayered normal one. The kit therefore avoids `!important` in component CSS; the few left only beat inline styles the component sets itself (the indeterminate Progress width, the AppShell content margin while the sidebar animates), `prefers-reduced-motion`, and the focus ring in `base.css`. To override one of those, use `!important` in your own unlayered rule.

For per-scheme overrides prefer `overrides` in the theme object, which is emitted for both `:root` and theme islands.

The `ca-*` BEM classes (`.ca-btn`, `.ca-dialog__body`, ...) are public API. Targeting them from app CSS is supported, and renaming one is a breaking change.

## Dialogs, drawers and the scrim

Since 2.0.0 (the release that dropped bits-ui) `.ca-overlay` is the modal `<dialog>` itself, not a separate backdrop element. Dialog, AlertDialog, Drawer, Sheet, CommandPalette and DocsSearch all render `dialog.ca-overlay`, the panel classes (`.ca-dialog`, `.ca-drawer`, ...) place it, and the scrim is its `::backdrop`. A rule written for the old overlay element now paints the panel:

```css
/* before: darkened the scrim element. now: makes every dialog and drawer see-through */
.ca-overlay { background-color: rgb(0 0 0 / .3); backdrop-filter: none; }
```

Style the scrim through its two tokens, or target the pseudo-element:

```css
:root {
  --ca-scrim-color: rgb(0 0 0 / .3);
  --ca-scrim-blur: none; /* default: blur(4px) saturate(180%) */
}
/* or, for a single rule */
dialog.ca-overlay::backdrop { background: rgb(0 0 0 / .3); }
```

`--ca-scrim-color` is set per preset and scheme; `--ca-scrim-blur: none` drops the blur on every modal at once. Search your app CSS for `.ca-overlay` when upgrading from 1.x and move each rule to `::backdrop` (scrim) or to the panel class (`.ca-dialog`, `.ca-drawer`) if it was meant for the surface.

## Do not break the glass

Two CSS properties silently kill `backdrop-filter` on glass surfaces:

- `will-change: transform` on the same element or an ancestor.
- `position: absolute` children inside an `isolation: isolate` parent.

Keep `backdrop-filter` on the element that composites directly against the page.

---

# Mobile

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/mobile/

Safe areas, dynamic viewport height, the on-screen keyboard, the iOS keyboard pattern, browser chrome color and the mobile layout components.

The package is built so apps feel native in Safari and Chrome on phones. Most of it is automatic once `global.css` is imported; this page lists what you need to set up and what each piece does.

## Viewport meta

```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
```

| Part | Why |
|---|---|
| `viewport-fit=cover` | Draws under the notch and home indicator. Required for the safe-area tokens to be non-zero. |
| `interactive-widget=resizes-content` | On Chromium the on-screen keyboard resizes the layout viewport instead of overlaying it. |

Never add `maximum-scale` or `user-scalable=no`. Zoom is an accessibility feature, and the package avoids iOS focus zoom a different way (see [Input font size](#input-font-size)).

## Safe areas and viewport height

`tokens.css` exposes the environment insets and a height that works everywhere:

| Token | Value |
|---|---|
| `--ca-safe-top`, `--ca-safe-right`, `--ca-safe-bottom`, `--ca-safe-left` | `env(safe-area-inset-*, 0px)` |
| `--ca-vh` | `100vh`, upgraded to `100dvh` where supported. Use it instead of a literal `100vh` or `100dvh`. |
| `--ca-kb-inset` | Height covered by the on-screen keyboard, `0px` when closed. Written by the viewport store. |
| `--ca-touch-target` | `44px`, applied to controls under `(pointer: coarse)`. |
| `--ca-chrome-surface` | Opaque surface for bars that touch a screen edge, see [below](#browser-chrome-color). |

```css
.fullscreen-panel {
  position: fixed;
  inset: 0;
  height: var(--ca-vh);
  padding: var(--ca-safe-top) var(--ca-safe-right) var(--ca-safe-bottom) var(--ca-safe-left);
}
```

## The on-screen keyboard

`viewport.keyboardInset` is the number of pixels of the layout viewport covered by the virtual keyboard. It is computed from `visualViewport` against `document.documentElement.clientHeight`, never from `window.innerHeight`: on iOS `innerHeight` changes with the URL bar, which would read as a phantom keyboard. Changes under 80px (browser toolbars) and pinch zoom are ignored. The store mirrors the value to `--ca-kb-inset` on `<html>`.

```svelte
<script>
  import { viewport } from "@codeatlasdev/ui";
  import { onMount } from "svelte";

  onMount(() => viewport.init()); // returns cleanup
</script>

{viewport.keyboardInset > 0 ? "keyboard open" : "keyboard closed"}
```

For most cases use the `keyboardAware` action, which starts the store for you. It pads the element's bottom by `--ca-kb-inset` and scrolls the focused field back into view when the keyboard resizes the viewport:

```svelte
<script>
  import { keyboardAware } from "@codeatlasdev/ui/actions";
</script>

<form use:keyboardAware>
  <textarea></textarea>
  <button>Send</button>
</form>
```

`StickyActions` and `MobilePane` already use it.

## Opening the keyboard on iOS

iOS Safari only opens the keyboard for a `focus()` call made synchronously inside a user gesture. Focus moved later (on mount, in `requestAnimationFrame`, after a transition) lands on the field without a keyboard and makes Safari scroll and zoom toward it. The package ships a small pattern for dialogs, sheets and search overlays:

1. In the tap handler, call `primeKeyboard()`. It focuses an invisible 16px proxy input so the keyboard opens. It does nothing on devices without a coarse pointer.
2. In the opened view, mark the real field with `use:autofocus` or call `focusTextField(el)`. iOS keeps the keyboard up while focus moves between text fields.

```svelte
<script>
  import { autofocus, primeKeyboard } from "@codeatlasdev/ui/actions";
  import { Button, Dialog } from "@codeatlasdev/ui";

  let open = $state(false);
</script>

<Button onclick={() => { primeKeyboard(); open = true; }}>Search</Button>

<Dialog bind:open title="Search">
  <input use:autofocus placeholder="Type to search" />
</Dialog>
```

On a touch device, `autofocus` and `focusTextField` only focus when the keyboard was primed in the opening gesture, so a field is never half-focused without a keyboard. Pass `{ touch: true }` (or `force` to `focusTextField`) to focus anyway, for example with a hardware keyboard. `DocsShell`, `Combobox` and `CommandPalette` use this pattern internally.

## Input font size

Safari zooms the page when a focused field computes under 16px. `base.css` raises every text-entry control (`input` except checkbox, radio, range, file, color and hidden, plus `textarea`, `select` and `[contenteditable]`) to `max(16px, 1em)` under `(pointer: coarse), (max-width: 899.98px)`, with zero specificity (`:where()`) so an app can still opt a field out. Package controls read `--ca-input-font-size`, which does the same under that query. In your own fields, use the token:

```css
.my-field input {
  font-size: var(--ca-input-font-size);
}
```

## Browser chrome color

Mobile browsers tint their status bar and toolbar from the page. The package feeds each engine what it reads:

- `<html>` has a solid background. `base.css` sets `html { background-color: var(--ca-surface-base) }` and keeps `body` transparent. The decorative mesh (drawn only by the `glass` and `frosted` styles, or by `paper: "mesh"`) lives in `body::before`, because browsers sample the real background and never pseudo-elements. The same color shows in the overscroll area.
- `--ca-chrome-surface` is opaque. `MobileHeader` and `BottomNav` use it as `background-color`, so the strip under the notch and the home indicator matches the bar.
- `<meta name="theme-color">` follows what is painted. The init script sets it from the preset before first paint. After `colorScheme.init()`, a small sync keeps it equal to the opaque color under the top edge of the screen: an opaque header, a [theme island](/docs/getting-started/theming/#theme-islands) or the page itself. It re-samples on theme and DOM changes, scroll, resize and when the tab returns to the foreground. This is what Chrome and Samsung Internet on Android, Safari 18 and earlier, and installed PWAs use.
- Safari 26 ignores `theme-color` and instead samples the background of the root and of fixed or sticky elements at the screen edges. Because those are solid colors, both paths show the same result.

A translucent glass header at the top edge cannot be sampled correctly. Use `--ca-chrome-surface` (or any opaque color) for fixed bars on the top and bottom edges, and keep `backdrop-filter` for surfaces inside the page.

## Layout components

### BottomNav and AppShellLayout

Below 900px `AppShellLayout` swaps the Rail and Panel for a `MobileHeader` and a `BottomNav` (up to five modules). The bar is `--ca-bottom-nav-h` (56px) plus `--ca-safe-bottom`, and the content area reserves exactly that space.

### MobilePane

A full-screen layer above the shell for drill-down views (chat thread, history, detail), instead of a hand-written `position: fixed`. It has a header with a back button, its own scroll with `overscroll-behavior: contain`, safe areas on every side and keyboard awareness. The back button and Escape set `open` to `false` and then call `onback`. Focus moves in on open and returns on close.

```svelte
<script>
  import { MobilePane, IconButton } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<MobilePane bind:open title="Maria" onback={() => console.log("closed")}>
  {#snippet actions()}<IconButton aria-label="More">…</IconButton>{/snippet}
  <Messages />
</MobilePane>
```

Use `scroll={false}` when the body has its own scroll area and a fixed composer (chat).

### StickyActions

A bar for form actions that sticks to the bottom of the scroll container, with glass chrome, safe-area padding and keyboard awareness. From 900px up it becomes an inline row with no chrome.

```svelte
<StickyActions align="stretch" show={dirty}>
  <Button variant="ghost">Cancel</Button>
  <Button variant="filled">Save</Button>
</StickyActions>
```

`align="end"` (default) pushes buttons to the right; `"stretch"` makes them fill the width on touch screens. `show` renders the bar only while there is something to confirm.

### Sheet

A bottom sheet below 900px and a centered dialog from 900px up. It keeps the focus trap, Escape, backdrop dismissal and scroll lock of the underlying dialog. In the bottom layout, dragging the handle or header down dismisses it (`swipeToDismiss`, default `true`). It closes past 30% of the sheet height or a release faster than 0.5 px/ms, otherwise it springs back, and the swipe is disabled when the user prefers reduced motion.

```svelte
<Sheet bind:open title="Switch account" description="Choose the active session">
  …
  {#snippet footer()}<Button fullWidth>New session</Button>{/snippet}
</Sheet>
```

### AuthLayout

Shows a brand strip when the side panel is hidden, below 900px (`mobileBrand`, default `true`). Do not build a local brand header for small screens.

## Native feel

`nativeFeel()` from `@codeatlasdev/ui/kit` makes an app shell behave like an app instead of a page. Call it once; it returns a cleanup function.

```ts
import { nativeFeel } from "@codeatlasdev/ui/kit";

onMount(() => nativeFeel());
```

It shows focus rings only while the user navigates with the keyboard (`html[data-kbd]`), removes the context menu and text selection on chrome (buttons, links, nav, header, tabs, menu items, options) while keeping them in fields and in `.ca-selectable` content (one class opts a region back into both the context menu and text selection; the old unprefixed `.selectable` is no longer recognized), and blocks dragging links and images. `blockZoom: true` also blocks page zoom, meant for desktop shells such as Tauri only: on the web, zoom is an accessibility feature.

Every element gets `touch-action: manipulation` and a transparent tap highlight from `base.css`. Under `(pointer: coarse)` the control heights (`--ca-control-height`) grow to 44px, and `Button` scales slightly on press under `(hover: none)` unless the user prefers reduced motion.

---

# Accessibility

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/accessibility/

What the components handle for you (focus, keyboard, labels, motion, transparency, contrast) and what stays your responsibility.

Interactive components run on a headless layer of our own that implements the WAI-ARIA Authoring Practices patterns: roles, keyboard handling, focus management and dismissal, using native elements (`<dialog>`, `<input>`, `<details>`) wherever the platform provides the behavior. The package adds tokens, motion and touch rules on top, and every component is tested with axe in a real browser.

*Credits: interaction patterns inspired by [Bits UI](https://bits-ui.com) and [Melt UI](https://melt-ui.com). See `NOTICE`.*

## What you get

| Area | Behavior |
|---|---|
| Focus ring | Every focusable component draws a 2px outline in `--ca-focus-ring` with a 2px offset. The generator solves the token per preset and scheme to keep 3:1 against every surface and the hover/selected fills; override the one token (never `--ca-brand-main`) to recolor all rings. Never remove it. |
| Overlays | Modal layers (`Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `CommandPalette`, `Lightbox`) are native `<dialog>` elements: the page behind is inert, focus is trapped and restored on close, Escape closes and page scroll is locked. Popovers and menus (`Popover`, `DropdownMenu`, `Select`, `Combobox`, date pickers) sit in the top layer without making the page inert: Escape or a press outside closes them and focus returns to the trigger. |
| Keyboard | Tabs, menus, selects, comboboxes, the command palette, date pickers, toggle groups and segmented controls follow their WAI-ARIA keyboard patterns. |
| Names | `IconButton` requires `aria-label` at the type level. Built-in strings (close, dismiss, copy, loading) come from the [i18n catalog](/docs/getting-started/i18n/), so they are announced in the active language. |
| Status | `Alert` uses `role="alert"`. `Toast` items use `role="status"` inside a polite live region. `Spinner` has `role="status"` with a label, `Progress` has `role="progressbar"` with `aria-valuenow`. `CopyButton` announces "Copied" through the shared [live region](#announcements). |
| Loading buttons | `Button` and `IconButton` with `loading` set `aria-busy`, keep their label and ignore clicks. When loading ends they announce "Finished loading". |
| Forms | `TextField` and the other fields link hint and error text with `aria-describedby` and set `aria-invalid` on error. Errors render with `role="alert"`. |
| Touch targets | Controls grow to 44px (`--ca-touch-target`) under `(pointer: coarse)`. |
| Zoom | The package never disables zoom. Fields are 16px on touch so iOS does not zoom on focus, see [Mobile](/docs/getting-started/mobile/#input-font-size). |
| Skip link | `AppShellLayout`, `DocsShell` and `AuthLayout` render a [`SkipLink`](#skip-link-and-landmarks) as the first focusable element and own the `#main` target. |
| Forced colors | Under `forced-colors: active` glass, blur and shadows are removed, surfaces get a `CanvasText` border and focus uses `Highlight`. |
| Increased contrast | Under `prefers-contrast: more`, `--ca-text-secondary`, `--ca-text-hint` and `--ca-outline-*` reach at least 7:1 (outlines 3:1 or more) in every built-in and brand preset. |

## Motion

When the user prefers reduced motion, `--ca-motion-scale` becomes `0`. Every duration token (`--ca-duration-fast`, `--ca-duration-base`, `--ca-duration-slow`, `--ca-duration-press`) is multiplied by it, so every token-driven transition is instant. Components with JavaScript-driven motion check the `reducedMotion` store: `Sheet` disables its swipe, `AppShellLayout` skips the panel spring and `SegmentedControl` turns off its indicator animation.

```ts
import { reducedMotion, reducedTransparency } from "@codeatlasdev/ui";

reducedMotion.init();       // start following the media query (returns cleanup)
reducedMotion.value;        // boolean, reactive
reducedTransparency.value;  // prefers-reduced-transparency
```

Use the duration tokens in your own CSS and your animations respect the setting for free:

```css
.panel {
  transition: transform var(--ca-duration-base) var(--ca-ease-standard);
}
```

## Visually hidden text

`.ca-sr-only` hides an element visually and keeps it in the accessibility tree: a 1px clipped box, absolutely positioned so it never affects layout. Use it for text only assistive tech needs: a table `<caption>`, a label for a control the design leaves unlabeled, an extra "(required)" cue.

```svelte
<table>
  <caption class="ca-sr-only">Invoices, newest first</caption>
  …
</table>
```

Do not use `display: none`, `visibility: hidden`, `hidden` or `aria-hidden` for this: they remove the element from the accessibility tree.

`.ca-sr-only--focusable` is for elements that must appear when they receive focus (skip links, a "jump to results" shortcut). It stays hidden until the element, or something inside it, is focused, then it returns to normal flow and your own styles decide how it looks.

```svelte
<a class="ca-sr-only ca-sr-only--focusable" href="#results">Skip to results</a>
```

Both live in the `ca.utilities` layer, so they are available wherever `global.css` or `core.css` is imported. The kit itself uses the class for the dialog and search titles, the required cue on `Select` and the month heading of the date pickers.

## Skip link and landmarks

`SkipLink` is the first tab stop of every page shell. It is hidden until focused, then jumps to `#main` and moves focus there (`tabindex="-1"`, no focus ring on the container).

| Shell | Who owns `#main` |
|---|---|
| `DocsShell`, `AuthLayout` | The shell: its own `<main id="main" tabindex="-1">`. |
| `AppShellLayout` | `<main id="main" tabindex="-1" class="ca-shell__content">`, the page landmark, so there is nothing to add. Pass `mainId={null}` when your page renders `<main id="main" tabindex="-1">` yourself: the content region becomes a plain `div`, never a second landmark. |
| `PageShell` | Nobody: it always sits inside a shell or a page that already has a `<main>`. |

Never put a second `id="main"` or a second `<main>` on a page. When a shell is embedded in a page that already has a skip link (a framed demo, a preview), pass `skipLink={false}` to `AppShellLayout`.

```svelte
<AppShellLayout {modules} {pathname}>
  <!-- the shell renders <main id="main">; render your own <main> only with mainId={null} -->
  <PageShell title="Users">…</PageShell>
</AppShellLayout>
```

## Announcements

`announce(message, politeness)` speaks a message through one shared, lazily created live region (a polite `role="status"` and an assertive `role="alert"` pair appended to `<body>`). Several components talking through separate regions step on each other; one region keeps messages ordered.

```ts
import { announce } from "@codeatlasdev/ui";

announce("3 results");                 // polite (default)
announce("Payment failed", "assertive");
```

In SvelteKit, mount `RouteAnnouncer` once in the root layout to announce client-side navigations (the new `document.title`, or the page `<h1>`):

```svelte
<script>
  import { RouteAnnouncer } from "@codeatlasdev/ui/kit";
</script>

<RouteAnnouncer />
```

## Forced colors and increased contrast

Windows High Contrast and other forced-color modes replace author colors with system colors. The package removes `backdrop-filter`, translucent tints and shadows there, draws surfaces with a 1px `CanvasText` border and uses `Highlight` for the focus ring, so nothing depends on a glass blur to be visible.

`prefers-contrast: more` raises the neutral tokens instead: text-secondary and text-hint to at least 7:1 and outlines to at least 3:1 on every surface, with a thicker focus ring. The values are generated per preset (built-in and brand presets from `defineTheme`), tinted with the preset hue.

## Reduced transparency

With `prefers-reduced-transparency: reduce`, every glass material (`glass-regular`, `glass-chrome`, overlays, panels, upload zones and glass buttons) drops `backdrop-filter` and renders on an opaque tint. Browsers without `backdrop-filter` support get the same near-opaque fallback, so text never sits on raw page content.

## Color contrast

Text tokens are tuned per preset and scheme:

- `--ca-text-primary` and `--ca-text-secondary` for body text.
- `--ca-text-hint` is the lowest readable tier and keeps 4.5:1. Use it for captions and helper text.
- `--ca-text-disabled` is for the label of disabled controls only, never for information (use `--ca-text-hint` to de-emphasise). It keeps 3:1 on every surface and on the disabled fill, so a disabled label stays legible. Disabled controls are drawn from tokens (`--ca-text-disabled`, `--ca-action-disabled-bg`, `--ca-outline-default`), never from `opacity`.
- `--ca-outline-control` is the edge of fields and controls (text field, select, checkbox box) and keeps 3:1 on every surface and on the 5% field tint (WCAG 1.4.11). `--ca-outline-subtle` is for dividers only.
- `--ca-focus-ring` and `--ca-state-indicator` (switch track, slider range, segmented thumb edge) keep 3:1 against every surface and the hover/selected fills.
- `--ca-semantic-error-contrast` is the text colour for `--ca-semantic-error-fill`, like `--ca-brand-contrast` for `--ca-brand-fill`. `defineTheme` derives it from a custom `colors.*.error`; if you set the fill yourself, set the contrast beside it.
- Menus, popovers and pickers (`--ca-overlay-bg`) and panels (`--ca-panel-bg`) are near-opaque (94% of `--ca-surface-overlay`) so their text contrast never depends on the page behind. The old see-through tint stays available as `--ca-overlay-bg-glass` / `--ca-panel-bg-glass` for decoration only.
- `--ca-brand-text` is brand-colored text that keeps contrast on the surface. Use `--ca-brand-fill` with `--ca-brand-contrast` for filled brand elements.

Brand presets generated from a hex color use the same generator, so they keep these relationships. Semantic colors (success, warning, error, info) are separated from the brand by luminance, not only hue, and should always be paired with an icon or text: color alone is never the only signal. `Alert` and `Toast` already include an icon.

Contrast of your own combinations is your responsibility. Check custom `overrides`, `setTokens` values and text placed over images or gradients.

## Writing accessible pages

- Give every page one `<h1>` and keep heading levels in order.
- Provide a skip link and a single `<main id="main" tabindex="-1">` landmark. `AppShellLayout`, `DocsShell` and `AuthLayout` already do (see [Skip link and landmarks](#skip-link-and-landmarks)); use `SkipLink` in shells you build.
- Label icon-only controls (`IconButton` enforces it) and give `Dialog`, `Sheet` and `Drawer` a `title`. Use `chromeless` dialogs with a `title` so the accessible name remains.
- Give `Select`, `Combobox` and the other fields a `label` prop. Without one, the control has no visible or programmatic name. For a `Combobox` with no visible label, pass `ariaLabel`.
- Do not put `will-change: transform` on glass surfaces. It breaks blur rendering, which also removes the contrast the tint was tuned for.
- Make clickable non-button elements real `<button>` or `<a>` elements.

## Testing

`@codeatlasdev/ui/testing` is the helper the library uses on its own components: axe-core run after animations settle, with the library's known exceptions. It takes any `Element` or `Document`, so it works in Vitest browser mode, Playwright component tests or any DOM test environment. `axe-core` is an optional peer dependency: install it where you import the helper.

```bash
bun add -d axe-core
```

```ts
import { render } from "vitest-browser-svelte";
import { expectNoA11yViolations } from "@codeatlasdev/ui/testing";

it("has no axe violations", async () => {
  const screen = await render(MyComponent);
  await expectNoA11yViolations(screen.container);
});
```

A violation rejects with the rule id, impact, help URL and every offending node. Run it in each state worth testing: open, error, empty, light and dark.

| Export | Returns | Description |
|---|---|---|
| `expectNoA11yViolations(target?, options?)` | `Promise<void>` | Rejects with a formatted report when axe finds violations. `target` defaults to `document`. |
| `checkA11y(target?, options?)` | `Promise<AxeResults>` | Runs axe and returns the raw results (violations only), for custom assertions. |
| `formatViolations(violations)` | `string` | The readable report used by `expectNoA11yViolations`. |
| `settled(timeout?)` | `Promise<void>` | Resolves once no finite CSS animation or transition is running. |
| `A11Y_EXCEPTIONS` | `RunOptions["rules"]` | The exceptions applied to every run: `region` is off, because a component rendered into an empty body is not a page. |

`options` is the axe `RunOptions`; its `rules` are merged over the exceptions, so `{ rules: { region: { enabled: true } } }` re-enables one. `axe.run` is not reentrant: never run two checks concurrently. Contrast needs real layout and styles, so run in a browser rather than jsdom.

To test whole pages (landmarks, heading order, `region`), run axe on your routes in light, dark and `forcedColors: "active"` with Playwright and `@axe-core/playwright`. Also test with a keyboard only and with a screen reader on at least one platform.

---

# Internationalization

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/i18n/

Every string the components render comes from a catalog. English is the default, Brazilian Portuguese ships built in, and any phrase can be overridden.

Every visible string the package generates (aria-labels, placeholders, empty states, "Copy", "On this page", toast and dialog buttons) comes from a message catalog. The default language is **English**; Brazilian Portuguese ships built in and any other language can be registered. There are two ways to choose the language.

## SSR apps: `I18nProvider`

On the server, wrap the tree in `I18nProvider`. The locale lives in Svelte context, so each request renders in its own language and concurrent requests never share state:

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import { I18nProvider } from "@codeatlasdev/ui";
  let { data, children } = $props();
</script>

<I18nProvider locale={data.locale}>
  {@render children()}
</I18nProvider>
```

`locale` is reactive: change the prop and every component inside re-renders. Pass `messages` to override phrases for that subtree (see below).

## Client-only apps: `setLocale`

SPAs and Astro islands have no per-request concern, so one module-level locale shared by every island is enough:

```svelte
<script>
  import { setLocale } from "@codeatlasdev/ui";

  setLocale("pt-BR");
</script>
```

On the server `setLocale` does nothing (and warns in dev), because module state would be shared by every concurrent request. Use `I18nProvider` in SSR layouts. An `I18nProvider` always wins over `setLocale`.

## Add a language

Locales are any BCP 47 tag. Register a dictionary once, at module load. You only translate the keys you need; the rest fall back to English:

```ts
// src/lib/i18n.ts
import { registerLocale } from "@codeatlasdev/ui";

registerLocale("es", {
  common: { close: "Cerrar", back: "Atrás" },
  docs: { toc: "En esta página" },
});
```

Then use it with `<I18nProvider locale="es">` or `setLocale("es")`. Region tags resolve to the base language (`es-MX` uses `es`), and unknown tags fall back to English. The exported `Messages` type describes the full shape and `MessagesOverride` the partial one.

## Override phrases

`I18nProvider`'s `messages` prop and `setLocale`'s second argument are a deep partial of the catalog, merged over the chosen locale:

```svelte
<I18nProvider locale="en" messages={{ docs: { toc: "In this article" }, common: { copy: "Copy link" } }}>
  {@render children()}
</I18nProvider>
```

A later `setLocale` call replaces the previous overrides. Message functions (strings with runtime values) keep their signature:

```ts
setLocale("en", {
  notificationBell: { label: (unread) => `Inbox, ${unread} new` },
});
```

## Explicit props win

A text prop always beats the catalog. Components that take text (`label`, `placeholder`, `confirmLabel`, `emptyText`, ...) fall back to the catalog only when the prop is omitted:

```svelte
<TableOfContents {headings} label="Neste artigo" />
```

## Reactive locale

With `setLocale`, the locale is shared module state, so every component and every island on the page re-renders when it changes. Read it with `locale.value`:

```svelte
<script>
  import { locale, setLocale } from "@codeatlasdev/ui";
</script>

<button onclick={() => setLocale(locale.value === "en" ? "pt-BR" : "en")}>
  {locale.value}
</button>
```

Inside an `I18nProvider`, read the active locale and messages from context with `useLocale()` and `useT()`, called at the top level of a component `<script>`:

```svelte
<script>
  import { useLocale, useT } from "@codeatlasdev/ui";
  const locale = useLocale();
  const t = useT();
</script>

<p lang={locale()}>{t().common.close}</p>
```

With Astro, each island is a separate Svelte app but they share the module, so one `setLocale` call in the first island that runs is enough. Call it before the islands that render text.

## Catalog

The catalog is grouped by component, for example `docs.search.placeholder`, `dialog.close`, `pagination.next`, `fileUpload`, `dataTable` and `toast`. Each group is its own module with its English source and its `pt-BR` translation (a missing key is a type error, and a test checks that both locales have identical keys). A component bundles only its own groups, so importing `Button` does not ship the strings of `CommandPalette` or `AppShell`. `useT()` and `getMessages()` return the full catalog and bundle all of it; use them only when you need strings outside a component.

## Server errors

`createErrorHandler` never reads global locale state. Give it the language of the fallback message, fixed or per request:

```ts
// src/hooks.server.ts
import { createErrorHandler } from "@codeatlasdev/ui/kit";

export const handleError = createErrorHandler({ locale: (event) => event.locals.locale as string });
```

## Dates, numbers and masks are separate

The UI language does not change date or number formatting. Pass `locale` to the components that format values, for example `DatePicker`, which defaults to `pt-BR`:

```svelte
<DatePicker locale="en-US" label="Start date" />
```

Formatting helpers such as `formatCurrency`, `formatDate` and `formatNumber` take their own locale too.

## In tests

The default is English. In browser tests, call `setLocale("pt-BR")` where a test asserts Portuguese text and reset with `setLocale("en")` in `afterEach`, so the module state does not leak between tests. In server-render tests, wrap the component in `I18nProvider` instead.

---

# AI agents

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/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`](/llms.txt) | Index: one line per documentation page with title, link and description. |
| [`/llms-full.txt`](/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](https://github.com/codeatlasdev/ui/blob/main/AGENTS.md) | `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](https://modelcontextprotocol.io) 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](/docs/getting-started/reporting/). |

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

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`](/api/v1/catalog.json), gallery: [`/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.

1. 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`.
2. 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.
3. 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:

```sh
/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](/docs/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:

```sh
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](/docs/getting-started/reporting/).

## Set up and migrate with the CLI

```sh
bunx @codeatlasdev/ui init
```

`init` detects SvelteKit or Astro and wires up what the [installation](/docs/getting-started/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.

```sh
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](/docs/getting-started/migrate-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:

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

`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

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

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

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

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

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](/docs/getting-started/accessibility/).

---

# Performance

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/performance/

Ship less CSS with per-preset imports, avoid layout shift with Image and metric-matched fonts, generate AVIF and WebP with enhanced-img, and animate without GSAP.

The package is tree-shakeable and its budgets are enforced in CI. This page covers what is yours to configure: which CSS you load, how images and fonts are delivered, and how to animate cheaply.

## CSS: load only the presets you use

`global.css` is the whole stylesheet: reset, tokens, base, materials, utilities, prose and all 8 built-in presets. Presets are generated and each one is a few kB of tokens, so an app that uses one preset can drop the rest.

| Entry | Contains |
|---|---|
| `@codeatlasdev/ui/styles/global.css` | Everything below, plus every built-in preset. The default, always safe. |
| `@codeatlasdev/ui/styles/core.css` | Reset, tokens, base, materials, utilities, prose and the default `amber` preset. |
| `@codeatlasdev/ui/styles/presets/<id>.css` | One built-in preset: `ocean`, `crimson`, `cyan`, `violet`, `emerald`, `rose` or `slate`. |

```ts
// +layout.svelte or your Astro base layout
import "@codeatlasdev/ui/styles/core.css";
import "@codeatlasdev/ui/styles/presets/ocean.css"; // only if the app can pick or default to ocean
```

`core.css` always carries `amber`, because its tokens are also the `:root` defaults. Brand presets declared in `defineTheme({ presets })` are not files: they are compiled into the inline `<style id="ca-theme">` that `caThemeHandle` and `caUI` emit, so they never cost an extra request.

A preset id that has no stylesheet loaded (for example `defaultPreset: "ocean"` with only `core.css`) falls back to the amber tokens. Import every built-in preset your `defaultPreset` and your preset picker can reach.

Cascade order is the same in every entry (`@layer ca.reset, ca.tokens, ca.themes, ca.base, ca.materials, ca.utilities, ca.components`), so splitting does not change which rule wins.

## JavaScript budget

`bun run size` in the package bundles each entry with esbuild (minified, ESM, tree-shaken) and fails when the gzip size passes the limit in `size-limit.json`. The limits are a ratchet: they only go down. Importing `Button` alone pulls the Svelte runtime, the button and its spinner, and the small i18n catalog; it does not pull the app shell, charts, tables or any other component. Heavy features stay behind subpath imports (`/charts`, `/table`, `/code`), so an app that does not use them never ships ECharts, TanStack Table or Shiki.

Import from the package root and let the bundler tree-shake:

```ts
import { Button, TextField } from "@codeatlasdev/ui"; // fine
import { LineChart } from "@codeatlasdev/ui/charts";   // loads ECharts only where used
```

## Images

Use the [`Image`](/docs/display/image/) component for every content image. It requires `width` and `height` so the layout does not move, lazy-loads by default and preloads the one `priority` image.

`Image` does not resize or re-encode files. For AVIF and WebP at build time use [`@sveltejs/enhanced-img`](https://svelte.dev/docs/kit/images#sveltejs-enhanced-img) in SvelteKit, and `astro:assets` in Astro:

</script>

<!-- enhanced-img emits a <picture> with AVIF/WebP/JPEG, srcset and width/height -->
<enhanced:img src={hero} alt="Dashboard overview" sizes="(min-width: 768px) 50vw, 100vw" />` },
{ label: "Astro", lang: "astro", code: `---
---

Rule of thumb: enhanced-img or `astro:assets` for photos and marketing art (they generate the formats), `Image` for images you already host in the right size (avatars from an API, user uploads behind a CDN that resizes) or when you want the package's dev warnings.

## Fonts

A web font causes two kinds of jank: the late swap that re-flows text, and the late request. The `fonts` option of the theme handles both. A font is either a plain stack string or a descriptor:

```ts
import type { ThemeOptions } from "@codeatlasdev/ui/vite";

export const theme: ThemeOptions = {
  fonts: {
    body: {
      family: "Inter",
      src: "/fonts/inter-var.woff2",
      weight: "100 900",
      preload: true,
      // Metric-matched fallback: Arial resized to Inter's proportions
      fallback: "Arial",
      fallbackMetrics: { sizeAdjust: 1.0447, ascent: "96.8%", descent: "24.1%", lineGap: "0%" },
    },
    mono: "ui-monospace, SFMono-Regular, Menlo, monospace", // strings still work
  },
};
```

| Field | Effect |
|---|---|
| `family`, `src`, `weight`, `style` | The `@font-face` rule. `src` is a woff2 URL; `weight` may be a variable range such as `"100 900"`. |
| `display` | `font-display`. Default `swap`: text shows at once in the fallback. |
| `preload` | `themeHead` (and so `caThemeHandle`) emits `<link rel="preload" as="font" type="font/woff2" crossorigin>` before any stylesheet. Use it only for fonts used above the fold. |
| `fallback`, `fallbackMetrics` | Declares `"<family> Fallback"` from a local system font with `size-adjust`, `ascent-override`, `descent-override` and `line-gap-override`, and puts it in the stack right after the web font. Text then takes the same space before and after the swap: no layout shift. |
| `generic` | The generic family at the end of the stack. Default `sans-serif`; use `monospace` or `serif` as needed. |

The resulting stack is `"Inter", "Inter Fallback", sans-serif`, assigned to `--ca-font-sans` (`body`), `--ca-font-mono` (`mono`) or `--ca-font-display` (`display`).

Get the metrics from the font's own tables. [Capsize](https://seek-oss.github.io/capsize/) and `fontaine` compute `sizeAdjust`, `ascent`, `descent` and `lineGap` for a font and a fallback.

`caUI` injects the theme from a head script, so its preload link is added after parsing starts. For the fastest start in Astro, also put the same `<link rel="preload">` in your layout `<head>`.

Self-host the files (same origin, long `Cache-Control`). The Google Fonts stylesheet is render-blocking and adds two connections; the [Fontsource](https://fontsource.org) packages give you the woff2 files without it.

## Motion without GSAP

Most UI motion needs neither GSAP nor a smooth-scroll library, and both cost more than the components they animate:

| Need | Use | Why |
|---|---|---|
| Enter, exit, hover, press | CSS transitions and `@keyframes`, with the `--ca-duration-*` and `--ca-ease-*` tokens | Runs on the compositor, zero JavaScript. |
| Sequenced or interrupted animation | The Web Animations API (`element.animate()`) | Native, cancellable, promise-based. |
| Reveal on scroll | `IntersectionObserver` (or CSS `animation-timeline: view()` where supported) | No scroll listeners, no layout reads. |
| Smooth scrolling | Native scrolling plus `scroll-behavior: smooth` for in-page anchors | A scroll-hijacking library fights the browser, adds input latency, and breaks `prefers-reduced-motion` and find-in-page. |
| Route transitions | View Transitions (`document.startViewTransition`, SvelteKit `onNavigate`) | The browser cross-fades screenshots; no per-element code. |

```ts
// Reveal once, no library
const io = new IntersectionObserver((entries) => {
  for (const e of entries) {
    if (!e.isIntersecting) continue;
    e.target.animate([{ opacity: 0, transform: "translateY(12px)" }, { opacity: 1, transform: "none" }], {
      duration: 320,
      easing: "cubic-bezier(0.2, 0, 0, 1)",
      fill: "both",
    });
    io.unobserve(e.target);
  }
}, { rootMargin: "0px 0px -10% 0px" });
document.querySelectorAll("[data-reveal]").forEach((el) => io.observe(el));
```

Always gate non-essential motion on `reducedMotion` from the package (or `@media (prefers-reduced-motion: reduce)`). The package's own components already do.

## Checklist

| Check | Where |
|---|---|
| Only the presets you reach are imported | [CSS](#css-load-only-the-presets-you-use) |
| One `priority` image, every image has `width` and `height` | [Images](#images) |
| Fonts self-hosted, above-the-fold font preloaded, fallback metrics set | [Fonts](#fonts) |
| No `will-change` on glass, no literal `100vh` | `bun run --cwd packages/ui lint:tokens` guards this in the package; follow the same rules in app CSS |
| Heavy features imported from subpaths | [JavaScript budget](#javascript-budget) |

---

# SEO

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/seo/

Head tags, structured data, sitemap, robots.txt, llms.txt, Markdown for AI crawlers and social images with the @codeatlasdev/ui/seo entry point.

`@codeatlasdev/ui/seo` covers what a public page needs to be found, shared and read by crawlers and AI assistants. It has no peer dependency beyond Svelte: the `Seo` component renders into `<svelte:head>` during SSR or prerender, and everything else is plain TypeScript that returns strings or objects. Nothing runs in the browser.

```ts
import {
  Seo, // component
  organization, website, softwareApplication, product, faqPage, breadcrumbList, article, graph, // JSON-LD
  sitemapXml, robotsTxt, // crawler files
  llmsTxt, markdownNegotiation, // AI readers
  ogImageRoute, ogCard, // social images
  iconLinks, // favicon, apple-touch-icon and manifest links
  manifest, appleMeta, // PWA (see the PWA page)
} from "@codeatlasdev/ui/seo";
```

## The Seo component

Place one `Seo` per page, in the route or layout that knows the page's data.

```svelte
<script>
  import { Seo, graph, organization, website } from "@codeatlasdev/ui/seo";
  import { page } from "$app/state";

  const origin = "https://acme.com";
</script>

<Seo
  title="Pricing"
  titleTemplate="%s · Acme"
  description="Plans for teams of any size."
  canonical={origin + page.url.pathname}
  og={{ image: `${origin}/og/pricing.jpg`, imageAlt: "Acme pricing", siteName: "Acme", locale: "en_US" }}
  twitter={{ site: "@acme" }}
  alternates={[
    { hreflang: "en", href: `${origin}/pricing` },
    { hreflang: "pt-BR", href: `${origin}/pt/pricing` },
    { hreflang: "x-default", href: `${origin}/pricing` },
  ]}
  jsonLd={graph(
    organization({ id: `${origin}/#org`, name: "Acme", url: origin }),
    website({ name: "Acme", url: origin, publisher: { "@id": `${origin}/#org` } }),
  )}
/>
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` | required | Page title, also used for og:title. |
| `titleTemplate` | `string` | '%s' | Wrapper for the title; %s is replaced. |
| `description` | `string` | - | Meta description, og:description and twitter:description. |
| `canonical` | `string` | - | Absolute URL of this page. Required on indexable pages; a dev warning fires without it. |
| `robots` | `string` | 'index,follow' | Content of the robots meta. |
| `noindex` | `boolean` | false | Shorthand for 'noindex,nofollow'. Use on admin, auth and app pages. |
| `alternates` | `{ hreflang: string; href: string }[]` | - | Translations, including the page itself and an x-default entry. |
| `og` | `{ type?, image?, defaultImage?, imageAlt?, imageType?, imageWidth?, imageHeight?, locale?, localeAlternates?, siteName? }` | - | Open Graph. `type` defaults to 'website', image size to 1200x630 and `imageType` to 'image/png' (set it to 'image/jpeg' for `ogImageRoute`, which renders JPEG by default). `defaultImage` is the site-wide card from the root layout; a page `image` replaces it. Without either, no image tag is written. |
| `twitter` | `{ card?, site? }` | - | `card` is summary_large_image when an og image is set, otherwise summary. `site` is the @handle. `twitter:title` and `twitter:description` always mirror the page title and description. |
| `jsonLd` | `object \| object[]` | - | Structured data. Serialized with '<' escaped, so values cannot close the script tag. |
| `manifest` | `string` | - | URL of the web app manifest. |
| `lang` | `string` | - | BCP 47 language of the page (`'pt-BR'`). Sets `og:locale` (`pt_BR`) unless `og.locale` is given and keeps `<html lang>` in sync on the client. The server-rendered `<html lang>` belongs in `app.html`. |

In development `Seo` warns when an indexable page has no `canonical`, and `caThemeHandle` warns once per problem when the final HTML has no `viewport-fit=cover`, a viewport meta that blocks zoom (`user-scalable=no`, `maximum-scale=1`) or no `lang` on `<html>`. Production builds stay silent.

## Structured data

The builders return plain objects with `undefined` fields removed. Give a node an `id` and reference it from others with `{ "@id": ... }`, then join everything with `graph()`.

| Builder | Use it for |
|---|---|
| `organization` | Company identity, logo, `sameAs` profiles. |
| `website` | Site root. `searchUrlTemplate: "https://acme.com/s?q={query}"` adds the sitelinks `SearchAction`. |
| `softwareApplication` | SaaS and app landing pages, with optional `offer` and `rating`. |
| `product` | Store pages: one or several `offers`, price, currency and availability. |
| `faqPage` | Question and answer lists that are visible on the page. |
| `breadcrumbList` | Trail from the root; omit `href` on the current page. |
| `article` | Blog posts and docs (`type: "BlogPosting" | "NewsArticle" | "TechArticle"`). |

```ts
import { product } from "@codeatlasdev/ui/seo";

product({
  name: "Ceramic mug",
  image: ["https://shop.example/mug.jpg"],
  brand: "Acme",
  offers: { price: 49.9, priceCurrency: "BRL", availability: "InStock" },
});
```

## Sitemap and robots.txt

Both are plain strings, meant for prerendered `+server.ts` routes.

```ts
// src/routes/sitemap.xml/+server.ts
import { sitemapXml } from "@codeatlasdev/ui/seo";

export const prerender = true;

export function GET() {
  const body = sitemapXml(
    ["/", "/pricing", "/docs"].map((path) => ({
      loc: `https://acme.com${path}`,
      lastmod: new Date(),
      alternates: [
        { hreflang: "en", href: `https://acme.com${path}` },
        { hreflang: "pt-BR", href: `https://acme.com/pt${path}` },
        { hreflang: "x-default", href: `https://acme.com${path}` },
      ],
    })),
  );
  return new Response(body, { headers: { "content-type": "application/xml" } });
}
```

```ts
// src/routes/robots.txt/+server.ts
import { robotsTxt } from "@codeatlasdev/ui/seo";

export const prerender = true;

export const GET = () =>
  new Response(robotsTxt({ sitemap: "https://acme.com/sitemap.xml", disallow: ["/app", "/admin"] }), {
    headers: { "content-type": "text/plain" },
  });
```

`sitemapXml` throws above 50,000 URLs, the protocol limit: split larger sites into a sitemap index.

## llms.txt and Markdown for AI

`llmsTxt` builds the [llms.txt](https://llmstxt.org) index: a title, a one-paragraph summary and link lists.

```ts
// src/routes/llms.txt/+server.ts
import { llmsTxt } from "@codeatlasdev/ui/seo";

export const prerender = true;

export const GET = () =>
  new Response(
    llmsTxt({
      title: "Acme",
      summary: "Invoicing for freelancers.",
      sections: [{ heading: "Docs", links: [{ title: "Quick start", href: "https://acme.com/docs/start", description: "Five minutes to the first invoice." }] }],
    }),
    { headers: { "content-type": "text/plain; charset=utf-8" } },
  );
```

`markdownNegotiation` is a SvelteKit `handle` that answers with `text/markdown` when a client sends `Accept: text/markdown` or identifies as an AI crawler (GPTBot, ClaudeBot, ChatGPT-User, PerplexityBot, Google-Extended, Applebot-Extended, ora-agent, DeepSeekBot). You decide which pages have a Markdown twin; everything else falls through to HTML. API, OAuth and `.well-known` paths are never negotiated.

```ts
// src/hooks.server.ts
import { sequence } from "@sveltejs/kit/hooks";
import { caThemeHandle } from "@codeatlasdev/ui/kit";
import { markdownNegotiation } from "@codeatlasdev/ui/seo";
import { markdownPages } from "$lib/markdown"; // Record<pathname, string>

export const handle = sequence(
  markdownNegotiation({ markdown: (pathname) => markdownPages[pathname] }),
  caThemeHandle({ defaultPreset: "ocean" }),
);
```

Responses carry `Vary: Accept, Accept-Encoding, User-Agent`, so a CDN keeps the HTML and Markdown variants apart.

## Social images

`ogImageRoute` renders an HTML template at 1200x630 through a headless browser and caches the result. HTML and CSS are the template language, so fonts, gradients and `<img>` work as in any page. The browser is passed in, so the package depends on neither Playwright nor Puppeteer: install `playwright` yourself and keep one browser alive per process.

```ts
// src/routes/og/[slug].jpg/+server.ts
import { ogImageRoute } from "@codeatlasdev/ui/seo";
import { chromium, type Browser } from "playwright";
import { posts } from "$lib/posts";

let browser: Promise<Browser> | undefined;

export const GET = ogImageRoute({
  browser: () => (browser ??= chromium.launch()),
  render: ({ params }) => {
    const post = posts[params.slug];
    return post && `<html><body style="margin:0;font:700 64px system-ui;padding:80px">${post.title}</body></html>`;
  },
  cacheKey: ({ params }) => params.slug,
});
```

Unknown slugs answer `404` without starting a browser. Renders run two at a time by default (`concurrency`) and the last 100 images stay in memory (`cacheSize`). Escape any user-provided text before putting it in the template, and inline remote images as `data:` URLs so rendering needs no network.

Browser rendering suits Node servers and containers. On serverless or edge targets with no Chromium, generate images at build time instead, or render in a separate service and point `og.image` at it.

## Brand assets

A favicon, a home-screen icon and a social card are three renderings of one thing: the mark. Drawing them by hand means the brand moves and the tab icon stays behind. `@codeatlasdev/ui/vite` renders them all from one SVG and your theme, with content-hashed names.

Write the mark once, with `{{ink}}` (outline) and `{{spark}}` (accent) in place of colors. A literal color in the mark is an error.

```svg
<!-- src/brand/mark.svg -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
  <path d="M6 5h20v22H6z" fill="none" stroke="{{ink}}" stroke-width="2" />
  <path d="M16 9l2 5 5 2-5 2-2 5-2-5-5-2 5-2z" fill="{{spark}}" />
</svg>
```

Register the plugin next to `caThemePlugin`, with the same theme object:

```ts
// vite.config.ts
import { sveltekit } from "@sveltejs/kit/vite";
import { caBrandPlugin, caThemePlugin } from "@codeatlasdev/ui/vite";
import { defineConfig } from "vite";
import { theme } from "./src/lib/theme.ts";

export default defineConfig({
  plugins: [
    sveltekit(),
    caThemePlugin(theme),
    caBrandPlugin({ theme, name: "Acme", outDir: "static/brand" }),
  ],
});
```

As soon as Vite resolves its config (dev server, build) it writes `src/generated/brand.ts` with the asset URLs, so the module exists before the first build. At build start it writes `favicon.<hash>.svg` (follows `prefers-color-scheme`), `favicon.<hash>.ico` (16, 32, 48), `favicon-32`, `apple-touch-icon` (180, opaque), `icon-192`, `icon-512`, `maskable-512` and `manifest.<hash>.webmanifest`. `outDir` is emptied first. Colors are `--ca-text-primary`, `--ca-brand-main` and `--ca-surface-base` of the theme's default preset, converted to `#rrggbb`. Add `static/brand/` and `src/generated/` to `.gitignore`: nothing it writes is meant to be committed.

The generated manifest is installable as is: `display: "standalone"`, `id` and `scope` `"/"`, and `theme_color` / `background_color` set to the surface color of the theme's default scheme (the dark one unless `defaultScheme` is `"light"`; a manifest holds a single color per field). Chromium shows the install prompt once the manifest, a service worker and the 192/512 icons are present.

| `caBrandPlugin` option | Default | Description |
|---|---|---|
| `mark` | `"src/brand/mark.svg"` | Path of the mark SVG, relative to the project root. The plugin warns and does nothing when it is missing. |
| `theme` | `{}` | The same `ThemeOptions` you pass to `caThemePlugin`. |
| `outDir` | `"static/brand"` | Directory served as `/brand`. Use `"public/brand"` with plain Vite and Astro. |
| `base` | `"/brand"` | URL prefix of `outDir`. |
| `manifestFile` | `"src/generated/brand.ts"` | Where the asset URLs are written, as a module exporting `brand`. |
| `name`, `shortName` | none | Fields of the generated web app manifest. |

`@resvg/resvg-js` and `png-to-ico` are optional peer dependencies. Install them where you register the plugin:

```sh
bun add -d @resvg/resvg-js png-to-ico
```

### Type-check on a fresh clone

`svelte-kit sync` and `svelte-check` never load Vite plugins, so a CI job that only type-checks would not find `src/generated/brand.ts`. Generate it first with the CLI, which takes the plugin's options and renders the same output:

```sh
bunx @codeatlasdev/ui brand --theme src/lib/theme.ts --name Acme
bunx svelte-check
```

`--theme` is a module exporting `theme` (or a default export); a `.ts` file needs Bun or Node 22.18+. The other flags are `--mark`, `--out`, `--base`, `--manifest`, `--short-name` and `--dir`, with the plugin's defaults. It exits 1 when the mark file is missing. A `package.json` script such as `"prepare:brand": "codeatlas-ui brand --theme src/lib/theme.ts"` run before `check-types` keeps the order explicit.

### From your own script

If you already describe the brand once as a `CaBrandPluginOptions` object, call the same functions the plugin and the CLI use instead of repeating the flags:

```ts
// scripts/brand.ts
import { brandUrls, runBrand } from "@codeatlasdev/ui/vite";
import { readFileSync } from "node:fs";
import { brand } from "../brand.config.ts";

await runBrand(process.cwd(), brand); // renders the icons, writes the module; false when the mark is missing
const mark = readFileSync(brand.mark ?? "src/brand/mark.svg", "utf8");
const urls = brandUrls({ mark, theme: brand.theme ?? {}, base: brand.base }); // URLs only: no rasterizer, no files
```

`runBrand(root, options)` needs `@resvg/resvg-js` and `png-to-ico`; `brandUrls` does not.

### Importing the theme in server code

`designStyle`, `mergeTheme`, `DESIGN_STYLES` and `ThemeOptions` are safe to import from `@codeatlasdev/ui/vite` in a `theme.ts` that `src/hooks.server.ts` also imports. The two native packages are loaded at run time, by name, only when you render icons, so the SSR build never bundles `resvgjs.*.node`. `caBrandPlugin` also marks both as `ssr.external`.

Outside Vite (an Astro prebuild script, a CI step), call `generateBrand({ mark, theme, outDir })`, which the plugin wraps. It returns the same URLs.

The hash covers the inputs (mark, resolved colors, sizes), not the rendered bytes, so it is the same on every machine. A changed color renames every file, which makes `/brand/*` safe to serve with `Cache-Control: public, max-age=31536000, immutable`; no `?v=` query is needed and scrapers see a new URL.

Link the icons with `iconLinks`, and keep the logo in the page on the same file by importing it with `?raw` and replacing the placeholders with `var(--ca-text-primary)` and `var(--ca-brand-main)`:

```svelte
<script>
  import { iconLinks } from "@codeatlasdev/ui/seo";
  import { brand } from "../generated/brand";
</script>

<svelte:head>{@html iconLinks(brand)}</svelte:head>
```

`iconLinks` emits the SVG icon, the ICO fallback, `apple-touch-icon` and the manifest link; it skips what you leave out.

### One card per page

`ogCard` returns the complete 1200x630 HTML for a social card: mark, site name, an optional eyebrow, title and description, in literal colors from `resolveBrand(theme)`. Pair it with `renderOgImage` at build time, or with `ogImageRoute` on a server. Name each card after a hash of what it shows (title, description, template version) and write that URL in `og:image` and `twitter:image`.

```ts
import { ogCard, renderOgImage } from "@codeatlasdev/ui/seo";
import { renderMark, resolveBrand } from "@codeatlasdev/ui/vite";

const colors = resolveBrand(theme).dark;
const html = ogCard({
  title: "Button",
  description: "Five variants, three sizes.",
  eyebrow: "Documentation",
  siteName: "Acme",
  mark: renderMark(markSource, colors),
  colors,
});
const png = await renderOgImage(browser, html, { format: "png" });
```

Pass `lang: "pt-BR"` (default `"en"`) when the card is not English: it sets `<html lang>`, which drives hyphenation and the locale font choice.

`@codeatlasdev/ui/vite` re-exports `ogCard`, `renderOgImage` and `OG_SIZE` for build scripts: Node cannot load the `seo` entry because it also exports the `Seo` component. This site does exactly that: `site/scripts/og-integration.ts` renders every page's card after `astro build`, and `site/tests/brand.spec.ts` fails when a page has no card of its own, when the favicon colors differ from the theme, or when `/brand/*` is not immutable.

## Checklist

| Check | Where |
|---|---|
| `<html lang>` set | `app.html` |
| Viewport has `viewport-fit=cover` | `app.html`, see [Mobile](/docs/getting-started/mobile/) |
| One `canonical` per indexable page, absolute | `Seo` |
| `noindex` on private routes | `Seo` |
| `sitemap.xml`, `robots.txt` and `llms.txt` prerendered | `+server.ts` routes |
| Social image 1200x630 with `imageAlt`, one per page | `ogCard` + `renderOgImage` or `ogImageRoute` |
| Favicon, `apple-touch-icon` (180) and manifest icons from one mark | `caBrandPlugin` |

---

# PWA

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/pwa/

Make a SvelteKit app installable with a themed web app manifest, iOS home screen tags and a service worker that keeps navigations on the network and falls back to an offline page.

A progressive web app needs three pieces: a manifest (name, icons, colors), the iOS tags that Safari still reads instead of the manifest, and a service worker. `@codeatlasdev/ui/seo` generates the first two. The service worker stays in your app on purpose: its cache rules depend on your routes and release flow.

`caBrandPlugin` renders the 192, 512 and maskable icons, the 180 `apple-touch-icon` and a ready `manifest.<hash>.webmanifest` from your mark SVG and theme. See [Brand assets](/docs/getting-started/seo/#brand-assets).

## Manifest

`manifest()` returns the manifest object. `theme_color` and `background_color` come from the same theme definition you give `caThemeHandle`: they are the surface color of the default preset in the default scheme (the dark one unless `defaultScheme` is `"light"`), the value the init script puts in `<meta name="theme-color">`. The splash screen and the browser chrome therefore match the first paint.

```ts
// src/routes/manifest.webmanifest/+server.ts
import { manifest } from "@codeatlasdev/ui/seo";
import { theme } from "$lib/theme"; // SvelteKit 3: "#lib/theme.ts"

export const prerender = true;

export const GET = () =>
  new Response(
    JSON.stringify(
      manifest({
        name: "Acme Seller",
        shortName: "Seller",
        description: "Orders and customers on the go.",
        theme,
        icons: [
          { src: "/icons/192.png", sizes: "192x192" },
          { src: "/icons/512.png", sizes: "512x512" },
          { src: "/icons/maskable-512.png", sizes: "512x512", purpose: "maskable" },
        ],
        shortcuts: [{ name: "New order", url: "/orders/new" }],
      }),
    ),
    { headers: { "content-type": "application/manifest+json" } },
  );
```

Defaults are `display: "standalone"`, `start_url: "/"`, `scope: "/"` and `short_name` equal to `name`. Each icon gets `type: "image/png"` unless you set one. Pass `themeColor` or `backgroundColor` (as `#rrggbb`) to override the derived colors, and `extra` for members the builder does not cover (`categories`, `screenshots`, `id`).

Android crops other icons into a white tile. Keep the artwork of the `maskable` icon inside the central 80% of the canvas. `manifest()` logs a warning when no icon has `purpose: "maskable"`.

Link it from the page head with `<Seo manifest="/manifest.webmanifest" ... />`.

## iOS home screen

Safari ignores most manifest fields. `appleMeta()` returns the tags it does read, as an HTML string:

```svelte
<script>
  import { appleMeta } from "@codeatlasdev/ui/seo";
</script>

<svelte:head>
  {@html appleMeta({ touchIcon: "/icons/apple-touch-180.png", title: "Seller" })}
</svelte:head>
```

| Tag | Effect |
|---|---|
| `mobile-web-app-capable` and `apple-mobile-web-app-capable` | Opens without browser chrome. |
| `apple-mobile-web-app-status-bar-style` | `black-translucent` (default), `default` or `black`. The default draws the page under the status bar: it needs `viewport-fit=cover`; pad with `var(--ca-safe-top)`. |
| `apple-mobile-web-app-title` | The label under the icon, emitted when you pass `title`. |
| `apple-touch-icon` | 180x180 PNG, from `touchIcon`. Use an opaque image: iOS fills transparency with black. |

## Service worker

SvelteKit builds the worker when `src/service-worker.ts` (Kit 2) or `src/service-worker/index.ts` (Kit 3) exists and registers it for you. `bunx @codeatlasdev/ui init --write` creates the right one for your Kit major, plus the prerendered `/offline` page. The build lists give the hashed build files, static files and the app version, so the cache never serves stale assets after a deploy.

Kit 3 removed `$service-worker`: `self` comes from `$app/service-worker`, the file lists from `$app/manifest` (`immutable`, `assets`) and `version` from `$app/env`. `$app/forms`, `$app/navigation` and `$app/state` cannot be imported into a worker (the build fails with `service_worker_invalid_import`), and `tsconfig.json` must list `src/service-worker` in `exclude` (the worker has its own `$app/tsconfig/service-worker`).

The pattern below (Kit 2 imports; the rules are the same on Kit 3) mirrors what works in production apps:

| Request | Strategy | Why |
|---|---|---|
| Build files (`/_app/immutable/*`) and static assets | Cache first | Content-hashed, safe forever. |
| Page navigations | Network first, then the cached offline page | Users always see fresh data; offline shows a real page instead of the browser error. |
| Everything else (API, auth, form actions) | Untouched | Never cache authenticated data. |

```ts
// src/service-worker.ts
/// <reference types="@sveltejs/kit" />
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
import { build, files, version } from "$service-worker";

const sw = self as unknown as ServiceWorkerGlobalScope;
const CACHE = `app-${version}`;
const ASSETS = [...build, ...files, "/offline"];

sw.addEventListener("install", (event) => {
  event.waitUntil(
    caches
      .open(CACHE)
      .then((cache) => cache.addAll(ASSETS))
      .then(() => sw.skipWaiting()),
  );
});

sw.addEventListener("activate", (event) => {
  event.waitUntil(
    caches
      .keys()
      .then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
      .then(() => sw.clients.claim()),
  );
});

sw.addEventListener("fetch", (event) => {
  const { request } = event;
  if (request.method !== "GET") return;
  const url = new URL(request.url);
  if (url.origin !== sw.location.origin) return;

  // Network first for pages, offline page when the network fails.
  if (request.mode === "navigate") {
    event.respondWith(
      fetch(request).catch(async () => (await caches.match("/offline")) ?? Response.error()),
    );
    return;
  }

  // Cache first for hashed build output and static files.
  if (ASSETS.includes(url.pathname)) {
    event.respondWith(caches.match(request).then((hit) => hit ?? fetch(request)));
  }
});
```

Create `src/routes/offline/+page.svelte` with a short message and a retry button, and set `export const prerender = true;` in a sibling `+page.ts` so it exists as static HTML when the worker installs. Using `version` in the cache name replaces old caches on every release.

Service workers only run on HTTPS or `localhost`, and only in a production build: run `bun run build && bun run preview`, open DevTools, Application, Service Workers, then tick Offline and reload.

## Install prompt

Browsers only offer to install an app that meets the criteria: the manifest above (`display: "standalone"`, 192 and 512 icons) and a service worker. [`InstallPrompt`](/docs/feedback/install-prompt/) turns that into UI: put it once in the root layout and it shows the native install dialog on Chromium, the Share, Add to Home Screen steps on iOS, and nothing once the app is installed or the user dismissed it.

## Checklist

| Check | Where |
|---|---|
| Manifest linked and valid in DevTools, Application, Manifest | `Seo manifest` |
| Maskable icon and 512px icon present | `manifest()` |
| `viewport-fit=cover` in the viewport meta | `app.html` |
| iOS tags present | `appleMeta()` |
| Offline page prerendered and cached on install | `src/service-worker.ts` |
| No authenticated responses cached | fetch handler |
| An install entry point | `InstallPrompt` in the root layout |

---

# Migrate from React

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/migrate-react/

Move a React app (MUI, shadcn/Radix or Chakra) to Svelte 5 and CodeAtlas UI. Decision flow, hook-to-rune map, component maps, layout, theme and data table recipes, and how to report gaps.

This page is written for a coding agent and for the person reviewing its work. Every component and prop named here exists in the generated manifest (`get_component`, `get_export`), and a test fails when one stops existing. If you cannot find an equivalent for something in your app, that is a [gap](#gaps-and-workarounds): write a documented workaround and report it, do not invent a component.

## Decide first: incremental or rewrite

| Situation | Choose | Why |
|---|---|---|
| Under about 15 routes, few shared stores, no heavy React-only dependency | **Rewrite** into a fresh SvelteKit app | One framework at the end, no bridge code to delete later. |
| Large app that ships weekly | **Incremental, route by route** | Put the new Svelte app behind the same domain (reverse proxy per path prefix), migrate a route at a time, share only the session cookie and the API. |
| Design system is the main goal | **Rewrite the shell and the list/form pages first** | `AppList`, `AppForm`, `AppSettings` and `PageShell` replace most hand-built page wrappers in one step. |

Never mount React inside Svelte (or the reverse) to save time: two reconcilers on one page means two focus models and two sets of effects. A route is either React or Svelte.

Port in this order, whatever you picked: theme and shell, then one list page, one form page, one settings page, then the rest. Keep the React app's API calls as they are; only the UI layer moves.

## Project setup

1. **Create the app.** `bunx sv create my-app` and choose SvelteKit with TypeScript. Svelte 5 runes mode is the default.

2. **Install and wire the package.**

```sh
bun add @codeatlasdev/ui @lucide/svelte
bunx @codeatlasdev/ui init --write
```

   `init` writes the theme file, the Vite plugins, the server hook, the `global.css` import and a mobile-ready viewport meta. Details: [Installation](/docs/getting-started/installation/).

3. **Install optional peers only for what you port.** `@tanstack/svelte-table` for `DataTable`, `echarts` for charts, `shiki` for code blocks.

4. **Give your agent the manifest.** `claude mcp add codeatlas-ui -- npx -y -p @codeatlasdev/ui ca-ui-mcp`, see [AI agents](/docs/getting-started/ai-agents/). Tell it to call `get_component` before it writes any prop.

## React to Svelte 5 runes

| React | Svelte 5 | Notes |
|---|---|---|
| `useState(0)` | `let n = $state(0)` | Assign to change it: `n += 1`. Objects and arrays are deep reactive, mutate in place (`list.push(x)`). |
| `useMemo(() => a * 2, [a])` | `let b = $derived(a * 2)` | No dependency array. Use `$derived.by(() => { … })` for several statements. |
| `useEffect(fn, [dep])` | `$effect(() => { … })` | Dependencies are whatever the effect reads. Runs in the browser only, after the DOM updates. |
| `useEffect(() => { fetch… }, [])` | `onMount` or a SvelteKit `load` | Fetch in `load` (server and client) instead of in an effect. |
| `useCallback(fn, [dep])` | a plain function | Functions are not recreated per render, there is nothing to memoize. |
| `useRef(null)` + `ref={r}` | `let el = $state<HTMLElement>()` + `bind:this={el}` | Read `el` inside `$effect` or an event handler. |
| `props` and `children` | `let { title, children } = $props()` and `{@render children?.()}` | `children` is a snippet. |
| render props, slots | named snippets: `{#snippet actions()}…{/snippet}` | The component renders it with `{@render actions?.()}`. Components of this library use snippets for every hole, see `get_component`. |
| `createContext` / `useContext` | `setContext(key, value)` / `getContext(key)` from `svelte` | Call both during component init. For shared app state prefer a `.svelte.ts` module exporting `$state`. |
| controlled `value` + `onChange` | `bind:value` | Two-way binding replaces the pair. Use `onchange` only for side effects. |
| `<form onSubmit>` + `e.preventDefault()` | `<form method="POST" use:enhance>` | SvelteKit form actions validate on the server and work without JavaScript. |

### Effect pitfalls

- **Do not use `$effect` to compute a value.** `useEffect` plus `setState` becomes `$derived`. An effect that writes state it also reads can loop.
- **Reads after `await` are not tracked.** Read every reactive value before the first `await` inside an effect.
- **Return a cleanup function** for timers, listeners and observers, exactly like `useEffect`. It runs before the next run and on destroy.
- **There is no effect on the server.** Code that touches `window`, `localStorage` or `matchMedia` belongs in `onMount` or `$effect`, or behind `browser` from `$app/environment`.
- **Reading `$state` outside a component** (a plain `.ts` file) does not track. Put shared reactive state in a `.svelte.ts` file.

```svelte
<script lang="ts">
  import { Button, TextField } from "@codeatlasdev/ui";

  let name = $state("");
  let saving = $state(false);
  let valid = $derived(name.trim().length > 1);

  async function save() {
    saving = true;
    await fetch("/api/users", { method: "POST", body: JSON.stringify({ name }) });
    saving = false;
  }
</script>

<TextField label="Name" bind:value={name} />
<Button variant="filled" loading={saving} disabled={!valid} onclick={save}>Save</Button>
```

## Component map

Targets are real exports of `@codeatlasdev/ui` unless the import path says otherwise. Props that differ from what you expect are listed; for the rest, call `get_component`.

### MUI

| MUI | CodeAtlas UI | Differences |
|---|---|---|
| `Button` (`contained`, `outlined`, `text`) | `Button` | `variant` is `filled`, `outlined`, `ghost`, `glass` or `destructive`. `loading`, `fullWidth`, `href`, snippets `leading` and `trailing` replace `startIcon` and `endIcon`. |
| `IconButton` | `IconButton` | `aria-label` is required, the child is the icon. |
| `TextField` | `TextField` | `label`, `error` (a string), `helperText`, `bind:value`. Multiline: `TextArea`. Number: `NumberField`. |
| `Select`, `MenuItem` | `Select` | Options go in the `options` array, not as children. For search use `Combobox`. |
| `Autocomplete` | `Combobox` | `options`, `bind:value`, `emptyText`. |
| `Checkbox` + `FormControlLabel` | `Checkbox` | `label` is built in, `bind:checked`. |
| `Switch` | `Switch` | `label`, `bind:checked`. |
| `RadioGroup`, `Radio` | `RadioGroup` | `items` array and `bind:value`. |
| `Slider` | `Slider` | `bind:value`, or `bind:values` for a range. |
| `ToggleButtonGroup` | `ToggleGroup` | Or `SegmentedControl` for a single choice. |
| `DatePicker`, `DateRangePicker` | `DatePicker`, `DateRangePicker` | Values are `@internationalized/date` values, not `Date`. Also `DateField`, `TimeField`, `Calendar`, `RangeCalendar`. |
| `Dialog` | `Dialog` | `bind:open`, `title`, `description`, snippets `children` and `actions`. Confirmations: `AlertDialog`. |
| `Drawer` | `Drawer` | `side` is `left`, `right` or `bottom`. On a phone, a bottom `Sheet` is the native pattern. |
| `Menu`, `MenuItem` | `DropdownMenu`, `DropdownMenuItem` | Also `DropdownMenuLabel` and `DropdownMenuSeparator`. |
| `Popover` | `Popover` | Snippets `trigger` and `children`. |
| `Tooltip` | `Tooltip` | `content` is a string. |
| `Tabs`, `Tab` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | `bind:value` on `Tabs`. |
| `Accordion` | `Accordion`, `AccordionItem` | `type` is `single` or `multiple`. |
| `Alert` | `Alert` | `severity` is `success`, `warning`, `error` or `info`. |
| `Snackbar` | `Toaster` plus `toast` | Mount `Toaster` once; call `toast.success(msg)`, `toast.error(msg)`, `toast.show(msg, { variant })`. |
| `Chip` | `Chip` | `deletable` and `ondelete`. Status labels: `StatusChip`. |
| `Badge` | `Badge` | `count`, `dot`, `color`. |
| `Avatar` | `Avatar` | `src`, `alt`, `fallback`. |
| `Card` | `Card` | `title`, `headerActions`, `flush`. |
| `Paper` | `Surface` | `elevation`, `material`, `tone`. |
| `Skeleton` | `Skeleton` | `variant`, `rows`. |
| `CircularProgress` | `Spinner` | `label` for assistive tech. |
| `LinearProgress` | `Progress` | `value`, `indeterminate`. |
| `Divider` | `Divider` | `orientation`. |
| `Breadcrumbs` | `Breadcrumb` | `items` array. |
| `Pagination` | `Pagination` | `count`, `perPage`, `bind:page`. |
| `Stepper` | `Stepper` | `steps` array, `bind:current`. |
| `Box`, `Stack`, `Grid`, `Container` | `Box`, `Stack`, `Grid`, `Container` | `gap`, `columns` and the other layout props are numbers on the token scale. No `sx`. |
| `Table` family | `SimpleTable` | Native `<thead>`/`<tbody>` markup inside. Sorting, search and paging: [Data tables](#data-tables). |

### shadcn/ui and Radix

| shadcn / Radix | CodeAtlas UI | Differences |
|---|---|---|
| `Button` | `Button` | Same variant names for `outline` → `outlined`, `ghost`, `destructive`; `default` → `filled`. |
| `Input`, `Label` | `TextField` | The label, hint (`description`) and error are props, not siblings. |
| `Textarea` | `TextArea` | `rows`, `resize`. |
| `Select` | `Select` | `options` array. |
| `Command` | `CommandPalette`, `Combobox` | Palette is for app navigation (`modules`); a searchable field is `Combobox`. |
| `Checkbox`, `Switch`, `RadioGroup`, `Slider` | `Checkbox`, `Switch`, `RadioGroup`, `Slider` | All `bind:`. |
| `ToggleGroup` | `ToggleGroup` | `items` array. |
| `Dialog` | `Dialog` | Controlled with `bind:open`. There is no `DialogTrigger`: put a `Button` that sets `open = true`. |
| `AlertDialog` | `AlertDialog` | `onconfirm`, `oncancel`, `destructive`. |
| `Sheet` | `Drawer` or `Sheet` | `Drawer` slides from a side; `Sheet` is the mobile bottom sheet. |
| `Popover`, `HoverCard` | `Popover` | |
| `DropdownMenu` | `DropdownMenu`, `DropdownMenuItem` | |
| `Tooltip` | `Tooltip` | |
| `Tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | |
| `Accordion`, `Collapsible` | `Accordion`, `Collapsible` | |
| `Alert` | `Alert` | |
| `Sonner` / `Toast` | `Toaster` plus `toast` | |
| `Badge` | `Badge`, `Chip` | |
| `Avatar` | `Avatar` | |
| `Card` | `Card` | Header, content and footer are `title`, `children` and `headerActions`. |
| `Skeleton` | `Skeleton` | |
| `Progress` | `Progress` | |
| `Separator` | `Divider` | |
| `Breadcrumb`, `Pagination` | `Breadcrumb`, `Pagination` | |
| `ScrollArea` | `ScrollArea` | |
| `Calendar`, `DatePicker` | `Calendar`, `DatePicker` | |
| `Table` | `SimpleTable` | |
| `DataTable` (TanStack recipe) | `DataTable` from `@codeatlasdev/ui/table` | See [Data tables](#data-tables). |
| `cn()` / `clsx` | not needed | Components take a `class` prop; layout comes from `Stack`, `Flex`, `Grid` and tokens. |

### Chakra UI

| Chakra | CodeAtlas UI |
|---|---|
| `Button`, `IconButton` | `Button`, `IconButton` |
| `Input`, `Textarea`, `NumberInput` | `TextField`, `TextArea`, `NumberField` |
| `FormControl` (label, helper, error) | the same props on each field (`label`, `description`, `error`) |
| `Select` | `Select` |
| `Checkbox`, `Switch`, `RadioGroup`, `Slider` | `Checkbox`, `Switch`, `RadioGroup`, `Slider` |
| `PinInput` | `PinInput` |
| `Modal` | `Dialog` |
| `AlertDialog` | `AlertDialog` |
| `Drawer` | `Drawer` |
| `Menu` | `DropdownMenu`, `DropdownMenuItem` |
| `Popover`, `Tooltip` | `Popover`, `Tooltip` |
| `Tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
| `Accordion` | `Accordion`, `AccordionItem` |
| `Alert`, `useToast` | `Alert`, `Toaster` plus `toast` |
| `Badge`, `Tag` | `Badge`, `Chip` |
| `Avatar` | `Avatar` |
| `Skeleton`, `Spinner`, `Progress` | `Skeleton`, `Spinner`, `Progress` |
| `Divider`, `Breadcrumb` | `Divider`, `Breadcrumb` |
| `Box`, `Flex`, `Stack`, `Grid`, `Container` | `Box`, `Flex`, `Stack`, `Grid`, `Container` |
| `Table` | `SimpleTable` |
| style props (`p`, `mt`, `bg`) | tokens (`--ca-space-*`, `--ca-*`) through `gap`, `padding` props on layout components, never inline styles |

## Layout patterns

Do not port a React page wrapper one-to-one. Pick the template that matches what the page is, then fill its snippets. They own the scroll behaviour, the header, the footer and the mobile layout.

| Your React page | Use | Holes |
|---|---|---|
| A list or CRUD index with search, filters and paging | `AppList` | `data`, `searchKeys`, `perPage`; snippets `actions`, `filters`, `children`. |
| Create or edit one entity | `AppForm` with `FormSection` | `backHref`, snippets `footer` for Cancel and Save, `leading`. |
| Settings with several sections | `AppSettings` | `tabs`, `bind:activeTab`; sections are `FormSection` and `SettingItem`. |
| Any other content page (dashboard, detail) | `PageShell` | `title`, `description`, snippet `actions`. |
| The signed-in frame (sidebar, bottom nav) | `AppShellLayout` | `modules`, `pathname`, `onNavigate`. Only in authenticated route layouts. |
| Login, sign-up | `AuthLayout` with `AuthCard` | |
| Empty and error states | `EmptyState`, `ErrorPage` | |

```svelte
<script lang="ts">
  import { AppList, Button, SimpleTable, StatusChip } from "@codeatlasdev/ui";

  let { data } = $props();
</script>

<AppList title="Users" data={data.users} searchKeys={["name", "email"]} perPage={10}>
  {#snippet actions()}
    <Button variant="filled" href="/users/new">New user</Button>
  {/snippet}

  {#snippet children(list)}
    <SimpleTable>
      <thead><tr><th>Name</th><th>Status</th></tr></thead>
      <tbody>
        {#each list.rows as u (u.id)}
          <tr>
            <td>{u.name}</td>
            <td><StatusChip status={u.active ? "success" : "neutral"} label={u.active ? "Active" : "Inactive"} /></td>
          </tr>
        {/each}
      </tbody>
    </SimpleTable>
  {/snippet}
</AppList>
```

Do not wrap fields in `Stack` or `Flex` for layout inside `FormSection`: `layout` is `grid` by default, `list` for switches and `stack` for composite blocks. Mobile rules (viewport units, safe areas, keyboard) are in [Mobile](/docs/getting-started/mobile/).

## Theme mapping

There is one `ThemeOptions` object in `src/lib/theme.ts`. Map your design tokens into it instead of recreating a theme provider:

| React source | `ThemeOptions` |
|---|---|
| MUI `palette.primary.main`, Tailwind `primary`, Chakra `brand.500` | `presets: [{ id: "app", color: "#rrggbb" }]` and `defaultPreset: "app"`. The library derives the full light and dark ramp in OKLCH. |
| Per-role colors (`background`, `text`, `error`) | `presets[].colors.light` and `.dark`, see [Theming](/docs/getting-started/theming/#porting-a-palette-by-role). |
| MUI `palette.mode`, `next-themes`, Chakra `colorMode` | `defaultScheme: "system"` and the `colorScheme` store (`colorScheme.toggle()`, or the `ThemeToggle` component). |
| MUI `shape.borderRadius`, Tailwind `rounded-*` | `radius` (multiplier) and `controlRadius`. |
| MUI `spacing`, Tailwind spacing scale, Chakra `space` | `density`: `compact`, `comfortable` or `airy`. |
| MUI `typography.fontFamily`, Tailwind `fontFamily` | `fonts: { body, mono, display }`. |
| Anything else (a one-off color or size) | `overrides: { light: { "--ca-…": "…" }, dark: { … } }`. Find the token with `search_tokens`. |

```ts
// src/lib/theme.ts
import type { ThemeOptions } from "@codeatlasdev/ui/vite";

export const theme: ThemeOptions = {
  presets: [{ id: "app", color: "#2563eb" }],
  defaultPreset: "app",
  defaultScheme: "system",
  radius: 0.8,
  density: "comfortable",
  fonts: { body: "Inter, system-ui, sans-serif" },
};
```

Delete the React theme provider, the Tailwind color config and every `sx`, `className` and style prop that only set color, spacing or radius.

## Data tables

TanStack Table for React becomes `DataTable` from the `@codeatlasdev/ui/table` entry, built on `@tanstack/svelte-table`. Column helpers keep the same accessor idea; search, sorting, paging and the column toggle are built in.

| TanStack Table (React) | `@codeatlasdev/ui/table` |
|---|---|
| `createColumnHelper<T>()` | `createCaColumnHelper<T>()` |
| `useReactTable({ data, columns, … })` + your markup | `DataTable` with `columns` and `data` (simple mode), or `createCaTable` to render your own markup |
| `getFilteredRowModel`, `globalFilter` state | built in; controlled with `globalFilter` and `onGlobalFilterChange` |
| sorting state | built in; controlled with `sorting` and `onSortingChange` |
| pagination state, manual pagination | built in; controlled with `pagination`, `onPaginationChange` and `total` for server data |
| `flexRender(cell.column.columnDef.cell, …)` | `renderComponent` from `@tanstack/svelte-table` for header or cell components |
| column visibility menu | `DataTableColumnToggle`, already in the toolbar |
| faceted filter chips | `DataTableFacetedFilter` as a child of `DataTable` |

```svelte
<script lang="ts">
  import { DataTable, createCaColumnHelper } from "@codeatlasdev/ui/table";

  type User = { name: string; email: string };
  let { users }: { users: User[] } = $props();

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor("name", { header: "Name", meta: { label: "Name" } }),
    col.accessor("email", { header: "Email", meta: { label: "Email" } }),
  ]);
</script>

<DataTable {columns} data={users} />
```

Details and controlled mode: [DataTable](/docs/display/data-table/). For a plain list without search or sorting, `SimpleTable` inside `AppList` is lighter.

## Gaps and workarounds

If something in the React app has no equivalent in the library (a component, a prop, a behaviour), do not fake it and do not leave it undocumented:

1. **Check twice.** Call `search_demos`, `get_component` and `get_export` with the React name and with a description of what it does. `list_components` shows everything.
2. **Write a workaround** in the app's own code, with a one-line marker so it can be found and removed later:

```svelte
<!-- ca-ui-workaround(#123): no equivalent of MUI TreeView, using nested Collapsible -->
```

   In script code use `// ca-ui-workaround(#123): reason`. Use the issue number once you have it; until then write the marker without a number and add it after step 3.
3. **Report it.** Call the MCP tool `report_issue` with `kind: "migration-gap"`, a neutral `title`, `expected` (what the React component did), `actual` (what the library offers), a minimal `repro` and your `workaround`. It returns a sanitized issue body and a prefilled link; it never posts by itself. Open the link, or run the `gh issue create` command it prints.

Never put project, company or customer names, file paths, URLs, environment values, secrets, data or business logic in the report. Use neutral names (`Foo`, `items`) in the repro. `bunx @codeatlasdev/ui workarounds` lists the markers in your code and which of their issues are closed, so you know when to delete a workaround.

Run `svelte-check` after every ported page. A wrong prop or snippet name is a type error, which is the fastest signal that a component was guessed instead of looked up.

---

# Reporting problems

Group: Getting started. URL: https://ui.codeatlas.com.br/docs/getting-started/reporting/

How an AI agent that hits a library problem writes a documented workaround and opens a sanitized issue, and what it must never include.

When an agent building with CodeAtlas UI hits a problem (a bug, a missing prop or component, a migration step the guide does not cover, docs that are wrong), it does two things: it works around it in your code so you are not blocked, and it drafts a public issue so the library gets fixed. The report must never leak anything about your project.

## The flow

1. **Workaround with a marker.** The agent keeps the workaround small and writes one line next to it:

```ts
// ca-ui-workaround(#227): Select closes when the list scrolls inside a dialog
```

   In markup: `<!-- ca-ui-workaround(#227): why -->`. The number is the issue it filed (or found).
2. **Draft the report.** The MCP tool `report_issue` takes `kind` (`bug`, `missing`, `migration-gap` or `docs`), `title`, `expected`, `actual` and optionally `component`, `repro`, `workaround` and `version`. It returns the sanitized markdown body, the list of redactions it applied, a prefilled link to the [AI report form](https://github.com/codeatlasdev/ui/issues/new?template=ai_report.yml) and a `gh issue create` command. It never posts by itself: the agent shows you the body and you open the link or run the command.
3. **Clean up later.** After you upgrade, list the markers and see which issues were closed:

```sh
bunx @codeatlasdev/ui workarounds        # scans src; pass paths to scan others
```

   Each line is `file:line  #issue  open|closed|unknown  reason`. A closed issue means the library fixed it: remove the workaround and its marker. The command only reads, asks the public GitHub API without a token, and exits 0 even offline (the state is then `unknown`).

## What is never reported

The issue is public. A report contains no project, company or customer names, file paths, URLs (except ui.codeatlas.com.br and github.com/codeatlasdev), environment variables, tokens, emails, IP addresses, data or business logic. The reproduction is the smallest snippet that shows the problem, written with generic names (`Item A`, `user@example.com`), not an excerpt of your files.

`report_issue` enforces this a second time on every field it receives. It replaces:

| Found | Becomes |
|---|---|
| Absolute, home and project-relative file paths | `<path>` |
| URLs other than ui.codeatlas.com.br and github.com/codeatlasdev | `<url>` |
| Email addresses | `<email>` |
| IPv4 and IPv6 addresses | `<ip>` |
| `sk-`, `ghp_`, AWS-style keys, `Bearer` tokens, JWTs and other long high-entropy strings | `<secret>` |
| `NAME_LIKE_THIS=value` assignments | `<env>` |
| Package scopes other than `@codeatlasdev` | `@scope/pkg` |

The result lists which categories matched, so the agent (and you) can see that something was removed. Redaction is a safety net, not a substitute for writing the report with neutral names in the first place: it can only recognize patterns, not that a word is your client's name.

The body carries the library version (from the installed package unless the agent passes one), the kind, the component and the sections above, and ends with `Reported by an AI agent via ca-ui-mcp; reviewed for private details`. The form has a required checkbox, "No private project details".

## Set it up

The tool ships in the same MCP server as the demo tools, see [AI agents](/docs/getting-started/ai-agents/#mcp-server). The skill `codeatlas-ui` (also installed by the Claude Code plugin) tells the agent when to use it: in the section "When the library gets in your way".

---

# Colors

Group: Foundation. URL: https://ui.codeatlas.com.br/docs/foundation/colors/

Brand, surface, text, outline and semantic color tokens, all defined in OKLCH and swapped per preset and scheme.

Every color is a CSS custom property. Components never hardcode a color, so changing the preset, the scheme or a single token restyles the whole app.

```css
.badge {
  color: var(--ca-brand-text);
  background: color-mix(in oklab, var(--ca-brand-main) 14%, var(--ca-surface-base));
  border: 1px solid var(--ca-outline-default);
}
```

The swatches below read the live tokens, so they follow the theme switcher in the header. Use `--ca-brand-text` for brand-colored text and `--ca-brand-fill` for filled brand surfaces: both are tuned to keep contrast in light and dark.

### Brand

Derived from the active preset. brand-fill and brand-text keep contrast in both schemes.

### Surfaces

A layered scale for depth: sunken, base, raised, overlay.

### Text

text-hint is the lowest readable tier (4.5:1). text-disabled is the label of disabled controls only (3:1 on every surface), never information.

### Semantic

Success, warning, error and info. Semantic colors never change with the preset.

### Outline

Border and divider scale.

---

# Typography

Group: Foundation. URL: https://ui.codeatlas.com.br/docs/foundation/typography/

Font families and the type scale for headings, body text and UI labels.

Type sizes are `rem` tokens multiplied by `--ca-font-scale`, so they follow the user's browser font size. Fonts are stacks: the defaults name Inter and JetBrains Mono but the kit does not load them, so load them yourself (for example with `@fontsource-variable`) or replace them in your theme. `--ca-font-display` defaults to `--ca-font-sans`.

```ts
import { defineTheme } from "@codeatlasdev/ui";

export const theme = defineTheme({
  fonts: { body: "Geist, system-ui, sans-serif", mono: "Geist Mono, monospace", display: "Fraunces, serif" },
});
```

`fonts.body`, `fonts.mono` and `fonts.display` set `--ca-font-sans`, `--ca-font-mono` and `--ca-font-display`. See [Theming](/docs/getting-started/theming/).

Text-entry controls use `--ca-input-font-size`, which is raised to at least 16px on touch devices and below 900px so iOS Safari does not zoom into focused fields. See [Mobile](/docs/getting-started/mobile/).

### Font families

### Heading scale

--ca-font-size-h1 to h6.

### Body and UI scale

Body, caption, label and button sizes, plus the micro and nano steps used by badges.

---

# Shadows

Group: Foundation. URL: https://ui.codeatlas.com.br/docs/foundation/shadows/

Elevation scale from xs to xl, tuned separately for light and dark schemes.

```css
.popover {
  box-shadow: var(--ca-shadow-lg);
}
```

The default shadows are neutral black with no hue: soft in light mode, deeper in dark mode, so one token works in both. The `flat`, `outlined` and similar styles replace them with none or a hairline ring, and the `liquid` recipe uses hue-tinted ones. [Surface](/docs/surfaces/surface/) takes its drop shadow from `elevation` (`--ca-elevation-0` to `--ca-elevation-5`), not from these tokens, see [Materials](/docs/foundation/materials/).

### Shadow scale

xs for hairline lift up to xl for modal depth.

---

# Materials

Group: Foundation. URL: https://ui.codeatlas.com.br/docs/foundation/materials/

The five material tiers behind every surface, from ultra-thin translucency to chrome, and how the surface style changes them.

Materials are CSS classes (`glass-ultra-thin`, `glass-thin`, `glass-regular`, `glass-thick`, `glass-chrome`) that read `--ca-mat-<tier>-*` tokens (blur, fill and shadow). [Surface](/docs/surfaces/surface/) paints the same five tiers for you from its `material` and `elevation` props (elevation 1 to 5 maps to ultra-thin to chrome), and adds the refraction layer for `material="liquid"`. Use the classes only for markup that is not a Surface.

```svelte
<script>
  import { Surface } from "@codeatlasdev/ui";
</script>

<Surface material="glass" elevation={4} tone="brand">Content</Surface>
```

The surface style on `<html data-style>` rewrites the `--ca-mat-*` tokens, so every material changes at once. `solid` is the default: no blur, opaque fills, no glow, hairline edges, so the tiers below differ only by fill and shadow. `flat` also drops the shadows, `frosted` keeps a lighter blur, and `glass` (the opt-in `liquid` look) has the full blur, mesh and glow. The demos on this page use `material="glass"`, so they look the same under any style. Switch the style with `colorScheme.setStyle()`, see [Theming](/docs/getting-started/theming/#surface-styles). Browsers with `prefers-reduced-transparency: reduce` get opaque surfaces.

Components that blur but are not a Surface (the Tabs list, Chip, Toast, Rail, Panel, the DataTable menus) set `data-ca-blur="<role>"` on their element instead of declaring `backdrop-filter`, so `<html data-style>` drives them exactly like a `material="auto"` Surface. Roles are `ultra-thin`, `thin`, `regular`, `thick`, `chrome`, `mat-thin`, `mat-regular`, `overlay`, `chrome-layer` and `tooltip`; Use it the same way on your own elements, and never add `will-change` or `isolation: isolate` around them. `list_surfaces` in the [MCP server](/docs/getting-started/ai-agents/#mcp-server) lists the styles and which ones draw a blur.

The modal scrim (the `::backdrop` of Dialog, AlertDialog, Sheet, Drawer, CommandPalette and DocsSearch) reads `--ca-scrim-blur`, which defaults to `blur(4px) saturate(180%)` under every style. Set `--ca-scrim-blur: none` on `:root` to drop the blur on all of them at once, for example in a WKWebView window that is transparent over a native view.

### Glass tiers

All five thickness levels on a gradient backdrop.

### Button glass variants

glass-btn, glass-btn-prominent and glass-btn-clear for custom controls. They follow `data-style`, so the halo and blur disappear under `solid`.

### Tinted and glowing

---

# Drag and drop

Group: Foundation. URL: https://ui.codeatlas.com.br/docs/foundation/drag-and-drop/

Sort a list, move items between lists and drop onto zones with mouse, touch and keyboard, announced to screen readers and calm under reduced motion.

`useDnd()` is the drag primitive behind reorderable lists, boards and drop targets. Call it once while a component initializes, render `<DndLayer {dnd} />` once next to your lists (it holds the keyboard instructions and the drag styles, so apps that never drag do not pay for them) and attach the parts `useDnd` hands back to your own markup:

```svelte
<script>
  import { applyMove, DndLayer, useDnd } from "@codeatlasdev/ui";

  let items = $state([{ id: "a" }, { id: "b" }, { id: "c" }]);
  const dnd = useDnd();
  const onDrop = (e) => (items = applyMove({ list: items }, e, (i) => i.id).list);
</script>

<DndLayer {dnd} />
<ul {@attach dnd.sortable(() => ({ id: "list", getItems: () => items.map((i) => i.id), onDrop }))}>
  {#each items as item (item.id)}
    <li data-dnd-item={item.id}>
      <button aria-describedby={dnd.instructionsId}>{item.id}</button>
    </li>
  {/each}
</ul>
```

## How it behaves

The engine measures the item boxes once when a drag starts and finds the target from those cached rectangles on every frame. While you drag, only three things move: a clone of the item that follows the pointer, a one-line drop indicator and `data-dnd-*` attributes. Your list does **not** re-render until `onDrop` fires, so a board with hundreds of cards stays smooth. `onDrop` is the only place you change state: `{ id, data, from, to }`, where `from` and `to` are `{ container, index }`.

| Input | How it works |
|---|---|
| Mouse and pen | Press and move 4px. A press that does not move stays a click. |
| Touch | Press and hold for 350ms, then drag. Moving before the hold ends is a scroll, so lists inside a scrolling page keep scrolling. |
| Keyboard | Focus the item (or its handle) and press Space to lift. Arrows move it, Home and End jump to the ends, Enter drops, Escape cancels. Left and right (up and down in a horizontal list) move it to the next list or zone. |
| Screen reader | Every step is spoken through [`announce()`](/docs/getting-started/accessibility/): "Lifted Write the release notes, position 2 of 4", "…position 3 of 4", "Dropped…", "Cancelled…". The text follows the active locale (English and Portuguese built in); pass `useDnd({ messages })` for another language. |
| Edges | Holding the pointer near the edge of a scrolling container scrolls it, faster the closer you are. |
| Reduced motion | The cancel animation and the press scale are removed. |

Put `aria-describedby={dnd.instructionsId}` on the focusable handle so a screen reader tells people how to lift it. Pass `handle: ".grip"` when only a grip may start a drag (a row that also holds links or inputs).

## Sort a list

### Sortable list

Drag the grip, press and hold on a touch screen, or focus the grip and press Space.

## Move between lists

Lists that share a `group` accept each other's items. `applyMove` applies a drop event to a record of arrays (reorder inside one list, move between two); use your own reducer when the data lives in a store.

### Board

Cards reorder inside a column and move between columns. With the keyboard, Space lifts, the arrows move and Enter drops.

## Drop zones

A drop zone is a target that is not a sortable list: a calendar day, a folder, a trash can. A standalone item uses `dnd.draggable`; the zone gets `data-dnd-over` while an item is above it. Return `false` from `accepts` to refuse an item.

### Drop zones

Drag a chip onto a day, or lift it with Space and pick the day with the arrows.

## API

`useDnd(options?)` returns `{ sortable, draggable, dropzone, instructionsId, instructions, active, cancel }`. `<DndLayer dnd={dnd} />` renders `instructions` under `instructionsId` and carries the styles. `sortable`, `draggable` and `dropzone` take a getter that returns the options and return an attachment (`{@attach …}`), so reactive state flows in without recreating anything.

| Option | Applies to | Description |
|---|---|---|
| `id` | all | Container or item id. Required. |
| `group` | `sortable` | Lists with the same group exchange items. Default: the list id (no exchange). |
| `getItems()` | `sortable` | Ids of the items, in order. |
| `getLabel(id)` | `sortable` | Name of an item for announcements. Default: its text. |
| `label` | all | Name of the list, zone or item for announcements. Default: the id. |
| `axis` | `sortable` | `"y"` (default) or `"x"`. |
| `handle` | `sortable`, `draggable` | CSS selector of the element that starts a drag. Default: the whole item. |
| `disabled` | all | Turns the container or item off. |
| `accepts(id, data)` | `dropzone` | Return `false` to refuse an item. |
| `data` | `draggable` | Anything you want back in `onDrop`. |
| `onDrop(e)` | `sortable`, `dropzone` | `{ id, data, from, to }`. The only place to change state. |

`useDnd` also takes `{ messages, threshold, holdMs, edge }` to override the screen reader strings and the timings.

### Styling hooks

The engine sets attributes you can style; the package ships defaults for them.

| Hook | Where | Meaning |
|---|---|---|
| `data-dnd-item` | item | You set it to the item id. |
| `data-dnd-dragging` | item | The item being dragged (its slot). |
| `data-dnd-pressing` | item | Touch press, before the hold completes. |
| `data-dnd-over` | list or zone | The pointer or keyboard target. |
| `data-dnd-zone` | zone | Set on every drop zone. |
| `html[data-dnd-active]` | `<html>` | A drag is running. |
| `.ca-dnd-overlay`, `.ca-dnd-indicator` | `<body>` | The clone and the drop line. |

Under `forced-colors: active` the indicator and the outlines use system colors.

---

# Surface

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/surface/

The painted container every card and panel is built on: elevation, material, tone, variant and radius as independent props.

```svelte
<script>
  import { Surface } from "@codeatlasdev/ui";
</script>

<Surface elevation={2} tone="brand" p="4">…</Surface>
<Surface as="section" material="glass" elevation={4}>…</Surface>
```

A Surface is one element painted by one CSS rule (`.ca-surface`). Each prop is a `data-*` attribute, and each attribute writes different `--ca-surface-*` variables, so the axes never fight: `elevation` is depth (shadow and the blur/fill tier), `material` is what the surface is made of, `tone` tints it, `variant` removes the fill or draws an outline, `radius` rounds it. Nothing is written to `style`.

`material="auto"` follows the theme: it reads the tokens that `<html data-style>` already rewrites, so an app on the default solid style gets opaque surfaces and one on the [`liquid` recipe](/docs/getting-started/theming/#surface-styles) gets glass, with no change to the component. The explicit materials ignore `data-style`: use `glass` for one blurred surface in a solid app, or `solid` to keep one opaque in a glass app. `liquid` is `glass` plus the SVG refraction layer, see [LiquidGlass](/docs/surfaces/liquid-glass/). Glass needs something behind it to blur, which is why the demos sit on a gradient.

Rules the CSS follows, and you should too when you wrap a Surface: never `will-change: transform` on it or an ancestor, and never `isolation: isolate` on a parent of a glass or frosted surface. Both silently remove the backdrop blur. Under `prefers-reduced-transparency` translucent fills become opaque, and under `forced-colors` every surface gets a real `CanvasText` border, except `variant="ghost"`.

### Materials

### Elevation

### Tone and variant

### Interactive

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `as` | `string` | 'div' | Element to render (`section`, `a`, `button`, `li`...). |
| `elevation` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` | 1 | Depth: drop shadow, and the blur/fill tier of the material. |
| `material` | `'auto' \| 'solid' \| 'frosted' \| 'glass' \| 'liquid'` | 'auto' | `auto` follows `<html data-style>`; the others are absolute. `liquid` adds the SVG refraction layer. |
| `tone` | `'neutral' \| 'brand' \| 'success' \| 'warning' \| 'error' \| 'info'` | 'neutral' | Semantic tint over the fill; the outline color of `variant="outlined"`. |
| `variant` | `'filled' \| 'outlined' \| 'ghost'` | 'filled' | `outlined` has an edge and no fill, `ghost` neither. |
| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'pill'` | undefined | Corner radius from the radius scale. Omit for the large radius (`--ca-radius-lg`). |
| `interactive` | `boolean` | false | Hover, press and focus-visible states and a pointer cursor. Render a link or button, or give it a role and a name. |
| `glow` | `boolean` | false | Brand halo behind the surface (a shadow, so it needs no isolation). It uses `--ca-glow-primary`, which is transparent under the `solid` and `flat` styles, so it only shows under styles that keep a glow, such as `glass`. |
| `p, px, py` | `Space \| responsive` | undefined | Padding as a spacing step (`"4"` = 16px). See [Layout primitives](/docs/layout/layout-primitives/). |
| `class` | `string` | '' | Extra class names. Other attributes are forwarded to the element. |
| `children` | `Snippet` | undefined | Content. |

## Data attributes

The attributes are part of the public CSS contract, so an app can restyle one axis without touching the component: `[data-elevation="0"]`, `[data-material="glass"]`, `[data-tone="error"]`, `[data-variant="ghost"]`, `[data-radius="pill"]`, `[data-interactive]`, `[data-glow]`.

## SurfacePanel

`SurfacePanel` is a Surface at elevation 2 that renders a `<section>`. With an accessible name (`aria-label` or `aria-labelledby`) it is a region landmark: a filter bar, a settings group, a summary beside a table. It is not the AppShell sidebar `Panel`.

---

# Card

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/card/

A Surface with a header, padding and an optional link: the default container for content sections.

```svelte
<script>
  import { Card } from "@codeatlasdev/ui";
</script>

<Card title="Team" headingLevel={2} tone="brand">…</Card>
```

Card is a [Surface](/docs/surfaces/surface/) with a header (`title`, `headerActions`), padding from `--ca-card-padding` and an optional link. Every Surface prop passes through (`elevation`, `material`, `tone`, `variant`, `radius`, `glow`, `interactive`), and `material="auto"` follows the theme: opaque under the default solid style, glass under `liquid`. The demos below set `material="glass"` so they look the same under any style. Use `flush` for content that touches the edges, such as tables, images and code.

**The content is already padded.** Card pads its children with `--ca-card-padding` (20px). A wrapper that adds its own padding (`<Card><div class="box">…</div></Card>` with `.box { padding: 1.25rem }`) doubles it to 40px, the usual cause of an oversized card. Remove the wrapper padding, pick a density with `padding` (`'none'`, `'sm'`, `'md'`, `'lg'`, a CSS length or a number of pixels), or use `flush` when you bring your own layout. In development a `[ca-ui]` warning names the mistake when the first child is padded. To change the default for the whole app, override `--ca-card-padding` on `:root`.

`title` is a paragraph unless you pass `headingLevel`, so adding a Card never changes a page outline by accident. Pass `headingLevel` to make the card a section under the page heading (a `PageShell` title is the `<h1>`, so cards start at `2`). Only the tag changes, never the look.

With `href` the card is a single `<a>` and is interactive. The link name comes from the content, so give the card a `title`.

### Content card

### Stat cards

### Tone and glow

### Header and actions

### Link card

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` | undefined | Header title. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | undefined | Renders `title` as `<h2>`–`<h6>` so the card is a section in the page outline. Omit for a plain paragraph. |
| `headerActions` | `Snippet` | undefined | Actions aligned to the end of the header. |
| `href` | `string` | undefined | Renders the card as a link (`<a>`, interactive). |
| `target` | `string` | undefined | Link target. `_blank` also sets `rel="noopener noreferrer"`. |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| string \| number` | 'md' | Content padding: 0, 12px, 20px, 32px, or a CSS length / number of pixels. Sets `--ca-card-padding` on this card only. |
| `flush` | `boolean` | false | Removes all padding. Alias of `padding="none"`, and wins over `padding`. |
| `full` | `boolean` | false | Sets `width: 100%`. |
| `elevation, material, tone, variant, radius, glow, interactive` | `Surface props` | see Surface | Passed to the underlying [Surface](/docs/surfaces/surface/). |
| `skeleton` | `boolean` | false | Loading placeholder: content keeps its layout but is hidden, so the card has the exact loaded size. See Skeleton. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Card content. |

---

# Accordion

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/accordion/

Vertically stacked collapsible sections with one or many items open at once.

```svelte
<script>
  import { Accordion, AccordionItem } from "@codeatlasdev/ui";
</script>

<Accordion type="single">
  <AccordionItem value="a" title="Question">Answer</AccordionItem>
</Accordion>
```

Triggers are buttons with `aria-expanded`. Arrow Up, Arrow Down, Home and End move focus between the enabled triggers, and every trigger stays in the tab order. With `type="single"` the bound `value` is a string, with `type="multiple"` it is a string array.

### Single

### Multiple

### Controlled

### Accordion props

| Prop | Type | Default | Description |
|---|---|---|---|
| `type` | `'single' \| 'multiple'` | 'single' | Whether one or many items can be open. |
| `value` | `string \| string[]` | undefined | Open item value(s): a string for `single` (`''` when none is open), an array for `multiple`. Bindable. |
| `onValueChange` | `(value: string \| string[]) => void` | undefined | Called when the open items change. |
| `class` | `string` | '' | Extra class names on the root. |
| `children` | `Snippet` | undefined | `AccordionItem` children. |

### AccordionItem props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Unique key of the item. Required. |
| `title` | `string` |  | Trigger label. Required. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Body shown when expanded. |

---

# Collapsible

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/collapsible/

A single toggle panel, simpler than Accordion when you only need one.

```svelte
<script>
  import { Collapsible } from "@codeatlasdev/ui";
</script>

<Collapsible title="Details" bind:open>…</Collapsible>
```

The trigger is a button with `aria-expanded`. Use [Accordion](/docs/surfaces/accordion/) when several related panels should coordinate.

### Default (closed)

### Open by default

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Trigger label. Required. |
| `open` | `boolean` | false | Expanded state. Bindable. |
| `disabled` | `boolean` | false | Prevents toggling. |
| `onOpenChange` | `(open: boolean) => void` | undefined | Called when the state changes. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Panel content. |

---

# Glass Card

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/glass-card/

Deprecated: use Card. GlassCard is kept until the next major version.

`GlassCard` is replaced by [Card](/docs/surfaces/card/) and removed in the next major version. It still works and looks the same: it renders a Card, keeps its `ca-glass-card*` and `glass*` classes, and logs a `[ca-ui]` warning in development.

```sh
bunx @codeatlasdev/ui migrate --write src
```

The codemod rewrites each static usage and leaves dynamic ones (`thickness={t}`) for you. `GlassCard` followed the theme (`<html data-style>`), so the replacement for an unchanged look is `<Card>` with `material="auto"`, which is the default; the codemod writes `material="glass"` so the result is glass in every theme, as the name promised.

```svelte
<!-- before -->
<GlassCard thickness="thick" tinted glowing padding="24px" title="Team">…</GlassCard>

<!-- after -->
<Card material="glass" elevation={4} tone="brand" glow p="6" title="Team">…</Card>
```

| GlassCard | Card |
|---|---|
| `thickness="ultra-thin"` `"thin"` `"regular"` `"thick"` `"chrome"` | `elevation={1}` `{2}` `{3}` `{4}` `{5}` |
| no `thickness` (default `"regular"`) | `elevation={3}`, always written: `Card` itself defaults to `elevation={1}` |
| `tinted` | `tone="brand"` |
| `glowing` | `glow` |
| `padding="24px"` | `p="6"` (a spacing step) |
| `title`, `headingLevel`, `headerActions`, `href`, `target`, `flush`, `full`, `skeleton`, `class` | unchanged |

| Class | Replacement |
|---|---|
| `.ca-glass-card`, `.ca-glass-card--flush`, `.ca-glass-card--full` | `.ca-card`, `.ca-card--flush`, `.ca-card--full` |
| `.ca-glass-card__header`, `__title`, `__header-actions` | `.ca-card__header`, `__title`, `__header-actions` |

---

# Glass Surface

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/glass-surface/

Deprecated: use Surface. GlassSurface is kept until the next major version.

`GlassSurface` is replaced by [Surface](/docs/surfaces/surface/) and removed in the next major version. It still works and looks the same: it renders a Surface, keeps its `glass*` classes, and logs a `[ca-ui]` warning in development.

```sh
bunx @codeatlasdev/ui migrate --write src
```

```svelte
<!-- before -->
<GlassSurface thickness="thick" tinted glowing>…</GlassSurface>

<!-- after -->
<Surface material="liquid" elevation={4} tone="brand" glow>…</Surface>
```

| GlassSurface | Surface |
|---|---|
| `thickness="ultra-thin"` `"thin"` `"regular"` `"thick"` `"chrome"` | `elevation={1}` `{2}` `{3}` `{4}` `{5}` |
| no `thickness` (default `"regular"`) | `elevation={3}`, always written: `Surface` itself defaults to `elevation={1}` |
| `tinted` | `tone="brand"` |
| `glowing` | `glow` |
| `refraction` (default `true`) | `material="liquid"`; `refraction={false}` is `material="glass"` |
| `class`, `style`, other attributes | unchanged (use `p` / `as` instead of a padding style) |

`GlassSurface` followed the theme (`<html data-style>`) through its `glass*` classes, and drew the refraction layer when `refraction` was on. The codemod writes `material="liquid"` (or `"glass"`), so the result is glass in every theme, as the name promised.

Dynamic props (`thickness={t}`) are not rewritten by the codemod: map them by hand with the table above.

---

# LiquidGlass

Group: Surfaces. URL: https://ui.codeatlas.com.br/docs/surfaces/liquid-glass/

The SVG refraction layer that Surface paints when material is "liquid". Use it directly only for a custom glass container.

```svelte
<script>
  import { LiquidGlass, GLASS_OPTICS } from "@codeatlasdev/ui";
</script>

<div class="my-glass">
  <LiquidGlass optics={GLASS_OPTICS.regular} />
  <slot />
</div>
```

You rarely need this. [Surface](/docs/surfaces/surface/) with `material="liquid"` renders `LiquidGlass` for you and picks the optics from its `elevation`. The component is an absolutely positioned, `aria-hidden` SVG that fills its parent and inherits the parent's border radius, so the parent needs `position: relative` and `overflow: hidden`. It only adds the refraction; the blur, tint and border come from the glass material classes on the parent.

`GLASS_OPTICS` maps each material thickness (`ultra-thin`, `thin`, `regular`, `thick`, `chrome`) to a ready-made `optics` object.

### Refraction layer

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `optics` | `{ frost, bend, depth, curvature, sheen, dispersion: number }` |  | Optical parameters of the refraction filter. Required. Take one from `GLASS_OPTICS`. |
| `style` | `string` | '' | Extra inline style for the SVG. |

---

# Export Menu

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/export-menu/

An Export button with a CSV and JSON menu that builds and downloads the file in the browser.

```svelte
<script>
  import { ExportMenu } from "@codeatlasdev/ui";
</script>

<ExportMenu data={rows} filename="domains" />
```

`ExportMenu` is a `DropdownMenu` with CSV and JSON items. Choosing one builds the file from `data`, downloads it and announces "Exported 3 rows as CSV" politely. It is disabled while `data` is empty. Pass all rows, not only the visible page.

CSV is RFC 4180 (CRLF, quoted fields) with a UTF-8 BOM in the downloaded file so Excel reads accents correctly. Text cells that start with `=`, `+`, `-` or `@` get a leading `'` so a spreadsheet never runs them as a formula (CSV injection). Numbers are left as they are.

### Default

Custom column order and headers. onexport receives the generated text, handy for tests or uploads.

## Helpers

The same logic is exported for custom UI:

```ts
import { toCsv, toJson, downloadFile } from "@codeatlasdev/ui";

downloadFile("domains.csv", toCsv(rows, columns), "text/csv;charset=utf-8");
```

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `readonly T[]` |  | Rows to export. |
| `filename` | `string` | 'export' | File name without extension. |
| `columns` | `ExportColumn<T>[]` |  | `{ key, header?, value? }` per column: header defaults to key, value overrides row[key]. Defaults to the keys of the first row. |
| `formats` | `('csv' \| 'json')[]` | ['csv', 'json'] | Formats offered, in menu order. |
| `label` | `string` | 'Export' (localized) | Button label. |
| `variant` | `'filled' \| 'glass' \| 'outlined' \| 'ghost'` | 'outlined' | Button variant. |
| `size` | `'sm' \| 'md' \| 'lg'` | 'md' | Button size. |
| `disabled` | `boolean` | false | Disables the button. |
| `onexport` | `(e: { format, filename, content, rows }) => void` |  | Called after each export with the generated text. |
| `class` | `string` | '' | Extra class on the menu content. |

---

# FilterGroup

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/filter-group/

Inline filter chips for list toolbars, with an automatic "All" option.

```svelte
<script>
  import { FilterGroup } from "@codeatlasdev/ui";

  let role = $state("all");
</script>

<FilterGroup
  label="Role"
  options={[{ value: "admin", label: "Admin" }, { value: "editor", label: "Editor" }]}
  bind:value={role}
/>
```

An "All" option is added in front of `options` and the value is `'all'` when nothing is filtered. Clicking the active option clears the filter and goes back to `'all'`. Inside [AppList](/docs/layout/list-page/), render it in the `filters` snippet and connect it to `list.setFilter`.

### Role filter

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `options` | `{ value: string; label: string }[]` |  | Filter choices. Required. |
| `value` | `string` | 'all' | Bindable selected value. |
| `label` | `string` |  | Text shown before the chips. |
| `onchange` | `(value: string) => void` |  | Called when the selection changes. |
| `class` | `string` | '' | Extra classes on the root. |

---

# SettingItem

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/setting-item/

A settings row with a label, a description and one control on the right.

```svelte
<script>
  import { SettingItem, Switch } from "@codeatlasdev/ui";

  let email = $state(true);
</script>

<SettingItem label="Email notifications" description="Receive an email for every mention.">
  <Switch bind:checked={email} />
</SettingItem>
```

The row is a `<label>`, so clicking the text activates the first control inside it (a `Switch`, an input, a select or a button) and names it for assistive technology. Use it inside [AppSettings](/docs/layout/list-page/) tabs.

### Switch rows

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | Setting name. Required. |
| `description` | `string` |  | Help text under the label. |
| `children` | `Snippet` |  | The control, placed on the right. |
| `class` | `string` | '' | Extra classes on the root. |

---

# Button

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/button/

Trigger actions with five visual variants, three sizes, leading and trailing icons, and a loading state.

```svelte
<script>
  import { Button } from "@codeatlasdev/ui";
</script>

<Button variant="filled" onclick={save}>Save</Button>
```

On touch devices every size grows to a 44px target and presses scale down slightly, like a native control.

### Variants

filled, glass, outlined, ghost and destructive.

### Sizes

### With icons

Leading and trailing snippets.

### Loading

Swaps the leading icon for a spinner, sets aria-busy and blocks clicks while keeping the label.

### States

Disabled buttons, a destructive action and a link rendered as a button.

### Full width

fullWidth stretches the button to its container.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `'filled' \| 'glass' \| 'outlined' \| 'ghost' \| 'destructive'` | 'filled' | Visual style. |
| `size` | `'sm' \| 'md' \| 'lg'` | 'md' | Height, padding and font size. |
| `disabled` | `boolean` | false | Prevents interaction. |
| `loading` | `boolean` | false | Shows a spinner in place of leading, sets aria-busy, blocks interaction and keeps the label. Adds ca-btn--loading. Screen readers hear "Finished loading" when it ends. |
| `type` | `'button' \| 'submit' \| 'reset' \| string` | 'button' | Without href: the HTML button type. With href: the MIME type hint of the linked resource. |
| `fullWidth` | `boolean` | false | Stretches the button to the width of its container. |
| `href` | `string` |  | Renders an anchor styled as a button. The props then accept the anchor's attributes: download, rel, hreflang, ping, referrerpolicy. |
| `target` | `string` |  | Anchor target, used with href. "_blank" adds rel="noopener noreferrer" to any rel you pass. |
| `children` | `Snippet` |  | Button label. |
| `leading` | `Snippet` |  | Content before the label. Replaced by a spinner while loading. |
| `trailing` | `Snippet` |  | Content after the label. |
| `onclick` | `(e: MouseEvent) => void` |  | Click handler. Not called while disabled or loading. |
| `aria-label` | `string` |  | Accessible name for icon-only buttons. |
| `class` | `string` |  | Extra classes on the root element. |

---

# Checkbox

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/checkbox/

Binary or indeterminate selection control with full keyboard support.

```svelte
<script>
  import { Checkbox } from "@codeatlasdev/ui";
  let accepted = $state(false);
</script>

<Checkbox label="I accept the terms" bind:checked={accepted} />
```

A checkbox rendered without `label` (for example in a table row) needs an `aria-label`. Space toggles it. Any other native attribute or handler (`data-*`, `id`, `onclick`, `onkeydown`, `aria-describedby`, `value`...) is forwarded to the native `<input>`, and `ref` gives you that input.

### States

Unchecked, checked and indeterminate.

### Disabled

### Without label

Bare checkbox for table rows or custom layouts.

### Shift range selection

onclick is forwarded to the input and runs just before onchange, so shiftKey is readable. data-testid reaches the input.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `checked` | `boolean` | false | Bindable checked state. |
| `indeterminate` | `boolean` | false | Renders the mixed state. |
| `disabled` | `boolean` | false | Disables interaction. |
| `name` | `string` |  | Native name, so the checkbox is in FormData on a plain form submit (value `on` when checked, absent when not). |
| `label` | `string` |  | Visible label rendered beside the checkbox. |
| `aria-label` | `string` |  | Accessible name used when no visible label is rendered. |
| `aria-labelledby` | `string` |  | Id of an element that names the checkbox. Ignored when label is set. |
| `class` | `string` |  | Extra classes on the wrapper. |
| `ref` | `HTMLInputElement \| null` |  | Bindable native input element. |
| `onchange` | `(checked: boolean, event: Event) => void` |  | Called when the checked state changes, with the native change event. |

---

# Combobox

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/combobox/

Select with built-in search for long option lists.

```svelte
<script>
  import { Combobox } from "@codeatlasdev/ui";
  let value = $state("");
</script>

<Combobox label="Framework" options={[{ value: "svelte", label: "Svelte" }]} bind:value />
```

Typing in the popup filters options by label, and opening the list moves focus to the search input. Pass a `label` (or `ariaLabel`) so the trigger and listbox have an accessible name. It has no `name` prop and does not submit with a native form (unlike `Select`): read `value` instead.

### Basic

Search a list of options and bind the selected value.

### States

Description, custom search placeholder and empty text, disabled option, error and disabled.

## Multiple selection

Set `multiple` and bind `value` to a `string[]`. The popup becomes a `listbox` with `aria-multiselectable`, each pick toggles its option (`aria-selected`) and the list stays open so you can keep picking. Selected values show as removable chips above the trigger, and the trigger shows the count. With the search input focused, `Enter` toggles the highlighted option and `Backspace` on an empty query removes the last chip.

Add `creatable` to offer a `Create "text"` row when the query matches no option exactly. Choosing it appends the text to `value` and calls `oncreate(text)`: add it to `options` there if you want it to stay selectable. In single mode `creatable` sets `value` to the new text and closes the list.

### Multiple

Searchable multi-select with removable chips and a disabled option.

### Creatable tags

Create a tag from the search text when nothing matches.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string \| string[]` | '' (or [] when multiple) | Bindable selected value. A `string[]` when `multiple` is set. |
| `multiple` | `boolean` | false | Multi-select: `value` is `string[]`, the list stays open after each pick, selections render as removable chips. |
| `creatable` | `boolean` | false | Offers a `Create "query"` row when the query matches no option label exactly. |
| `oncreate` | `(value: string) => void` |  | Called with the new text when the create row is chosen. |
| `options` | `ComboboxOption[]` |  | Options: { value, label, disabled? }. |
| `label` | `string` |  | Visible label above the trigger. |
| `ariaLabel` | `string` |  | Accessible name when there is no visible `label`. The trigger is named `ariaLabel` followed by its current value. Without either, it is named only by its current value. |
| `placeholder` | `string` | 'Select…' (localized) | Trigger text when nothing is selected. Default comes from the active i18n catalog. |
| `searchPlaceholder` | `string` | 'Search…' (localized) | Placeholder and accessible name of the search input. |
| `emptyText` | `string` | 'No results' (localized) | Message shown when the filter matches nothing. |
| `description` | `string` |  | Hint shown below the trigger. |
| `error` | `string` |  | Error message. Puts the combobox in the error state. |
| `required` | `boolean` | false | Marks the field as required. |
| `disabled` | `boolean` | false | Disables the combobox. |
| `size` | `'sm' \| 'md'` | 'md' | Trigger height. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: string \| string[]) => void` |  | Called when the selection changes. Receives the array when `multiple`. |

---

# CopyButton

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/copy-button/

Copies a string to the clipboard, swaps the icon to a check for 2 seconds and announces the result to screen readers.

```svelte
<script>
  import { CopyButton } from "@codeatlasdev/ui";
</script>

<CopyButton value="npm i @codeatlasdev/ui" />
```

The result is announced through a polite live region (`Copied`), and a failed copy raises an error toast. For a success toast, pass `toast` and mount a `<Toaster />` once in your layout. An icon-only button (`label=""`) is named from the localized `Copy` label by default. In a list or table every row would then announce the same name, so pass a distinct `aria-label` per row (`aria-label="Copy client_id of Acme"`). Other attributes (`id`, `data-*`, `aria-describedby`) go to the underlying button. Default labels come from the active i18n catalog.

### Default

### Variants and sizes

### Icon only and toast

label=&quot;&quot; renders an icon-only button. toast shows a success message after copying.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Text copied to the clipboard. |
| `label` | `string` | 'Copy' (localized) | Visible label. '' renders an icon-only button. |
| `size` | `'sm' \| 'md' \| 'lg'` | 'md' | Button size. |
| `variant` | `'filled' \| 'glass' \| 'outlined' \| 'ghost'` | 'ghost' | Button style. |
| `aria-label` | `string` | 'Copy' (localized) | Accessible name of the icon-only button. Use one per row in lists. Ignored when `label` is visible. |
| `toast` | `string` |  | Success toast message. Omit for no toast. |
| `class` | `string` |  | Extra classes on the button. |
| `oncopy` | `(value: string) => void` |  | Called after a successful copy. |

---

# Date and time

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/date-picker/

DatePicker, DateRangePicker, DateField, TimeField, Calendar and RangeCalendar, fully keyboard operable.

```svelte
<script>
  import { DatePicker, CalendarDate } from "@codeatlasdev/ui";
  let date = $state(new CalendarDate(2026, 10, 10));
</script>

<DatePicker label="Delivery date" bind:value={date} />
```

Values are `@internationalized/date` objects. `CalendarDate`, `Time`, `today`, `getLocalTimeZone` and the `DateValue`, `DateRange` and `TimeValue` types are re-exported from `@codeatlasdev/ui`, so you do not need that package as a direct dependency.

The default `locale` is `pt-BR` with Monday-first weeks. The demos below pass `locale="en-US"` and `weekStartsOn={0}` to show the English format.

**Keyboard.** In field segments, type digits or use the up and down arrows to change a value, and the left and right arrows or Tab to move between segments. In a calendar, left and right move by day, up and down by week, PageUp and PageDown by month, Shift with PageUp or PageDown by year, Home and End to the week edges, Enter or Space selects, and Escape closes the popover.

An `error` is rendered with `role="alert"` and sets `aria-invalid` and `aria-describedby`. Clicking a field `label` focuses its first segment.

### DatePicker and DateRangePicker

Editable segments plus a calendar popover. The range picker shows two months.

### DateField and TimeField

Segments only, no popover. granularity=&quot;minute&quot; adds a time, and hourCycle switches between 12h and 24h.

### Calendar and RangeCalendar

Inline calendars. Click a start date, then an end date for the range.

### Min, max, error and disabled

Only the next 30 days are selectable. Out-of-range days are disabled and typed values become invalid.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | Field label. On Calendar and RangeCalendar it is the screen-reader label. |
| `description` | `string` |  | Hint below the field (aria-describedby). Pickers and fields only. |
| `error` | `string` |  | Error message (role="alert"). Sets aria-invalid and the error style. Pickers and fields only. |
| `disabled` | `boolean` | false | Disables the field and popover. |
| `readonly` | `boolean` | false | Shows the value without allowing edits. |
| `required` | `boolean` | false | Marks the field as required. Pickers and fields only. |
| `value` | `DateValue \| DateRange \| Time` |  | Bindable. DateValue for DatePicker, DateField and Calendar, DateRange for the range components, Time for TimeField. |
| `placeholder` | `DateValue \| TimeValue` |  | Bindable. Controls the visible month, or the starting point of an empty field. |
| `locale` | `string` | 'pt-BR' | Intl locale for segments, month and weekday names. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | 1 | First day of the week (0 is Sunday). Calendars and pickers. |
| `minValue` | `DateValue` |  | Lower bound. Out-of-range days are disabled and typed values become invalid. |
| `maxValue` | `DateValue` |  | Upper bound. |
| `granularity` | `'day' \| 'hour' \| 'minute' \| 'second'` | 'day' (TimeField: 'minute') | Which segments are shown. TimeField accepts hour, minute and second. |
| `hourCycle` | `12 \| 24` |  | DateField and TimeField. Defaults to the locale (pt-BR is 24h). |
| `open` | `boolean` | false | Bindable popover state. DatePicker and DateRangePicker. |
| `numberOfMonths` | `number` | 1 (range components: 2) | Months shown side by side. |
| `fixedWeeks` | `boolean` | false | Always render six weeks. Calendar and RangeCalendar. |
| `isDateDisabled` | `(d: DateValue) => boolean` |  | Disables matching dates. Calendars and pickers. |
| `isDateUnavailable` | `(d: DateValue) => boolean` |  | Marks matching dates as unavailable. Calendars and pickers. |
| `closeOnDateSelect` | `boolean` | true | DatePicker: close the popover after picking a date. |
| `closeOnRangeSelect` | `boolean` | true | DateRangePicker: close the popover once the range is complete. |
| `size` | `'sm' \| 'md'` | 'md' | Field height. Pickers and fields. |
| `name` | `string` |  | Name of the hidden input (ISO string) for native forms. DatePicker, DateField and TimeField. |
| `triggerLabel` | `string` | 'Open calendar' (localized) | aria-label of the calendar button. Pickers. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value) => void` |  | Called when the value changes. Receives DateValue \| undefined, DateRange or Time \| undefined depending on the component. |

---

# FileUpload

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/file-upload/

Drag and drop zone for selecting files, with type and size validation.

```svelte
<script>
  import { FileUpload } from "@codeatlasdev/ui";
  let files = $state([]);
</script>

<FileUpload bind:files multiple accept="image/*" maxSize={10 * 1024 * 1024} />
```

The drop zone is a keyboard-operable control: Enter or Space opens the file picker. Files larger than `maxSize` are rejected with a per-file error message. In `multiple` mode new picks are appended to `files`, otherwise they replace it. The component never uploads: send `files` to your API yourself.

Native input attributes (`name`, `capture`, `data-*`...) are spread on the `<input type="file">`, and `bind:ref` gives you that input. To open the picker from a button elsewhere, keep the component instance with `bind:this` and call `open()` (a no-op while `disabled`). For apps that upload on pick and draw their own progress, set `list={false}`: `onchange` receives only the files just picked, nothing is kept in `files`, and the built-in list is not rendered.

### Basic

Multiple files with a size limit and the selected count.

### Images only and disabled

### External trigger, no list

list={false} plus an Add files button that calls open().

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `files` | `File[]` | [] | Bindable list of selected files. |
| `accept` | `string` |  | Accepted types, for example "image/*,.pdf". Shown as the hint when hint is not set. |
| `multiple` | `boolean` | false | Allows selecting multiple files. |
| `maxSize` | `number` |  | Maximum file size in bytes. Larger files are rejected with an error. |
| `label` | `string` | 'Drop files here or click to browse' (localized) | Drop zone text and accessible name. |
| `hint` | `string` |  | Helper text below the label. |
| `list` | `boolean` | true | Shows the built-in file list. `false` makes a plain picker: `onchange` gets only the newly picked files and `files` is not kept. |
| `ref` | `HTMLInputElement \| null` |  | Bindable native file input. |
| `disabled` | `boolean` | false | Disables the upload. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(files: File[]) => void` |  | Called when the file list changes. |
| `children` | `Snippet` |  | Custom content inside the drop zone. |

---

# MaskedField

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/masked-field/

Text input with live formatting for Brazilian documents, phone numbers, CEP and dates.

```svelte
<script>
  import { MaskedField, maskCPF, isValidCPF } from "@codeatlasdev/ui/forms";
  let cpf = $state("");
</script>

<MaskedField
  label="CPF"
  mask={maskCPF}
  validate={(v) => (isValidCPF(v) ? undefined : "Invalid CPF")}
  bind:value={cpf}
/>
```

These components live in the `@codeatlasdev/ui/forms` subpath. A `mask` is a pure function from raw text to formatted text, so you can write your own. `MaskedField` renders a [TextField](/docs/inputs/text-field/) and forwards its props. Digit-only masks set `inputmode="numeric"` automatically.

The package never makes network requests. `CepField` only calls the `onlookup` function you inject (for example a ViaCEP client) once 8 digits are typed.

Documents try these values: CPF `123.456.789-09` is valid and `111.111.111-11` is invalid. Validation runs on blur.

### Documents and dates

CPF, CNPJ, a mask that switches after 11 digits, a birth date and RG.

### Phone and CEP

PhoneField binds E.164 (+55...) while showing the masked form. CepField resolves an address through onlookup. Try 01310-100.

### use:mask action

Apply any pure mask to a plain input. The caret stays on the same digit.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `mask` | `(raw: string) => string` |  | Required. Pure formatter applied while typing, for example maskCPF. |
| `validate` | `(value: string) => string \| undefined` |  | Returns an error message on blur for non-empty values, or undefined when valid. |
| `inputmode` | `HTMLInputAttributes['inputmode']` | auto | Defaults to 'numeric' for digit-only masks and 'text' otherwise. |
| `value` | `string` | '' | Bindable masked value (what the user sees). |
| `error` | `string` |  | External error. Takes precedence over the validate result. |
| `label` | `string` |  | Label text. |
| `placeholder` | `string` |  | Input placeholder. |
| `description` | `string` |  | Hint shown below the field. |
| `disabled` | `boolean` | false | Disables the input. |
| `required` | `boolean` | false | Marks the field as required. |
| `readonly` | `boolean` | false | Makes the input read-only. |
| `autocomplete` | `HTMLInputAttributes['autocomplete']` |  | Native autocomplete hint. |
| `leading / trailing` | `Snippet` |  | Content before or after the input. |
| `size` | `'sm' \| 'md'` | 'md' | Field height. |
| `name` | `string` |  | Native name, for form submission. |
| `oninput / onchange` | `(value: string) => void` |  | Called with the masked value. |
| `onblur` | `(e: FocusEvent) => void` |  | Called when the input loses focus. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `PhoneField.value` | `string` | '' | Bindable E.164 value (+5511987654321). Empty while the number is incomplete or empty. |
| `PhoneField.country` | `'BR'` | 'BR' | Only BR is supported today. |
| `PhoneField.placeholder` | `string` | '(11) 98765-4321' | Input placeholder. |
| `CepField.value` | `string` | '' | Bindable masked CEP (01310-100). |
| `CepField.onlookup` | `(cep: string) => Promise<CepAddress \| null>` |  | Injected lookup. Receives 8 digits. Return null for an unknown CEP. |
| `CepField.onresolve` | `(address: CepAddress) => void` |  | Called with the address after a successful lookup. |
| `CepField.lookupPending` | `boolean` | false | Bindable. True while onlookup is in flight. |
| `CepField.placeholder` | `string` | '00000-000' | Input placeholder. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `maskCPF / maskCNPJ / maskCPFCNPJ` | `(raw: string) => string` |  | Document masks. maskCPFCNPJ switches after 11 digits. |
| `maskDateBR / maskRG / maskCEP / maskPhoneBR` | `(raw: string) => string` |  | Date (dd/mm/yyyy), RG, CEP and Brazilian phone masks. |
| `isValidCPF / isValidCNPJ / isValidDateBR` | `(value: string) => boolean` |  | Validators for use in validate. |
| `mask` | `Action<HTMLInputElement, (raw: string) => string>` |  | Svelte action that applies a mask to any input. |

---

# MoneyInput

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/money-input/

Currency field. The bound value is an integer in the currency's minor unit and the display is formatted as you type. BRL by default.

```svelte
<script>
  import { MoneyInput } from "@codeatlasdev/ui/forms";
  let price = $state(123456); // R$ 1.234,56
</script>

<MoneyInput label="Price" bind:value={price} />
```

Import from the `@codeatlasdev/ui/forms` subpath. The value is always an integer in the currency's minor unit (cents for BRL and USD, whole yen for JPY), so there is no floating-point rounding. Digits shift in from the right: typing `123456` gives `R$ 1.234,56`. `min` and `max` clamp the value, and an out-of-range value set from outside is clamped back into `value`.

`centsToDisplay` returns the text exactly as `Intl` formats it, including the no-break space (U+00A0) between the symbol and the number, so a price in a narrow slot never wraps between `R$` and the amount. The input's own text uses a plain space instead, which is what `parseInputToCents` and the user type, so compare with `centsToDisplay(v).replace(/\u00a0/g, " ")` when you need that form.

### Default

Type 123456 to get R$ 1.234,56.

### Min, max, negative, error and disabled

Deposit is clamped between R$ 10,00 and R$ 100,00. Include a minus sign to toggle the sign when allowNegative is set.

### Currency and locale

currency picks the minor unit (USD 2 decimals, JPY none); locale picks separators and symbol placement.

### Helpers

Pure functions exported from @codeatlasdev/ui/forms.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` | 0 | Bindable amount in the currency's minor unit (integer). |
| `currency` | `string` | 'BRL' | ISO 4217 code. Decimals come from Intl: USD 2, JPY 0, BHD 3. |
| `locale` | `string` |  | BCP 47 tag for separators and symbol placement. Defaults to the active i18n locale when currency is set, and to 'pt-BR' when it is not, so the BRL default keeps its format. |
| `min` | `number` |  | Minimum value in cents. |
| `max` | `number` |  | Maximum value in cents. |
| `allowNegative` | `boolean` | false | Accepts negative amounts. Type a minus sign to toggle. |
| `label` | `string` |  | Label text. |
| `placeholder` | `string` | the formatted zero amount | Input placeholder. |
| `error` | `string` |  | Error message. Puts the field in the error state. |
| `description` | `string` |  | Hint shown below the field. |
| `disabled` | `boolean` | false | Disables the input. |
| `required` | `boolean` | false | Marks the field as required. |
| `readonly` | `boolean` | false | Makes the input read-only. |
| `size` | `'sm' \| 'md'` | 'md' | Field height. |
| `name` | `string` |  | Native name, for form submission. |
| `leading / trailing` | `Snippet` |  | Content before or after the input. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(cents: number) => void` |  | Called on every edit with the new cents value. |
| `onblur` | `(e: FocusEvent) => void` |  | Called when the input loses focus. The display is re-formatted first. |

---

# NumberField

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/number-field/

Stepper input for numeric values with optional min, max and step.

```svelte
<script>
  import { NumberField } from "@codeatlasdev/ui";
  let qty = $state(1);
</script>

<NumberField label="Quantity" bind:value={qty} min={0} max={99} />
```

The plus and minus buttons stop at `min` and `max`. Typing a value does not clamp it, so validate on your side if a typed value can leave the range.

### Basic

Integer and decimal steps with bounds.

### States

Helper text, error, disabled and the small size.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` | 0 | Bindable numeric value. |
| `min` | `number` |  | Minimum value. The decrement button disables at this value. |
| `max` | `number` |  | Maximum value. The increment button disables at this value. |
| `step` | `number` | 1 | Increment applied by the plus and minus buttons. |
| `label` | `string` |  | Label text. |
| `description` | `string` |  | Hint shown below the field. |
| `error` | `string` |  | Error message. Puts the field in the error state. |
| `required` | `boolean` | false | Marks the field as required. |
| `disabled` | `boolean` | false | Disables the field and its buttons. |
| `name` | `string` |  | Native name, for form submission. |
| `size` | `'sm' \| 'md'` | 'md' | Field height. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: number) => void` |  | Called on every change, from the buttons or from typing a valid number. |

---

# PinInput

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/pin-input/

One-time code and PIN entry. Paste, backspace and arrow keys work across cells, and SMS codes autofill.

```svelte
<script>
  import { PinInput } from "@codeatlasdev/ui";
  let code = $state("");
</script>

<PinInput label="Verification code" bind:value={code} oncomplete={(v) => verify(v)} />
```

One hidden input backs all cells, with `autocomplete="one-time-code"`, so mobile keyboards offer the SMS code. In `numeric` mode the numeric keypad opens and non-digits are rejected. The `error` is announced with `role="alert"`.

### Default

Six digits by default. oncomplete fires once all cells are filled. A four-digit masked PIN is shown below it.

### States

Description, error, disabled and a free-text code.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `length` | `number` | 6 | Number of cells. |
| `value` | `string` | '' | Bindable value. |
| `type` | `'numeric' \| 'text'` | 'numeric' | Numeric restricts input to digits and opens the numeric keypad. |
| `label` | `string` |  | Visible label. |
| `description` | `string` |  | Hint below the cells. |
| `error` | `string` |  | Error message (role="alert"). Sets aria-invalid. |
| `mask` | `boolean` | false | Shows a bullet instead of each character. |
| `disabled` | `boolean` | false | Disables input. |
| `class` | `string` |  | Extra classes on the root. |
| `oncomplete` | `(value: string) => void` |  | Called once all cells are filled. |

---

# RadioGroup

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/radio/

Single-selection radio group as a list of rows or a grid of selectable cards.

```svelte
<script>
  import { RadioGroup } from "@codeatlasdev/ui";
  let plan = $state("pro");
</script>

<RadioGroup items={[{ value: "free", label: "Free" }, { value: "pro", label: "Pro" }]} bind:value={plan} />
```

The options are native radio inputs that share one `name`, so arrow keys move focus and selection inside the group and Tab leaves it. The group has no visible title of its own: pass `aria-label`, or wrap it in a `fieldset` with a `legend` when the choice needs a visible heading.

### Vertical

The default layout.

### Horizontal

orientation=&quot;horizontal&quot; lays the options out in a row.

### Cards

variant=&quot;cards&quot; renders each option as a selectable card with an optional description.

### Disabled

Disable a single item, or the whole group.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | '' | Bindable selected value. |
| `items` | `RadioItem[]` |  | Options: { value, label, description?, disabled? }. description is shown in the cards variant. |
| `variant` | `'list' \| 'cards'` | 'list' | list renders radio and label rows. cards renders each option as a card in a responsive grid, and the whole card is the hit area. |
| `name` | `string` |  | Native name of the radios, so the value is in FormData on a plain form submit (works without JS and with use:enhance). Unset: an internal id groups them and the value is not submitted by name. |
| `orientation` | `'vertical' \| 'horizontal'` | 'vertical' | Layout direction and arrow-key axis. |
| `disabled` | `boolean` | false | Disables the entire group. |
| `aria-label` | `string` |  | Accessible name of the group. |
| `class` | `string` |  | Extra classes on the group. |
| `onchange` | `(value: string) => void` |  | Called when the selection changes. |

---

# SegmentedControl

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/segmented-control/

Single-choice control with a sliding thumb. It always has a selection and honors prefers-reduced-motion.

```svelte
<script>
  import { SegmentedControl } from "@codeatlasdev/ui";
  let period = $state("month");
</script>

<SegmentedControl
  aria-label="Period"
  bind:value={period}
  items={[{ value: "week", label: "Week" }, { value: "month", label: "Month" }]}
/>
```

Unlike [ToggleGroup](/docs/inputs/toggle-group/), exactly one item is always selected: when `value` is unset it starts on the first enabled item. Give the control an `aria-label` since it has no visible heading, and an `aria-label` on every icon-only item. Arrow keys move between items.

### Default

Text items, and text items with icons.

### Small, full width, disabled item

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | first enabled item | Bindable selected value. |
| `items` | `ToggleGroupItem[]` |  | { value, label?, icon?, disabled?, 'aria-label'? }. |
| `size` | `'sm' \| 'md'` | 'md' | Item height. |
| `fullWidth` | `boolean` | false | Stretches the control to the container width. |
| `disabled` | `boolean` | false | Disables the whole control. |
| `aria-label` | `string` |  | Accessible name of the control. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: string) => void` |  | Called when the selection changes. |

---

# Select

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/select/

Dropdown selector with keyboard navigation, a label, hint and error state.

```svelte
<script>
  import { Select } from "@codeatlasdev/ui";
  let value = $state("br");
</script>

<Select label="Country" options={[{ value: "br", label: "Brazil" }]} bind:value />
```

For long lists that need filtering, use [Combobox](/docs/inputs/combobox/). Without a `label`, pass `aria-label` (or `aria-labelledby`) to name the trigger: the accessible name is that text followed by the current value, so it still contains the visible text. With neither, the `placeholder` names it. Arrow keys, Enter and Space open the list from the trigger, and Escape closes it. Pass `name` to submit the selected value with a native form (a hidden input; nothing is sent while no option is selected or the field is disabled). `required` blocks native form submission while nothing is selected. Text inside inputs stays at 16px or more on touch screens, so iOS Safari never zooms on focus.

### Basic

Controlled select with a pre-selected value.

### Placeholder

No initial value: the placeholder shows until the user picks an option.

### Empty-value option

An option with value '' (such as 'All projects') is a real selection: the trigger shows its label, not the placeholder. Use it for filters instead of a sentinel value.

### States

Disabled options, description, error and a disabled select.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Bindable selected value. `undefined` means no selection and shows the placeholder; `""` is a valid value when an option declares it. |
| `options` | `Array<{ value: string; label: string; disabled?: boolean }>` |  | Option items. |
| `placeholder` | `string` | 'Select…' (localized) | Text shown when `value` is `undefined` or matches no option. The default comes from the active i18n catalog. |
| `label` | `string` |  | Visible label above the trigger. |
| `description` | `string` |  | Hint shown below the trigger. |
| `aria-label` | `string` |  | Accessible name when there is no visible `label`. The trigger is named `aria-label` + current value; the list is named `aria-label`. |
| `aria-labelledby` | `string` |  | Id of an element that names the select when there is no visible `label` (followed by the current value). Ignored when `label` is set. |
| `error` | `string` |  | Error message. Puts the select in the error state. |
| `name` | `string` |  | Native name, so the selected value is in FormData on a plain form submit. |
| `required` | `boolean` | false | Marks the field as required. |
| `disabled` | `boolean` | false | Disables the entire select. |
| `size` | `'sm' \| 'md'` | 'md' | Trigger height. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: string) => void` |  | Called when the selection changes. |

---

# Slider

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/slider/

Range input with a single thumb or two thumbs, plus min, max and step.

```svelte
<script>
  import { Slider } from "@codeatlasdev/ui";
  let volume = $state(60);
  let range = $state([20, 75]);
</script>

<Slider bind:value={volume} />
<Slider bind:values={range} />
```

`value` and `values` are independent: bind one or the other. The slider has no built-in label or value readout, so render those next to it as the demos do. Arrow keys move by `step`, Home and End jump to the bounds.

### Single value

Binds a plain number. Default range is 0 to 100.

### Range

Bind a [min, max] tuple to values for two thumbs.

### Step and disabled

step={10} snaps to increments of 10.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` |  | Single-value mode: bind a plain number. Defaults to the midpoint when neither value nor values is set. |
| `values` | `[number, number]` |  | Range mode: bind a [min, max] tuple. |
| `min` | `number` | 0 | Minimum value. |
| `max` | `number` | 100 | Maximum value. |
| `step` | `number` | 1 | Step increment. |
| `disabled` | `boolean` | false | Disables the slider. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: number[]) => void` |  | Called on change. Always receives an array: one number in single mode, two in range mode. |

---

# SwatchGroup

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/swatch-group/

Single-choice color picker made of round swatches. Preset swatches follow the theme; custom ones take any CSS color.

```svelte
<script>
  import { SwatchGroup } from "@codeatlasdev/ui";
  let preset = $state("ocean");
</script>

<SwatchGroup
  aria-label="Accent"
  bind:value={preset}
  items={[{ value: "ocean" }, { value: "violet" }, { value: "emerald" }]}
/>
```

Each item paints from the theme preset named by its `value`, so the swatch always matches the palette. Give an item a `color` to paint it with any CSS color instead; its `value` is then free-form. Leave `value` empty for "none selected", for example while a custom color is active. The selected swatch shows a check mark.

On touch screens (`pointer: coarse`) each swatch grows to the 44px touch target, so neighbouring hit areas never overlap.

**Accessibility.** The group is a `radiogroup` and every swatch a `radio` with `aria-checked`. The group has no visible heading, so pass `aria-label`; each swatch is named by its `label`, falling back to `value`, so give custom colors a readable `label` ("Blue", not "#2563eb"). Arrow keys move focus between enabled swatches and Tab leaves the group. The selected state does not rely on color alone: it adds a check mark and a ring, and both survive forced-colors mode.

### Theme presets

Swatches without a color paint from the preset named by their value.

### Custom colors

Any CSS color, a small size and a disabled swatch.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | '' | Bindable selected item value. Empty means none selected. |
| `items` | `SwatchItem[]` |  | { value, label?, color?, disabled? }. Without `color` the swatch paints from the theme preset named by `value`; `label` is the accessible name and falls back to `value`. |
| `size` | `'sm' \| 'md'` | 'md' | Swatch diameter. |
| `disabled` | `boolean` | false | Disables every swatch. |
| `aria-label` | `string` |  | Accessible name of the group. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: string) => void` |  | Called when the user picks a different swatch. |

---

# Switch

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/switch/

Toggle control for binary on/off settings, with `role="switch"`.

```svelte
<script>
  import { Switch } from "@codeatlasdev/ui";
  let enabled = $state(false);
</script>

<Switch label="Notifications" bind:checked={enabled} />
```

Without a visible `label`, always pass `aria-label` (or `aria-labelledby`) so the switch has an accessible name. The track is 44px wide, so it is comfortable to hit on touch screens.

### Basic

Default off and on states.

### Disabled

### Without label

Provide aria-label when no visible label is rendered.

### Settings list

Common pattern: a row with title, helper text and a trailing switch.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `checked` | `boolean` | false | Bindable on/off state. |
| `disabled` | `boolean` | false | Disables interaction. |
| `name` | `string` |  | Native name, so the switch is in FormData on a plain form submit (value `on` when checked, absent when not). |
| `label` | `string` |  | Visible label rendered beside the switch. |
| `aria-label` | `string` |  | Accessible name used when no visible label is rendered. |
| `aria-labelledby` | `string` |  | Id of an element that names the switch. Ignored when label is set. |
| `class` | `string` |  | Extra classes on the wrapper. |
| `onchange` | `(checked: boolean) => void` |  | Called when the state changes. |

---

# TextArea

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/text-area/

Multi-line text input with label, helper text, error state and configurable resize behavior.

```svelte
<script>
  import { TextArea } from "@codeatlasdev/ui";
  let message = $state("");
</script>

<TextArea label="Message" bind:value={message} rows={4} />
```

The label sits above the field. `description` is hidden while an `error` is shown, and the error is announced with `role="alert"`. Text stays at 16px or more on touch devices so iOS Safari does not zoom on focus. Native textarea attributes (`maxlength`, `data-*`, `onkeydown`, `aria-label`...) are spread on the `<textarea>`, `bind:ref` gives you the element, and `hideLabel` keeps the label for screen readers only.

### Basic

Empty, with a placeholder, and pre-filled.

### States

Helper text, error, required, read-only, disabled and resize=&quot;none&quot;.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | '' | Bindable text value. |
| `label` | `string` |  | Label text. |
| `hideLabel` | `boolean` | false | Renders the label with `.ca-sr-only`: read by screen readers, not shown. |
| `placeholder` | `string` | '' | Native placeholder. |
| `rows` | `number` | 4 | Visible row count. |
| `minRows` | `number` |  | Row count used for the minimum height. Defaults to rows. |
| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | 'vertical' | CSS resize behavior. |
| `error` | `string` |  | Error message. Sets the error styling. |
| `description` | `string` |  | Helper text shown below. Hidden when error is set. |
| `helperText` | `string` |  | Deprecated alias of description. Use description. |
| `disabled` | `boolean` | false | Disables the textarea. |
| `required` | `boolean` | false | Marks the field as required, with a visual asterisk. |
| `readonly` | `boolean` | false | Makes the textarea read-only. |
| `name` | `string` |  | Native name, for form submission. |
| `class` | `string` |  | Extra classes on the root. |
| `ref` | `HTMLTextAreaElement \| null` |  | Bindable native textarea element. |
| `oninput` | `(value: string) => void` |  | Called on every keystroke with the new value. |
| `onchange` | `(value: string) => void` |  | Called when the value is committed (on blur, after an edit). |
| `onfocus` | `(e: FocusEvent) => void` |  | Called when the textarea gains focus. |
| `onblur` | `(e: FocusEvent) => void` |  | Called when the textarea loses focus. |

---

# TextField

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/text-field/

Styled text input with label, helper text, error state and leading and trailing slots.

```svelte
<script>
  import { TextField } from "@codeatlasdev/ui";
  let email = $state("");
</script>

<TextField label="Email" type="email" bind:value={email} />
```

An `error` replaces the `description` and is announced to assistive tech. On touch devices the input text stays at 16px or more so iOS Safari does not zoom on focus. Native input attributes (`maxlength`, `inputmode`, `data-*`, `onkeydown`, `onfocus`...) are spread on the `<input>`, and `bind:ref` gives you the element. For an inline field whose label is implied visually, set `hideLabel` (the label stays for screen readers) or pass `aria-label` without `label`. Wrapper components such as `MaskedField`, `MoneyInput` and `PhoneField` forward these props to TextField.

### Default

Basic text inputs with a label.

### With icons

leading and trailing snippets. Interactive trailing content, like a reveal button, must be a real button with its own label.

### States

Helper text, error, required, read-only, disabled and the small size.

### Hidden label

hideLabel keeps the label for assistive tech only; maxlength and ref reach the native input.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | Label text. |
| `hideLabel` | `boolean` | false | Renders the label with `.ca-sr-only`: read by screen readers, not shown. |
| `placeholder` | `string` | '' | Input placeholder. |
| `value` | `string` | '' | Bindable input value. |
| `type` | `string` | 'text' | HTML input type. |
| `error` | `string` |  | Validation error message. Puts the field in the error state. |
| `description` | `string` |  | Non-error hint shown below the field. |
| `helperText` | `string` |  | Deprecated alias of description. |
| `disabled` | `boolean` | false | Disables the input. |
| `required` | `boolean` | false | Marks the field as required. |
| `readonly` | `boolean` | false | Makes the input read-only. |
| `autocomplete` | `HTMLInputAttributes['autocomplete']` |  | Native autocomplete hint. |
| `name` | `string` |  | Native name, for form submission. |
| `size` | `'sm' \| 'md'` | 'md' | Field height. |
| `leading` | `Snippet` |  | Icon or element before the input. |
| `trailing` | `Snippet` |  | Icon or element after the input. |
| `skeleton` | `boolean` | false | Loading placeholder with the exact size of the loaded field (disabled, `aria-busy`). See Skeleton. |
| `class` | `string` |  | Extra classes on the root. |
| `ref` | `HTMLInputElement \| null` |  | Bindable native input element. |
| `oninput` | `(value: string) => void` |  | Called on every keystroke with the new value. |
| `onchange` | `(value: string) => void` |  | Called when the value is committed (blur or Enter). |
| `onfocus` | `(e: FocusEvent) => void` |  | Called when the input gains focus. |
| `onblur` | `(e: FocusEvent) => void` |  | Called when the input loses focus. |

---

# ThemeToggle

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/theme-toggle/

Switches between light and dark through the colorScheme store. Built for the AppShell railBottom slot.

```svelte
<script>
  import { ThemeToggle } from "@codeatlasdev/ui";
</script>

<ThemeToggle />
```

The toggle reads and writes the `colorScheme` store, so call `colorScheme.init()` once in your root layout. The choice is saved to localStorage and applied before first paint by the theme script. The default name is localized.

### Basic

Click it: the whole site flips between light and dark.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | 'Toggle color scheme' (localized) | Accessible name and tooltip. |
| `size` | `number` | 18 | Icon size in px. |
| `class` | `string` |  | Extra classes on the button. |

---

# ToggleGroup

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/toggle-group/

A set of toggle buttons with single or multiple selection. Single groups use arrow-key navigation.

```svelte
<script>
  import { ToggleGroup } from "@codeatlasdev/ui";
  let format = $state(["bold"]);
  const items = [
    { value: "bold", label: "Bold" },
    { value: "italic", label: "Italic" },
  ];
</script>

<ToggleGroup type="multiple" aria-label="Text formatting" bind:value={format} {items} />
```

In `single` mode the user can press the active item again to clear the selection, so `value` can be an empty string. Set `required` to keep a selection: pressing the active item does nothing and `onchange` stays silent, like a radio group (`multiple` keeps its last pressed item). Use [SegmentedControl](/docs/inputs/segmented-control/) when a required choice should look like a track with a sliding thumb. In `single` mode the group is one tab stop and arrow keys move focus (Home and End jump to the ends); in `multiple` mode each item stays in the tab order. Icon-only items need an `aria-label`.

### Single and multiple

type=&quot;single&quot; binds a string and can be cleared. type=&quot;multiple&quot; binds a string array. required keeps one item pressed.

### Variants and orientation

outlined and ghost variants, sizes, a disabled item and a vertical layout.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `type` | `'single' \| 'multiple'` | 'single' | Selection mode. |
| `value` | `string \| string[]` |  | Bindable. A string for single, an array for multiple. |
| `items` | `ToggleGroupItem[]` |  | { value, label?, icon?, disabled?, 'aria-label'? }. Icon-only items need aria-label. |
| `size` | `'sm' \| 'md'` | 'md' | Item height. |
| `variant` | `'outlined' \| 'ghost'` | 'outlined' | Container style. |
| `disabled` | `boolean` | false | Disables the whole group. |
| `orientation` | `'horizontal' \| 'vertical'` | 'horizontal' | Layout and arrow-key axis. |
| `required` | `boolean` | false | Keep a selection. Pressing the active item (the last pressed one for multiple) does not clear it. |
| `aria-label` | `string` |  | Accessible name of the group. |
| `class` | `string` |  | Extra classes on the root. |
| `onchange` | `(value: string \| string[]) => void` |  | Called on every change. |

---

# useForm

Group: Inputs. URL: https://ui.codeatlas.com.br/docs/inputs/use-form/

Reactive form state with optional schema validation. Works with Zod, Valibot or a plain validator function.

```svelte
<script>
  import { TextField, useForm } from "@codeatlasdev/ui";

  const form = useForm(
    { email: "" },
    { schema: (data) => (data.email.includes("@") ? {} : { email: "Enter a valid email." }) },
  );
</script>

<TextField
  label="Email"
  value={form.fields.email.value}
  error={form.fields.email.error}
  oninput={(v) => form.set("email", v)}
  onblur={() => form.touch("email")}
/>
```

`useForm` has no dependencies. The `schema` option accepts a plain function that returns an object of field errors, a Zod schema (`safeParse`) or a Valibot schema. Every field value is a string. Errors only appear after a field is touched (on blur) or after `validate()`, and then update on each keystroke.

Pass `arrays` for repeatable row groups, for example `useForm({ name: "" }, { arrays: { phones: [{ number: "" }] } })`, and use `form.arrays.phones.add`, `remove` and `move`.

### No schema

Manual validation on submit. touch() and set() drive the per-field state.

### With schema

A plain-function schema runs on every keystroke once a field is touched.

### Submit state

validate() gates submission, submitting drives the button loading state, and reset() clears everything after success.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `initialValues` | `Record<K, string>` |  | Field names and their initial string values. |
| `options.schema` | `ValidationSchema<K>` |  | A function (data) => Partial<Record<K, string>>, or a Zod or Valibot schema. |
| `options.arrays` | `{ [name]: Item[] }` |  | Initial rows for repeatable field groups, exposed as form.arrays. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `fields` | `Record<K, { value: string; error: string \| undefined; touched: boolean }>` |  | Reactive state of every field. |
| `arrays` | `{ [name]: { items; add(item); remove(index); move(from, to) } }` |  | Repeatable row groups declared with options.arrays. |
| `dirty` | `boolean` |  | True when any value differs from its initial value. |
| `valid` | `boolean` |  | True when the schema reports no errors, regardless of touched state. |
| `submitting` | `boolean` |  | Writable flag for in-flight submits. |
| `touch` | `(field: K) => void` |  | Marks a field as touched and validates it. |
| `set` | `(field: K, value: string) => void` |  | Sets a value, and re-validates the field if it was touched. |
| `validate` | `() => boolean` |  | Validates all fields, marks them touched and returns true when all pass. |
| `reset` | `() => void` |  | Restores initial values and clears errors, touched state and submitting. |

---

# Alert

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/alert/

Inline status messages for success, warning, error and info states, with an optional title and close action.

```svelte
<script>
  import { Alert } from "@codeatlasdev/ui";
</script>

<Alert severity="success" title="Saved">Your changes were saved.</Alert>
```

The parent owns visibility: render the alert conditionally and hide it from `onclose`. The root has `role="alert"` with `aria-live="polite"`, so assistive technology announces it.

### Severities

### With title

### Closable

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `severity` | `'success' \| 'warning' \| 'error' \| 'info'` |  | Semantic color and icon. Required. |
| `title` | `string` | undefined | Bold heading above the message. |
| `closable` | `boolean` | false | Shows a dismiss button. |
| `onclose` | `() => void` | undefined | Called when the close button is clicked. |
| `class` | `string` | '' | Extra class names on the root element. |
| `children` | `Snippet` | undefined | Alert body content. |

---

# Avatar

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/avatar/

User avatar that shows an image and falls back to colored initials, with size, shape and presence status.

```svelte
<script>
  import { Avatar } from "@codeatlasdev/ui";
</script>

<Avatar src="/ana.jpg" alt="Ana Lima" size="lg" status="online" />
```

Without `src`, or when the image fails to load, the avatar shows initials derived from `alt` (or `fallback`). `fallback` also takes a snippet, for an icon on groups, channels and bots that have no meaningful initials. The photo is a real `<img>`: pass `loading="lazy"` in long lists and `referrerpolicy="no-referrer"` for CDNs that reject a cross-origin `Referer`; `onerror` fires when it fails so you can refetch a signed URL. The background color is generated from the name, so the same person always gets the same color.

### With image

### Initials fallback

### Icon fallback

### Sizes

### Shape and status

### Avatar stack

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | undefined | Image URL, rendered as a real `<img>`. The fallback shows beneath it while it loads and when it fails. |
| `alt` | `string` | '' | Alt text. Initials are derived from it when no `fallback` is set. |
| `fallback` | `string \| Snippet` | undefined | Explicit initials (string) or an icon/any content (snippet). Overrides the initials derived from `alt`. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | 'md' | Named size (20, 28, 36, 48, 64px) or a diameter in pixels. |
| `shape` | `'circle' \| 'rounded'` | 'circle' | Avatar outline. |
| `status` | `'online' \| 'offline' \| 'busy' \| 'away'` | undefined | Shows a presence dot in the bottom-right corner. |
| `loading` | `'lazy' \| 'eager'` | undefined | Passed to the `<img>`. Use `lazy` in long lists so off-screen photos are not fetched. |
| `referrerpolicy` | `ReferrerPolicy` | undefined | Passed to the `<img>`, e.g. `no-referrer` for CDNs that reject a cross-origin `Referer`. |
| `crossorigin` | `'anonymous' \| 'use-credentials'` | undefined | Passed to the `<img>`. |
| `onerror` | `(event: Event) => void` | undefined | Called when the image fails to load; the fallback shows. Refetch a signed URL here. |
| `skeleton` | `boolean` | false | Loading placeholder with the exact avatar size; no image request is made. See Skeleton. |
| `class` | `string` | '' | Extra class names. |

---

# Badge

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/badge/

Small count and status indicators anchored to icons, avatars and buttons.

```svelte
<script>
  import { Badge, IconButton } from "@codeatlasdev/ui";
</script>

<Badge count={3}><IconButton aria-label="Messages">…</IconButton></Badge>
```

Badge wraps its child and positions the indicator on the corner. Pass `count` for a number (hidden at 0, capped at `99+`) or `dot` for a plain status dot. The indicator is a `role="status"` element labelled "New" (dot) or "N notifications" (count) from the i18n catalog; still give the wrapped control its own accessible name.

### Dot and counts

### On avatars

### Colors

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `count` | `number` | undefined | Number to display. Hidden when 0 or undefined unless `dot` is set. Values above 99 render as `99+`. |
| `dot` | `boolean` | false | Shows a dot instead of a number. |
| `color` | `'brand' \| 'success' \| 'error' \| 'warning'` | 'brand' | Indicator color. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | The element the badge is anchored to. |

---

# Chip

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/chip/

Compact element for tags, filters and status labels, with icons, color variants, selection and deletion.

```svelte
<script>
  import { Chip, StatusChip } from "@codeatlasdev/ui";
</script>

<Chip label="Design" variant="brand" deletable ondelete={remove} />
<StatusChip status="success" label="Active" />
```

A chip becomes a keyboard-focusable toggle button when `onclick` is set: Enter and Space activate it and `aria-pressed` follows `selected`. `StatusChip` is a separate, non-interactive component for dot + label statuses.

### Basic

### Variants and size

### With icons

### Selectable

### Deletable

### StatusChip

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | Text content of the chip. Required. |
| `icon` | `Component` | undefined | Icon component rendered before the label. |
| `variant` | `'default' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'brand'` | 'default' | Color variant. |
| `size` | `'sm' \| 'md'` | 'md' | Chip size. |
| `selected` | `boolean` | false | Selected visual state, exposed as `aria-pressed` on interactive chips. |
| `deletable` | `boolean` | false | Shows a × remove button. |
| `onclick` | `() => void` | undefined | Makes the chip interactive (button role, focusable). |
| `ondelete` | `() => void` | undefined | Called when the × button is clicked. |
| `class` | `string` | '' | Extra class names. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `status` | `'success' \| 'warning' \| 'error' \| 'info' \| 'neutral'` |  | Semantic status. Required. |
| `label` | `string` |  | Text shown next to the dot. Required. |
| `class` | `string` | '' | Extra class names. |

---

# CodeSnippet

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/code-snippet/

Syntax-highlighted code block with a copy button, highlighted by Shiki and following the current color scheme.

CodeSnippet lives in its own entry point so that Shiki stays out of bundles that do not need it. Install the optional peer first.

```svelte
<script>
  import { CodeSnippet } from "@codeatlasdev/ui/code";
</script>

<CodeSnippet code={source} language="typescript" />
```

The theme switches between a light and a dark high-contrast Shiki theme when the color scheme changes.

### Languages

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `code` | `string` |  | Source code to display. Required. |
| `language` | `string` | 'svelte' | Shiki language identifier. |
| `class` | `string` | '' | Extra class names. |

---

# Image

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/image/

A responsive image that reserves its space (no layout shift), loads lazily, and preloads the one above-the-fold image.

```svelte
<script>
  import { Image } from "@codeatlasdev/ui";
</script>

<Image src="/hero.avif" alt="Dashboard overview" width={1200} height={630} priority />
```

`width` and `height` are the intrinsic pixel size of the file. The browser derives the aspect ratio from them before the image arrives, so nothing jumps when it loads, and `max-width: 100%` with `height: auto` keeps that ratio on small screens. Images are `loading="lazy"` and `decoding="async"` by default.

Use `priority` on the one image that is the largest thing visible on first paint (the LCP element). It loads eagerly, sets `fetchpriority="high"` and adds a `<link rel="preload" as="image">` to `<head>`. Never put it on more than one image per page.

### Fixed ratio

### srcset and sizes

For AVIF and WebP generation at build time see [Performance](/docs/getting-started/performance/#images).

## Alt text

`alt` is required. An image that carries no meaning passes `decorative` instead of `alt=""`; it renders `alt=""` with `aria-hidden="true"`. In development the component warns when `alt=""` is passed without `decorative`, when `width` or `height` is missing, and when `decorative` is combined with a non-empty `alt`.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` |  | Image URL. |
| `alt` | `string` |  | Text alternative. Required; use `decorative` for decoration. |
| `width` | `number` |  | Intrinsic width in pixels. Required, with `height` it reserves the space. |
| `height` | `number` |  | Intrinsic height in pixels. Required. |
| `decorative` | `boolean` | false | Renders `alt=""` and `aria-hidden="true"`. |
| `priority` | `boolean` | false | Eager load, `fetchpriority="high"` and a preload link in `<head>`. One per page, for the LCP image. |
| `loading` | `'lazy' \| 'eager'` | 'lazy' ('eager' with priority) | Overrides the default. |
| `decoding` | `'async' \| 'sync' \| 'auto'` | 'async' | Decode hint. |
| `class` | `string` | '' | Extra class names. |

Other `<img>` attributes are forwarded as they are. `srcset` and `sizes` are the ones you will use most: `srcset` lists the candidate renditions and `sizes` tells the browser the rendered width. With `priority`, both are copied onto the preload link in `<head>`. `fetchpriority` is controlled by `priority`.

---

# DataTable

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/data-table/

Table with search, sorting, pagination, column visibility, row groups, resizable columns, drag-to-reorder rows and interactive cells, built on TanStack Table.

DataTable lives in its own entry point so that TanStack Table stays out of bundles that do not need it. Install the optional peer first.

```svelte
<script lang="ts">
  import { DataTable, createCaColumnHelper } from "@codeatlasdev/ui/table";
  type User = { name: string };
  const users: User[] = [{ name: "Ana Souza" }, { name: "Bruno Lima" }];

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor("name", { header: "Name", meta: { label: "Name" } }),
  ]);
</script>

<DataTable {columns} data={users} />
```

There are two modes. In simple mode you pass `columns` and `data` and the table searches, sorts and paginates locally. In controlled mode you pass `globalFilter`, `pagination` and `sorting` together with their change handlers, and feed it one page of data plus `total`, which is what you want for server-side data.

### Simple mode

### Controlled mode

## Groups, resize, reorder and interactive cells

Four options turn the table into a backlog or board in table form. They are independent: use any of them alone.

- **Row groups.** `groupBy={(row) => row.sprint}` renders one `<tbody>` per key, in first-appearance order, each with a header row. The header is a button with `aria-expanded` that collapses its rows; `groupLabel` replaces its content.
- **Column resize.** Set `meta: { resizable: true }` on a column, with `size`, `minSize` and `maxSize` on the definition. The header gets a handle that follows the window splitter pattern: drag it with a mouse, pen or finger, or focus it and press the arrow keys (10px, 40px with Shift), Home (minimum), End (maximum) and Enter (reset). Double click resets too. Once a column is resizable the table uses a fixed layout and scrolls sideways when its columns are wider than the container.
- **Row reorder.** `onReorder` adds a drag grip to every row, built on the [drag and drop primitive](/docs/foundation/drag-and-drop/): mouse, touch (press and hold) and keyboard (Space lifts, arrows move, Enter drops, Escape cancels), announced to screen readers. Groups exchange rows. `DataTable` never changes `data`: the handler gets `{ id, from, to }` with `{ group, index }` positions inside a group and you apply them. Give rows stable ids with `rowId`.
- **Interactive cells.** A cell can render any component (`renderComponent(Button, …)`, menus, inline editors). A click on a link, button, input or other control inside a cell does not reach `onRowClick`; mark any other element with `data-no-row-click` to opt it out too.

Only the current page is in the DOM, so a table of thousands of rows stays fast: raise `pageSize` (simple mode) or page on the server (controlled mode).

### Groups

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `columns` | `ColumnDef[]` |  | Column definitions created with `createCaColumnHelper`. Required. |
| `data` | `TData[]` |  | Row data. In simple mode pass all rows; in controlled mode pass the current page. Required. |
| `total` | `number` | data.length | Total row count after filtering, used to compute the page count. Ignored in simple mode. |
| `globalFilter` | `string` | undefined | Search value. Passing it switches the table to controlled mode. |
| `onGlobalFilterChange` | `(v: string) => void` | undefined | Called when the user types in the search box. |
| `pagination` | `PaginationState` | undefined | Controlled `{ pageIndex, pageSize }`. |
| `onPaginationChange` | `(v: Updater<PaginationState>) => void` | undefined | Called when the page or page size changes. |
| `sorting` | `SortingState` | undefined | Controlled sorting, `[{ id, desc }]`. |
| `onSortingChange` | `(v: Updater<SortingState>) => void` | undefined | Called when the user clicks a column header. |
| `labels` | `{ noResults?, noResultsSub?, clearSearch? }` | undefined | Overrides the strings of the no-results state. |
| `searchPlaceholder` | `string` | undefined | Placeholder of the search input. |
| `isLoading` | `boolean` | undefined | Shows a loading indicator in the toolbar. |
| `isExporting` | `boolean` | undefined | Shows the export button as busy. |
| `onExport` | `() => void` | undefined | Enables the export button in the toolbar. |
| `onRowClick` | `(row: TData) => void` | undefined | Called when a row is clicked. Clicks on a control inside a cell (link, button, input, `data-no-row-click`) are ignored. |
| `rowId` | `(row: TData) => string` | undefined | Stable id of a row. Defaults to its index; set it when you use `onReorder`. |
| `groupBy` | `(row: TData) => string` | undefined | Rows with the same key share a collapsible `<tbody>`, in first-appearance order. |
| `groupLabel` | `Snippet<[{ group: string; count: number }]>` | undefined | Custom content of a group header button. |
| `onReorder` | `(e: DataTableReorderEvent) => void` | undefined | Shows a drag grip on every row and reports `{ id, from, to }` with `{ group, index }` positions. You apply the move to `data`. |
| `pageSize` | `number` | 10 | Rows per page in simple mode. |
| `hasActiveFilters` | `boolean` | undefined | Treats the table as filtered, which suppresses the empty state. |
| `emptyState` | `Snippet` | undefined | Custom content shown when there is no data and no active filter. |
| `children` | `Snippet` | undefined | Filter chips such as `DataTableFacetedFilter`, rendered in the toolbar. |
| `class` | `string` | '' | Extra class names on the wrapper. |

## Building blocks

`DataTable` is assembled from the parts below, all exported from `@codeatlasdev/ui/table`. You rarely need them: use them standalone when you render your own `<table>` markup around a table instance made with `createCaTable`, for example a layout `DataTable` does not offer. Inside `DataTable` the toolbar, pagination and column toggle are already wired. Use `DataTableColumnHeader` as a column `header` to get a sortable header, and pass `DataTableFacetedFilter` as `children` of `DataTable`.

```svelte
<script lang="ts">
  import { renderComponent } from "@tanstack/svelte-table";
  import { createCaColumnHelper, DataTableColumnHeader } from "@codeatlasdev/ui/table";
  type User = { name: string };

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor("name", {
      header: ({ column }) =>
        renderComponent(DataTableColumnHeader<User, string>, { column, title: "Name" }),
      meta: { label: "Name" },
    }),
  ]);
</script>
```

`createCaColumnHelper`, `createCaTable`, `caTableFeatures` and the `CaColumn`, `CaColumnDef`, `CaColumnMeta`, `CaTable` and `CaTableFeatures` types are exported from the same entry point. `meta.label` is the name shown in the column visibility menu.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `table` | `CaTable<TData>` |  | Table instance from `createCaTable`. Required. |
| `total` | `number` |  | Result count shown in the toolbar. Required. |
| `globalFilter` | `string` |  | Current search value. Required. |
| `onGlobalFilterChange` | `(v: string) => void` |  | Called when the user types in the search box. Required. |
| `searchPlaceholder` | `string` | undefined | Placeholder and accessible name of the search input. |
| `isLoading` | `boolean` | undefined | Shows a spinner. |
| `isExporting` | `boolean` | undefined | Disables the export button and shows a spinner in it. |
| `onExport` | `() => void` | undefined | Renders the export button. It is disabled while `total` is 0. |
| `children` | `Snippet` | undefined | Filter controls rendered next to the search box. |

The toolbar always includes `DataTableColumnToggle` on its right side.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `table` | `CaTable<TData>` |  | Table instance from `createCaTable`. Required. |
| `total` | `number` |  | Total row count shown next to the page indicator. Required. |

It renders a page size select (10, 20, 50 or 100 rows), a `page / pages` indicator and previous and next buttons.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `column` | `CaColumn<TData, TValue>` |  | Column the header belongs to. Required. |
| `title` | `string` |  | Header text. Required. |
| `class` | `string` | '' | Extra class names. |

A sortable column renders a button that toggles sorting and shows the direction icon, and its `<th>` carries `aria-sort`. A column that cannot sort renders the plain title.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `column` | `CaColumn<TData, TValue>` |  | Column to resize. Required. |
| `label` | `string` |  | Accessible name of the handle, such as `Resize Task`. Required. |
| `step` | `number` | 10 | Keyboard step in px; Shift uses four times as much. |

`DataTable` renders it for every column with `meta.resizable`. Use it in your own header markup when you build the table yourself.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `table` | `CaTable<TData>` |  | Table instance from `createCaTable`. Required. |

A menu of checkboxes, one per column that can be hidden. It follows the menu keyboard pattern: arrow keys move, Space and Enter toggle, Escape closes.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Label of the filter button. Required. |
| `facets` | `Record<string, number>` | {} | Option key to result count. Options are sorted by count, highest first. |
| `labelMap` | `Record<string, string>` | {} | Maps option keys to display labels. |
| `selected` | `string[]` | [] | Selected option keys. |
| `onSelectionChange` | `(values: string[]) => void` |  | Called with the new selection. Required. |

---

# Divider

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/divider/

Horizontal and vertical separators drawn with outline tokens.

```svelte
<script>
  import { Divider } from "@codeatlasdev/ui";
</script>

<Divider />
<Divider orientation="vertical" />
```

A vertical divider stretches to the height of its flex container, so place it inside a `Flex` with `align="center"` or give it a fixed height.

### Horizontal

### Vertical

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `orientation` | `'horizontal' \| 'vertical'` | 'horizontal' | Direction of the separator. |
| `class` | `string` | '' | Extra class names. |

---

# NotificationBell

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/notification-bell/

Bell button with an unread badge that opens a notification center, designed for app shell headers.

```svelte
<script>
  import { NotificationBell } from "@codeatlasdev/ui";
</script>

<NotificationBell notifications={items} onRead={markRead} onReadAll={markAll} onClear={clear} />
```

The unread count is derived from `notifications` where `read` is falsy. The component is controlled: update your list in `onRead`, `onReadAll` and `onClear`. Every visible string can be replaced through `labels`. The panel is a popover layer anchored below the bell, aligned to its end edge, and closes on Escape or an outside press.

### Default

### Controlled

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `notifications` | `NotificationItem[]` | [] | Items shown in the panel: `{ id, title, body?, time?, read?, variant? }`. `variant` is `'default' \| 'info' \| 'success' \| 'warning' \| 'error'`. |
| `onRead` | `(id: string) => void` | undefined | Called when an unread item is clicked. Items already read do not call it. |
| `onReadAll` | `() => void` | undefined | Called by the mark all as read action. |
| `onClear` | `() => void` | undefined | Called by the clear action. |
| `labels` | `{ title?, markAll?, clear?, empty? }` | {} | String overrides for i18n. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Custom trigger content. |

---

# Kbd

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/kbd/

A keycap for keyboard shortcuts in prose, menus and tooltips.

```svelte
<script>
  import { Kbd } from "@codeatlasdev/ui";
</script>

<Kbd>Esc</Kbd>
```

`Kbd` renders a native `<kbd>` element. Use one per key and join combinations with a plain `+`. The keycap is not selectable, so double clicks on a shortcut do not select it.

### Shortcuts in text

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` |  | The key label, for example Ctrl or K. |
| `class` | `string` | '' | Extra classes on the `<kbd>` element. |

---

# Pagination

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/pagination/

Navigation between pages of a data set, with a bindable current page.

```svelte
<script>
  import { Pagination } from "@codeatlasdev/ui";
</script>

<Pagination count={100} perPage={10} bind:page />
```

`count` is the total number of items, not the number of pages. Pages are numbered from 1, and the first and last page always show. The nav buttons and page buttons form one keyboard group: arrow keys move between them (wrapping at the ends, mirrored in right-to-left layouts), Home and End jump to the first and last enabled control. The current page has `aria-current="page"`.

### Basic

### More siblings

### Few items

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `count` | `number` |  | Total number of items to paginate. Required. |
| `perPage` | `number` | 10 | Items per page. |
| `page` | `number` | 1 | Current page, 1-based. Bindable. |
| `siblingCount` | `number` | 1 | Pages shown on each side of the current page. |
| `onPageChange` | `(page: number) => void` | undefined | Called with the new page when the user changes it. It does not fire when you set `page` yourself. |
| `class` | `string` | '' | Extra class names. |

---

# ScrollArea

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/scroll-area/

Scrollable container with overlay scrollbars styled by the theme.

```svelte
<script>
  import { ScrollArea } from "@codeatlasdev/ui";
</script>

<ScrollArea maxHeight="240px">…</ScrollArea>
```

The area scrolls once its content exceeds `maxHeight` or `maxWidth`, so set one of them (or a height through `class`). Native scrolling and touch momentum are preserved. The viewport is focusable (`tabindex="0"`), so keyboard users can scroll it with the arrow keys.

### Vertical scroll

### Horizontal scroll

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `type` | `'hover' \| 'scroll' \| 'auto' \| 'always'` | 'hover' | When the scrollbar is visible. |
| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | 'vertical' | Which scrollbars to render. |
| `maxHeight` | `string` | undefined | CSS max-height of the area, for example `'240px'`. |
| `maxWidth` | `string` | undefined | CSS max-width of the area. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Scrollable content. |

---

# Table

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/table/

SimpleTable styles plain table markup with a sticky header, hover rows and an optional card layout in narrow containers.

```svelte
<script>
  import { SimpleTable } from "@codeatlasdev/ui";
</script>

<SimpleTable responsive="cards">
  <thead>…</thead>
  <tbody>…</tbody>
</SimpleTable>
```

SimpleTable styles plain `thead` and `tbody` markup inside a focusable, horizontally scrolling region. For search, sorting and pagination use [DataTable](/docs/display/data-table/). It is exported from `@codeatlasdev/ui`. `@codeatlasdev/ui/table` also exports a `Table`, a bordered wrapper around a plain `<table>` that forwards native table attributes.

### Default (scroll)

### Cards on narrow containers

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `responsive` | `'scroll' \| 'cards'` | 'scroll' | `scroll` keeps a regular table. `cards` turns each row into a card when the table's own width is below the `sm` breakpoint (600px). Cell captions come from the `thead` headers automatically. |
| `skeleton` | `boolean` | false | Loading placeholder: rows keep their layout but are hidden, so the table has the exact loaded size. Render placeholder rows so the height matches. See Skeleton. |
| `class` | `string` | '' | Extra class on the wrapper. |
| `children` | `Snippet` | undefined | `thead` and `tbody` markup. |

---

# Timeline

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/timeline/

Chronological list of events with colored markers.

```svelte
<script>
  import { Timeline } from "@codeatlasdev/ui";
</script>

<Timeline items={[{ label: "Order created", date: "Today", variant: "success" }]} />
```

### With variants

### Simple

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `TimelineItem[]` |  | Events: `{ label, description?, date?, variant? }`. `variant` is `'default' \| 'success' \| 'error' \| 'warning' \| 'info'`. Required. |
| `class` | `string` | '' | Extra class names. |

---

# Live List

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/live-list/

A list that fills while rows stream in over SSE, WebSocket or a bulk job, with progress, batched screen reader announcements and auto-scroll that never steals focus.

```svelte
<script>
  import { LiveList } from "@codeatlasdev/ui";

  let items = $state([]);
  let status = $state("running");

  const source = new EventSource("/api/check");
  source.onmessage = (e) => items.push(JSON.parse(e.data));
  source.addEventListener("done", () => { status = "done"; source.close(); });
</script>

<LiveList {items} total={domains.length} {status} label="Domain checks">
  {#snippet item(row)}
    <span>{row.domain}</span>
    <span>{row.available ? "Available" : "Taken"}</span>
  {/snippet}
</LiveList>
```

`AppList` and `DataTable` assume data that is already there. `LiveList` is for rows that arrive over time: a bulk checker, an import, a log viewer. Append to `items` as messages arrive; the component does the rest.

## What it handles for you

|Concern|Behaviour|
|---|---|
|Screen readers|The list is a named `role="log"` with `aria-live="off"`, so a screen reader is **not** flooded with one announcement per row. New rows are summarised as a single polite message per batch ("12 new items"), and completion is announced once. Errors are announced assertively.|
|Auto-scroll|Follows the newest row only while the user is at the bottom. Scrolling up pauses it and shows a "N new" button; pressing it jumps to the latest row and resumes. Turn it off with `follow={false}`.|
|Focus|Nothing in `LiveList` calls `focus()`. A row action or a field outside the list keeps focus while rows stream in.|
|Progress|Determinate ("3 of 12" and a bar) when you pass `total`; a plain count and an indeterminate bar while `status="running"` otherwise.|
|Keyboard|The scrolling area becomes focusable only while it overflows, so it can be scrolled with the arrow keys.|

### Streaming rows

Start the check, then scroll up while it runs: following pauses and a New button appears.

## Rules for the row snippet

- Do not put `role="status"` or `aria-live` inside a row. `StatusChip` has `role="status"` on purpose (it is a live region), so inside a `LiveList` use `Chip` or plain text, or every row would announce itself.
- Rows are append-only. Keep a stable `getKey` if you ever replace the array with a reordered copy.
- A row can hold interactive content (buttons, links). Focus is never moved, so those controls stay usable while the list grows.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `readonly T[]` |  | Rows received so far, oldest first. Append to it as messages arrive. |
| `item` | `Snippet<[T, number]>` |  | Renders one row (inside an `li`). Receives the row and its index. |
| `label` | `string` |  | Accessible name of the log region and of the progress bar. |
| `total` | `number` |  | Expected number of rows. Enables determinate progress. |
| `status` | `'idle' \| 'running' \| 'done' \| 'error'` | 'idle' | `running` shows progress; `done` and `error` are announced once. |
| `follow` | `boolean` | true | Follow the newest row while the user is at the bottom. |
| `height` | `string` | '24rem' | Height of the scrolling area (any CSS length). |
| `getKey` | `(item: T, index: number) => string \| number` | index | Stable key per row. |
| `announceDelay` | `number` | 600 | Quiet period in ms before a batch of new rows is announced. |
| `empty` | `Snippet` |  | Content shown while there are no rows. |
| `class` | `string` | '' | Extra class names. |

---

# Tooltip

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/tooltip/

Floating label shown on hover and focus, with four placements and a configurable delay.

```svelte
<script>
  import { Tooltip, Button } from "@codeatlasdev/ui";
</script>

<Tooltip content="Save changes">
  {#snippet triggerChild(props)}
    <Button {...props}>Save</Button>
  {/snippet}
</Tooltip>
```

When the trigger is an interactive control, use `triggerChild` and spread the received `props` onto it so no extra wrapper button is created. `children` is for non-interactive content such as text, which the tooltip wraps in its own button. Tooltips open on keyboard focus without the delay and close on Escape. Pointer hover waits for `delay`, touch never opens them, and moving between tooltips within 300ms skips the delay. Never put essential information only in a tooltip.

The blur behind the tooltip is `--ca-tooltip-blur` (default `var(--ca-blur-ultra-thin)`). Set `--ca-tooltip-blur: none` to get an opaque tooltip without touching the shared ultra-thin tier that `.glass-ultra-thin` and `.glass-btn-clear` also use.

### All sides

### On icon buttons

### Custom delay

### Text trigger

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `content` | `string` |  | Text shown in the tooltip. Required. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | 'top' | Preferred placement side. |
| `delay` | `number` | 500 | Open delay in milliseconds. |
| `class` | `string` | '' | Extra classes on the tooltip content. |
| `children` | `Snippet` | undefined | Non-interactive trigger content, wrapped in the tooltip's own button. |
| `triggerChild` | `Snippet<[props]>` | undefined | Interactive trigger. Receives the trigger `props` to spread onto a Button or IconButton. |

---

# External Link

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/external-link/

A link that opens in a new tab with the right rel, an icon and a screen reader hint, ready for table cells.

```svelte
<script>
  import { ExternalLink } from "@codeatlasdev/ui";
</script>

<ExternalLink href="https://registrar.example/buy?d=atlas.dev">Buy at registrar</ExternalLink>
```

`ExternalLink` always sets `target="_blank"` with `rel="noopener noreferrer"`, draws a trailing arrow icon (hidden from assistive technology) and appends a visually hidden "(opens in a new tab)" to the accessible name. The hint comes from the i18n catalog (`externalLink.newTab`), so it follows `setLocale`. Without it a screen reader user gets no warning that the link leaves the page.

A results table with a per-row external link needs nothing more than putting it in a cell. For links that look like buttons, use `Button` with `href` and `target="_blank"`; it already sets `rel`.

### In a results table

One link per row. The accessible name of each link is for example “Buy at registrar (opens in a new tab)”.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `href` | `string` |  | Destination URL. |
| `children` | `Snippet` |  | Link text. |
| `showIcon` | `boolean` | true | Trailing arrow icon. The screen reader hint stays either way. |
| `class` | `string` | '' | Extra class names. |

Other anchor attributes (`aria-label`, `data-*`, `onclick`) are passed through. `target` and `rel` are fixed on purpose.

---

# Message Bubble

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/message-bubble/

A chat bubble with direction, grouping tails, sender and avatar, reply quote, reactions and delivery ticks.

```svelte
<script>
  import { MessageBubble } from "@codeatlasdev/ui";
</script>

<MessageBubble direction="out" time="14:32" status="delivered">Sent it by email.</MessageBubble>
```

`direction` picks the side and colors (`out` uses the brand fill). Consecutive messages from one person use `grouped`: `first`, `middle` and `last` flatten the joined corners, and only `single` and `last` keep the tail and show the `avatar` slot (the other positions reserve its width so the column stays aligned). The delivery ticks are decorative; the state is also written as visually hidden text after the time, so a screen reader hears "14:32, Delivered" once. The bubble has no live region: the list that appends messages decides what is announced.

### A grouped conversation

The first bubble shows the sender, the last one the avatar and the tail.

### Delivery status

pending, sent, delivered and read; read ticks use the info color.

### Quote and reactions

The quote slot renders a reply preview; reactions overlap the bottom edge.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `direction` | `'in' \| 'out'` | 'in' | Side and color. |
| `grouped` | `'single' \| 'first' \| 'middle' \| 'last'` | 'single' | Position in a run of bubbles from one sender; controls the tail and spacing. |
| `sender` | `string` |  | Name above the text, for incoming single or first bubbles. |
| `avatar` | `Snippet` |  | Avatar slot beside incoming bubbles (single and last). |
| `quote` | `Snippet` |  | Reply preview shown at the top of the bubble. |
| `reactions` | `{ emoji: string; count?: number; mine?: boolean }[]` |  | Reaction chips under the bubble. |
| `time` | `string` |  | Footer time text. |
| `status` | `'pending' \| 'sent' \| 'delivered' \| 'read'` |  | Delivery ticks for outgoing bubbles. |
| `footer` | `Snippet` |  | Extra footer content before the time. |
| `children` | `Snippet` |  | Message body. |

---

# Conversation Item

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/conversation-item/

An inbox row with avatar, title, time, preview, unread badge, pinned and muted flags and an active state.

```svelte
<script>
  import { Avatar, ConversationItem } from "@codeatlasdev/ui";
</script>

<ConversationItem title="Maria Souza" time="14:32" preview="Sent it by email." unread={3} active>
  {#snippet avatar()}<Avatar alt="Maria Souza" size="lg" />{/snippet}
</ConversationItem>
```

The whole row is the hit area (at least 44px tall). With `href` it renders a link, otherwise a button. `active` sets `aria-current`; unread rows make the title and time bold; the count is capped at 99+ and announced as "3 unread messages". `typing` replaces the preview.

### Inbox

Pinned, muted, unread, typing and the active row.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Contact or group name. |
| `time` | `string` |  | Last activity time. |
| `preview` | `string` |  | One-line preview. |
| `previewIcon` | `Snippet` |  | Leading icon or ticks before the preview. |
| `avatar` | `Snippet` |  | Avatar slot. |
| `unread` | `number` |  | Unread count badge (99+ cap). |
| `pinned` | `boolean` | false | Shows the pin indicator. |
| `muted` | `boolean` | false | Shows the muted indicator and a quiet badge. |
| `active` | `boolean` | false | Selected row (aria-current). |
| `typing` | `boolean` | false | Shows a typing indicator instead of the preview. |
| `href` | `string` |  | Render as a link. |
| `onclick` | `(e: MouseEvent) => void` |  | Click handler. |

---

# Audio Player

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/audio-player/

A voice message player with waveform scrubbing, playback rate, lazy loading and slider semantics.

```svelte
<script>
  import { AudioPlayer } from "@codeatlasdev/ui";
</script>

<AudioPlayer src="/voice/42.ogg" peaks={peaks} duration={31} />
```

The native `<audio controls>` is unstyled and differs in dark mode and on iOS. This player keeps the `<audio>` element but draws its own controls. The `src` is attached on the first play (`preload="none"`), so a thread with fifty voice notes makes no request until you press play; pass `duration` so the UI is complete before that. The waveform is a `role="slider"`: drag or click to seek, Arrow keys move 5 seconds, Page Up and Page Down 10, Home and End jump. Starting one player pauses any other.

### Voice messages

With peaks, and without waveform data.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` |  | Audio URL, loaded on first play. |
| `peaks` | `number[]` |  | Waveform amplitudes from 0 to 1, resampled to the width. |
| `duration` | `number` |  | Seconds, shown before metadata loads. |
| `rates` | `number[]` | [1, 1.5, 2] | Playback speeds the rate button cycles through. |
| `preload` | `'none' \| 'metadata'` | 'none' | Load nothing, or only metadata, before the first play. |
| `label` | `string` |  | Accessible name of the player. |
| `onplay / onpause / onended / onerror` | `(e: Event) => void` |  | Media events. |

---

# Media Grid

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/media-grid/

Image, video and document tiles for a chat message that open a Lightbox gallery.

```svelte
<script>
  import { MediaGrid } from "@codeatlasdev/ui";
</script>

<MediaGrid items={[{ src: "/a.jpg", alt: "Beach" }, { type: "video", src: "/b.mp4", thumb: "/b.jpg", duration: "0:12" }]} />
```

Tiles keep their box while the thumbnail loads (a skeleton shows meanwhile) and show an error state if it fails. Past `maxVisible` the last tile reads "+N more" and opens the gallery at that index. Images and videos open a [Lightbox](/docs/feedback/lightbox/) with previous and next; documents are plain download links and stay out of the gallery.

### Mixed media

Images, a video, a document and the +N overflow tile.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `MediaGridItem[]` |  | { type?, src, thumb?, alt?, title?, caption?, meta?, duration?, poster?, download?, size? }. |
| `maxVisible` | `number` | 4 | Tiles shown before the +N overflow tile. |
| `columns` | `1 \| 2 \| 3` |  | Defaults by item count. |
| `label` | `string` |  | Accessible name of the group. |
| `onopen` | `(index: number, item: MediaGridItem) => void` |  | Called when a tile is opened. |
| `ondownload` | `(item, index) => void` |  | Forwarded to the Lightbox Download button. |

---

# Virtual List

Group: Display. URL: https://ui.codeatlas.com.br/docs/display/virtual-list/

A windowed list with load-older at the top that keeps the scroll position, for long chat histories.

```svelte
<script>
  import { VirtualList } from "@codeatlasdev/ui";
</script>

<VirtualList {items} getKey={(m) => m.id} label="Conversation" {hasMore} loadingMore={loading} onloadmore={loadOlder}>
  {#snippet item(m)}<Message {m} />{/snippet}
</VirtualList>
```

Only the rows in view (plus `overscan`) are in the DOM; row heights are measured, so they can vary. Prepending older rows keeps the row you were reading in the same place: the list finds the previous first row by `getKey` and corrects `scrollTop`. `LiveList` follows the bottom but cannot prepend history without a jump; this one can, and also follows new rows while you are at the bottom. A visible "Load older messages" button gives keyboard and screen reader users the same trigger as scrolling.

### Chat history

Scroll to the top to load older messages; the view does not jump.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `readonly T[]` |  | Rows, oldest first. |
| `item` | `Snippet<[T, number]>` |  | One row, rendered inside an li. |
| `getKey` | `(item: T, index: number) => string \| number` |  | Stable key per row; required to keep position on prepend. |
| `label` | `string` |  | Accessible name of the scrolling region. |
| `estimateSize` | `number` | 56 | Row height guess in px until measured. |
| `overscan` | `number` | 6 | Extra rows rendered above and below the view. |
| `height` | `string` | '24rem' | Height of the scrolling area. |
| `follow` | `boolean` | true | Stay at the bottom while new rows arrive and you are there. |
| `hasMore` | `boolean` | false | More older rows exist. |
| `loadingMore` | `boolean` | false | A page is loading. |
| `loadThreshold` | `number` | 120 | Distance from the top in px that triggers onloadmore. |
| `onloadmore` | `() => void \| Promise<void>` |  | Load the next older page. |
| `empty` | `Snippet` |  | Shown when there are no rows. |

---

# Dialog

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/dialog/

A second-layer modal. The overlay blurs the page while the panel uses a solid surface.

```svelte
<script>
  import { Dialog, Button } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<Dialog bind:open title="Confirm" description="This cannot be undone.">
  {#snippet actions()}
    <Button variant="ghost" onclick={() => (open = false)}>Cancel</Button>
    <Button variant="destructive" onclick={remove}>Delete</Button>
  {/snippet}
</Dialog>
```

The dialog renders a native modal `<dialog>` opened with `showModal()`: the page behind is inert, focus is trapped, scrolling is locked and Escape closes it. Clicking the overlay closes it too. For decisions that need an explicit answer use [AlertDialog](/docs/feedback/alert-dialog/). On phones, prefer [Sheet](/docs/feedback/sheet/) for bottom-anchored content.

### Confirmation

The destructive confirm and cancel pattern.

### Info

Informational content with a single action.

### Form

A dialog holding a form, at the md size.

### Chromeless

No header, description or actions, and the body has no padding. The title becomes the visually hidden accessible name.

### Split

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `title` | `string` |  | Header title. With chromeless it is the hidden accessible name. |
| `description` | `string` |  | Subtitle below the title. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'split'` | 'md' | Width: 400, 480, 600 or 820px. split is 1100 by 720 in two columns from 900px. |
| `chromeless` | `boolean` | false | Omits header, description and actions; the body has no padding. title and description stay available to screen readers. |
| `children` | `Snippet` |  | Dialog body. |
| `actions` | `Snippet` |  | Footer buttons. |
| `onOpenChange` | `(open: boolean) => void` |  | Called whenever the open state changes. |
| `class` | `string` | '' | Extra classes on the panel. |

## Layers

Dialogs, sheets, drawers, menus, popovers and tooltips share one layer stack. Modals are native `<dialog>` elements opened with `showModal()`; menus, popovers and tooltips are `popover` elements. Both live in the browser's top layer, so a layer opened later is always on top: there is no `z-index` to manage, and a menu inside a dialog just works. Anchored layers use CSS anchor positioning where the browser supports it and fall back to Floating UI elsewhere.

Escape and outside presses go to the topmost layer only, so a menu inside a dialog closes first and the dialog on the next press. A layer stops being the topmost one the moment its `open` turns false, not when its exit animation ends: an Escape pressed while a confirm dialog is fading out reaches the drawer underneath. A menu that was already open when a modal opened ranks above that modal, so the first Escape closes the menu and the second the dialog. Focus returns to the trigger when a layer closes.

An open modal makes the rest of the page inert (no pointer, no Tab, no screen reader), and that includes top-layer popovers that live outside it. So a menu, select list, popover or tooltip is mounted inside the topmost open modal while it is open and goes back to where it was declared when it closes. This also holds when the modal opens after the popover (a shortcut opening a dialog over an open menu): the popover moves into the new modal and is shown again above it, and when a modal closes first its popovers are handed to the next modal or put back. Do not give a layer a `z-index` to fight this: it has no effect in the top layer.

A host that draws outside the DOM (a native view over a webview) can follow the stack with `onLayerChange`. It fires on every open and close with the open layers, bottom to top, and their rectangles, and returns the function that unsubscribes:

```ts
import { onLayerChange, type LayerChange } from "@codeatlasdev/ui";

const stop = onLayerChange((change: LayerChange) => {
  nativeView.setParked(change.count > 0);
  // change.layers: LayerInfo[], bottom to top
  // each LayerInfo is { kind: LayerKind, rect: DOMRect }
});
```

The same signal is a `layerchange` `CustomEvent` on `document`, with the detail as `event.detail`. `LayerChange` is `{ layers: LayerInfo[]; count: number; modal: boolean }`, where `modal` is true while at least one modal layer is open. `LayerKind` is `"modal"` for Dialog, AlertDialog, Drawer and Sheet, `"popover"` for menus and popovers, and `"hint"` for tooltips. All three types are exported from `@codeatlasdev/ui`.

---

# AlertDialog

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/alert-dialog/

A confirmation dialog that demands an explicit answer, with role alertdialog and async confirm handling.

```svelte
<script>
  import { AlertDialog } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<AlertDialog
  bind:open
  title="Delete item?"
  description="This action cannot be undone."
  confirmLabel="Delete"
  destructive
  onconfirm={() => api.remove(id)}
/>
```

Unlike [Dialog](/docs/feedback/dialog/), there is no close button and a click outside does not dismiss it, and initial focus lands on the dialog itself instead of the first control. Escape and Cancel close it and fire `oncancel`. Both are ignored while a request is pending.

### Basic and destructive

Confirm and cancel, with the destructive variant for irreversible actions.

### Async onconfirm

While the promise is pending the confirm button shows a spinner, Cancel is disabled and Escape is ignored. The dialog closes when it resolves and stays open if it throws.

### Controlled pending

Pass pending when the loading state lives outside, for example a mutation from your query client.

### Type to confirm

children renders a field under the description, confirmDisabled keeps Confirm off until the key matches, description takes a snippet for rich text, and confirmProps tags the button for tests.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `title` | `string` |  | Required. Dialog title and accessible name. |
| `description` | `string \| Snippet` |  | Supporting text below the title. Pass a snippet for rich text; it still describes the dialog. |
| `children` | `Snippet` |  | Body between the description and the buttons: a confirmation field or a choice. |
| `confirmLabel` | `string` | 'Confirm' (localized) | Label of the confirm button. Defaults to the active locale's string. |
| `cancelLabel` | `string` | 'Cancel' (localized) | Label of the cancel button. Defaults to the active locale's string. |
| `cancelVariant` | `'ghost' \| 'outlined' \| 'glass' \| 'filled'` | 'ghost' | Variant of the cancel button. |
| `confirmDisabled` | `boolean` | false | Keeps Confirm disabled, for type-to-confirm. Escape and Cancel still close the dialog. |
| `confirmProps` | `{ id, class, size, aria-label, aria-describedby, data-* }` |  | Attributes for the confirm button. Variant, loading, label and click stay owned by the dialog. |
| `cancelProps` | `{ id, class, size, aria-label, aria-describedby, data-* }` |  | Attributes for the cancel button. |
| `destructive` | `boolean` | false | Confirm button uses the destructive variant. |
| `pending` | `boolean` | false | Controls the loading state externally. Without it, pending is automatic while onconfirm is awaited. |
| `onconfirm` | `() => void \| Promise<void>` |  | Required. Closes the dialog when it resolves; if it throws, the dialog stays open and the error propagates. |
| `oncancel` | `() => void` |  | Fires on Cancel or Escape. Never fires while pending. |
| `class` | `string` | '' | Extra classes on the panel. |

---

# Drawer

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/drawer/

A side or bottom panel for the second layer, with a blurred overlay and a solid panel.

```svelte
<script>
  import { Drawer, Button } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<Drawer bind:open title="Filters" side="right" width="360px">
  ...
  {#snippet actions()}<Button onclick={apply}>Apply</Button>{/snippet}
</Drawer>
```

Same architecture as [Dialog](/docs/feedback/dialog/): the overlay blurs the page and the panel is a solid surface that slides in from an edge. For a mobile bottom panel with swipe to dismiss, use [Sheet](/docs/feedback/sheet/).

### Right (default)

Slides in from the right, with a footer actions area.

### Left and bottom

Left suits mobile navigation. Bottom is a simple bottom panel without gestures.

### Notification panel

A real-world use: a 400px wide panel on the right.

### Own header

No title: aria-labelledby points at your heading, so the panel keeps its accessible name while you build the header and its close button. Attributes such as data-testid reach the dialog.

The panel needs a name. Pass `title` (add `hideTitle` to keep it for screen readers only), or `aria-label`, or `aria-labelledby` with the id of your own heading. Any other attribute (`id`, `data-*`, `style`) reaches the `<dialog>` element.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `side` | `'left' \| 'right' \| 'bottom'` | 'right' | Edge the panel slides from. |
| `title` | `string` |  | Header title and the panel's accessible name. |
| `hideTitle` | `boolean` | false | Hides the title heading visually but keeps it as the accessible name; the header shrinks to the close button. |
| `aria-label` | `string` |  | Accessible name when there is no `title`. Replaces the title reference. |
| `aria-labelledby` | `string` |  | Id of your own heading, for a custom header inside the body. Wins over `title`. |
| `width` | `string` | '360px' | Panel width for left and right. |
| `children` | `Snippet` |  | Panel body. |
| `actions` | `Snippet` |  | Footer buttons, separated by a top rule. |
| `onOpenChange` | `(open: boolean) => void` |  | Called whenever the open state changes. |
| `class` | `string` | '' | Extra classes on the panel. |

---

# Sheet

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/sheet/

A mobile-first bottom sheet with swipe to dismiss that becomes a centered dialog from 900px.

```svelte
<script>
  import { Sheet, Button } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<Sheet bind:open title="Switch session" description="Choose the active account">
  ...
  {#snippet footer()}<Button>New session</Button>{/snippet}
</Sheet>
```

Below 900px the sheet rises from the bottom edge with a drag handle, safe-area padding and rounded top corners. From 900px up it renders as a centered dialog. Focus trap, focus restore, Escape, overlay dismissal and scroll lock come from the native modal `<dialog>` the sheet renders.

**Swipe to dismiss.** Drag the handle or the header down. Releasing past 30% of the panel height, or faster than 0.5 px/ms, closes the sheet; otherwise it springs back. The gesture is off under `prefers-reduced-motion` and in the centered desktop layout. Keyboard users close it with Escape or the close button. Open the demos below on a phone or in a mobile viewport to try the gesture.

### Swipe to dismiss

Drag the handle or header down on a viewport below 900px. Above that, it is a centered dialog.

### Footer and swipeToDismiss

A pinned footer, and swipeToDismiss set to false so only the close button, Escape and the overlay dismiss it.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `title` | `string` |  | Header title. Without it the panel falls back to a localized generic aria-label. |
| `description` | `string` |  | Supporting text under the title. |
| `swipeToDismiss` | `boolean` | true | Drag the handle or header down to dismiss in the bottom-sheet layout. Ignored under reduced motion and on desktop. |
| `onclose` | `() => void` |  | Called when the sheet closes by swipe, close button, Escape or overlay. |
| `children` | `Snippet` |  | Required. Scrollable body. |
| `footer` | `Snippet` |  | Pinned footer below the body. |

---

# Skeleton

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/skeleton/

Loading placeholders that match the shape of the real content.

```svelte
<script>
  import { Skeleton } from "@codeatlasdev/ui";
</script>

<Skeleton height="20px" width="60%" />
<Skeleton variant="circular" width={48} height={48} />
<Skeleton rows={3} />
```

Skeletons are `aria-hidden`. Announce the loading state on the container, for example with `aria-busy="true"`, and leave the placeholders silent.

## The `skeleton` prop

`Avatar`, `KpiCard`, `TextField`, `Table`, `Card` and `GlassCard` take `skeleton`. The component keeps its real DOM, so the placeholder has exactly the loaded size (no layout shift): content is laid out but hidden, the host paints the same shimmer as `<Skeleton>`, and it is announced with `aria-busy="true"`. A skeleton `TextField` is disabled and an `Avatar` makes no image request. For `Table`, render placeholder rows so the height matches. Under `prefers-reduced-motion` the sweep stops and the placeholder is dimmed.

The sweep is a gradient band. Under the plain surface styles (`defaultStyle: "flat"`, `"solid"` or `"outlined"`, or `data-style` on `<html>`) no gradient is drawn: `<Skeleton>` and the `skeleton` prop pulse their opacity on a flat block instead. Glass, frosted, neumorphic, clay, chrome and tonal keep the sweep.

### Text lines

With rows, the last line is shortened to 60% for a natural paragraph.

### Card layout

### The skeleton prop

One flag on the real component keeps its size while data loads.

### Image placeholder

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `'text' \| 'circular' \| 'rectangular' \| 'rounded'` | 'text' | Shape of the placeholder. |
| `width` | `string \| number` |  | CSS width. Numbers are treated as pixels. |
| `height` | `string \| number` |  | CSS height. Numbers are treated as pixels. |
| `rows` | `number` | 1 | Renders several stacked lines. For the text variant the last one is 60% wide. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Spinner

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/spinner/

An inline loading indicator for buttons, sections and overlays.

```svelte
<script>
  import { Spinner } from "@codeatlasdev/ui";
</script>

<Spinner size={24} />
```

The spinner has `role="status"` and a localized `aria-label`. Under `prefers-reduced-motion` it slows down instead of stopping. For buttons, prefer `Button`'s `loading` prop, which swaps the leading icon for a spinner and sets `aria-busy`.

### Sizes

The size prop takes a number of pixels or any CSS length.

### In a button

Use the loading prop of Button instead of placing a Spinner by hand.

### Section loader

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `number \| string` | 24 | Diameter. Numbers are pixels; strings are any CSS length. |
| `label` | `string` | 'Loading…' (localized) | Accessible label. Defaults to the active locale's string. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Progress

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/progress/

A linear progress bar with determinate values, an indeterminate animation and an accessible label.

```svelte
<script>
  import { Progress } from "@codeatlasdev/ui";
</script>

<Progress value={60} label="Upload progress" />
<Progress indeterminate label="Loading" />
```

Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin` (always 0) and `aria-valuemax` (from `max`). Always pass `label` so screen readers know what is progressing. The indeterminate state omits `aria-valuenow`.

### Determinate

An explicit value from 0 to max (100 by default).

### Indeterminate

Use when progress cannot be determined.

### Animated

Start a simulated upload.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` | 0 | Current progress value. |
| `max` | `number` | 100 | Maximum value, also exposed as `aria-valuemax`. The fill width is clamped between 0 and 100%. |
| `indeterminate` | `boolean` | false | Plays the shimmer animation when progress is unknown. |
| `label` | `string` | undefined | Accessible name, set as `aria-label`. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Toast

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/toast/

A global notification system. Mount Toaster once, then call toast.success(), toast.error() and friends from anywhere.

Mount `Toaster` once in the root layout:

```svelte
<!-- +layout.svelte -->
<script>
  import { Toaster } from "@codeatlasdev/ui";
  let { children } = $props();
</script>

{@render children()}
<Toaster />
```

Then call `toast` from anywhere:

```svelte
<script>
  import { toast } from "@codeatlasdev/ui";
</script>

<button onclick={() => toast.success("Changes saved.")}>Save</button>
```

`toast` is a global store, so the calls need no component context. The Toaster is a polite live region (`role="region"`, `aria-live="polite"`) and each toast is a `role="status"` with a dismiss button. Toasts stack in the bottom right corner, up to 380px wide, in a fixed container layered with `--ca-z-snackbar` (they are not in the browser top layer, unlike dialogs and popovers). `toast.show` accepts `variant` and `duration` in its options; the shortcut methods take the duration as a second argument. The demo below mounts its own `Toaster` because every demo is an independent island.

### Variants and duration

Five variants, plus persistent (duration 0) and custom durations. The default auto-dismiss is 4 seconds.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `toast.show(message, opts?)` | `(message: string, opts?: { variant?: ToastVariant; duration?: number }) => string` |  | Shows a toast and returns its id. Variant defaults to 'default'. |
| `toast.success(message, duration?)` | `(message: string, duration?: number) => string` |  | Success toast. |
| `toast.error(message, duration?)` | `(message: string, duration?: number) => string` |  | Error toast. |
| `toast.warning(message, duration?)` | `(message: string, duration?: number) => string` |  | Warning toast. |
| `toast.info(message, duration?)` | `(message: string, duration?: number) => string` |  | Info toast. |
| `toast.remove(id)` | `(id: string) => void` |  | Dismisses a toast by id. |
| `toast.items` | `ToastItem[]` |  | Reactive list of the visible toasts. |
| `duration` | `number` | 4000 | Auto-dismiss delay in ms. 0 keeps the toast until dismissed. |
| `ToastVariant` | `'default' \| 'success' \| 'error' \| 'warning' \| 'info'` |  | Accepted variants. |

---

# Lightbox

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/lightbox/

A full-screen viewer for images and videos, single or as a gallery, on a native modal dialog.

```svelte
<script>
  import { Lightbox } from "@codeatlasdev/ui";

  let open = $state(false);
</script>

<button onclick={() => (open = true)}>View photo</button>
<Lightbox bind:open src={url} alt="Photo sent by Maria" />
```

Pass `items` for a gallery of images and videos; `src` and `alt` are sugar for a single image.

```svelte
<Lightbox bind:open bind:index items={[
  { src: photo, alt: "Beach", caption: "Praia", meta: "Maria, 10:42" },
  { type: "video", src: clip, poster, alt: "Short clip" },
]} ondownload={(item, i) => save(item)} />
```

With more than one item the viewer shows previous and next buttons, a counter, and answers to the ArrowLeft and ArrowRight keys and to a horizontal swipe. It does not wrap: the buttons at either end are `aria-disabled` and keep focus. Arrow keys are left alone while a video has focus so they keep seeking, and a video is paused as soon as you move to another item. The caption and `meta` (sender, time) overlay the bottom edge without changing the media box. A Download button appears for galleries: `ondownload(item, index)` replaces the default `<a download>` to `item.download ?? item.src`, which only works for same-origin or CORS-enabled files.

The media is contained in the viewport and respects the device safe areas. Escape, the close button and a click on the backdrop close it. Because it is a native modal `<dialog>`, the page behind is inert, focus returns to the trigger and scrolling is locked while it is open. `alt` is required.

### Open from a button

### Gallery with video, caption and download

Arrow keys, buttons and swipe move through the items.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `src` | `string` |  | Single-image sugar: same as `items={[{ src, alt }]}`. |
| `alt` | `string` |  | Image description for the `src` form. |
| `items` | `LightboxItem[]` |  | Gallery. Each item: `{ type?: 'image' \| 'video', src, alt?, caption?, meta?, poster?, download? }`. Wins over `src`. |
| `index` | `number` | 0 | Bindable current item. |
| `ondownload` | `(item: LightboxItem, index: number) => void` |  | Replaces the default download link. The Download button shows for `items` galleries. |
| `onclose` | `() => void` |  | Called after the viewer closes. |

---

# InstallPrompt

Group: Feedback. URL: https://ui.codeatlas.com.br/docs/feedback/install-prompt/

A dismissible banner that offers to install the app, with the native dialog on Chromium and Share-sheet steps on iOS.

```svelte
<script>
  import { InstallPrompt } from "@codeatlasdev/ui";
</script>

<InstallPrompt onchoice={(outcome) => console.log(outcome)} />
```

Render it once, in the root layout. It shows nothing until there is something to offer:

- **Chromium (Android, desktop)**: it keeps the `beforeinstallprompt` event, so the browser's own mini-infobar does not appear, and shows an **Install** button that opens the native dialog. The browser only fires the event when the app is installable: a manifest with `display: "standalone"` and 192 and 512 icons, and a service worker (see [PWA](/docs/getting-started/pwa/)).
- **iOS Safari** (iPhone, and iPad, which reports a Mac user agent): Safari has no install API, so it shows the two steps, Share then Add to Home Screen.
- **Already installed** (`display-mode: standalone`, or `navigator.standalone`): nothing.
- **Dismissed**: nothing for `dismissDays`, remembered in `localStorage`.

### Native prompt

The Chromium flow: Install opens the browser's install dialog. This demo fires a stand-in event so the banner shows in any browser.

### iOS instructions

What Safari on iPhone and iPad gets: the two steps, no button.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `mode` | `'auto' \| 'native' \| 'ios'` | 'auto' | `auto` picks from the browser. Force `native` or `ios` to document or test one flow. |
| `dismissDays` | `number` | 14 | Days the banner stays hidden after the user closes it. |
| `storageKey` | `string` | 'ca-install-dismissed' | `localStorage` key that holds the end of the dismissal. |
| `onchoice` | `(outcome: 'accepted' \| 'dismissed') => void` |  | The user's answer in the browser's install dialog. |
| `ondismiss` | `() => void` |  | The user closed the banner with the close button. |
| `class` | `string` | '' | Extra CSS classes. |

Strings come from the `installPrompt` group of the i18n catalog (`en` and `pt-BR` built in).

---

# Command Palette

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/command-palette/

A spotlight-style navigation overlay opened with Cmd+K or Ctrl+K from anywhere.

```svelte
<script>
  import { CommandPalette } from "@codeatlasdev/ui";
  import { goto } from "$app/navigation";
  let open = $state(false);
</script>

<CommandPalette modules={NAV} onNavigate={(path) => goto(path)} bind:open />
```

The palette searches the same `NavModule[]` you pass to [AppShellLayout](/docs/layout/app-shell/), matching on item label and module label. It registers `Cmd+K` and `Ctrl+K` itself on `window`, so mount it once near the root. It opens as a modal dialog layer. Arrow keys move the selection, Enter navigates and Escape closes.

### Open the palette

Click the button or press Cmd+K / Ctrl+K while this page is focused. Picking an item shows its path instead of navigating.

### Keyboard

Type to filter across every module. Queries shorter than minQueryLength keep the full grouped list.

## Async results

Pass `search` to add server-side results under the local matches. It runs once the user stops typing for `searchDebounce` ms, receives the trimmed query and an `AbortSignal`, and returns `CommandResult[]` (`{ id, label, group?, path }`). A newer query, closing the palette or unmounting aborts the pending call, so forward the signal to `fetch` and never apply a stale answer. While it runs the list is `aria-busy` and a "Searching…" row shows; a rejection shows "Search failed" without hiding local matches; the empty state appears only after the search settles. Progress, the result count and failures are announced through `announce()`.

Results with a `group` are listed under that heading. Activating one calls `onSelect(result)` when provided, otherwise `onNavigate(result.path)`.

### Async results

A simulated 600 ms server search, grouped, with loading and abort on every new query.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `modules` | `NavModule[]` |  | Navigation tree to search. Same format as AppShellLayout. |
| `onNavigate` | `(path: string) => void` |  | Called with the selected item's path. Use goto() in SvelteKit or location in static sites. |
| `open` | `boolean` | false | Bindable. Controls visibility. Cmd+K and Ctrl+K also toggle it. |
| `minQueryLength` | `number` | 1 | Trimmed characters needed before the list is filtered. Shorter queries keep the full grouped list. |
| `search` | `(query: string, signal: AbortSignal) => Promise<CommandResult[]>` |  | Async/server-side search, debounced and aborted on every new query. Throw or reject to show the failed state. |
| `searchDebounce` | `number` | 200 | Milliseconds without typing before `search` is called. |
| `shortcut` | `boolean` | true | Opens and closes on Mod+K (Cmd+K / Ctrl+K) anywhere in the window. Turn it off for every palette but one when a page has several, or when the app binds its own shortcut. |
| `onSelect` | `(result: CommandResult) => void` |  | Called with the whole result when a server result is activated. Replaces `onNavigate` for those results. |
| `query` | `string` | '' | Bindable current input text. |

---

# Dropdown Menu

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/menu/

A floating action menu with items, checkbox and radio items, submenus and context-menu anchoring.

```svelte
<script>
  import {
    DropdownMenu,
    DropdownMenuItem,
    DropdownMenuLabel,
    DropdownMenuSeparator,
    Button,
  } from "@codeatlasdev/ui";
</script>

<DropdownMenu>
  {#snippet triggerChild(props)}<Button {...props}>Open menu</Button>{/snippet}
  <DropdownMenuLabel>File actions</DropdownMenuLabel>
  <DropdownMenuItem onclick={edit}>{#snippet children()}Edit{/snippet}</DropdownMenuItem>
  <DropdownMenuSeparator />
  <DropdownMenuItem variant="destructive" onclick={remove}>{#snippet children()}Delete{/snippet}</DropdownMenuItem>
</DropdownMenu>
```

Keyboard support follows the WAI-ARIA menu pattern: Enter, Space or ArrowDown opens the menu on the first item, ArrowUp opens it on the last, arrows then move, Enter or Space selects, Escape closes and focus returns to the trigger. Tab closes the menu. Selecting an item closes it. The menu is a popover layer in the browser top layer, positioned with CSS anchor positioning where supported, so it stays on top of a dialog it is opened from. Pass an interactive trigger (`Button`, `IconButton`) through `triggerChild` and spread the received `props` on it. Use `trigger` only for non-interactive content such as text or an icon. Use `DropdownMenuLabel` for a non-interactive group heading and `DropdownMenuSeparator` for a divider.

### Checkbox and radio items

`DropdownMenuCheckboxItem` renders `role="menuitemcheckbox"` with `aria-checked` and a check indicator; bind `checked` or listen to `onCheckedChange`. `DropdownMenuRadioGroup` wraps `DropdownMenuRadioItem`s (`role="menuitemradio"`): bind the group's `value`, each item sets it with its own `value`. Enter, Space or a click toggles the item and the menu stays open so several options can be set in one visit (the WAI-ARIA menu pattern); pass `closeOnSelect` to close after one pick. Arrow keys, Home, End and typeahead reach these items like any other, and disabled ones are skipped. Give the group an `aria-label` or put a `DropdownMenuLabel` first and the group is named for screen readers.

### Controlled and context menus

`bind:open` and `onOpenChange` control the menu from outside: set `open = true` from any handler and it opens; `onOpenChange` fires for user-driven changes (a trigger press, Escape, an outside press, picking an item), like `Dialog`. For a right-click menu pass `anchor={{ x, y }}` (viewport coordinates) together with `open = true` and leave out `trigger`: the menu opens at that point on the first item and focus returns to the element that had it when the menu closes. Setting `anchor` again while the menu is open moves it instead of toggling it, so a second right-click relocates the menu. Handle Shift+F10 and the ContextMenu key in your own `onkeydown` the same way (the demo shows both); on the built-in trigger they open the menu on its first item.

### Submenus

Put a `DropdownMenuSub` among the items. Its `trigger` snippet holds a `DropdownMenuSubTrigger` (an item with a chevron, `aria-haspopup="menu"` and `aria-expanded`) and its children are the submenu's items, labels and further `DropdownMenuSub`s, nested to any depth. ArrowRight, Enter or Space on the trigger opens the submenu with focus on its first enabled item; ArrowLeft or Escape closes only that level and returns focus to the trigger; arrows, Home, End and typeahead stay inside the open level. Hovering the trigger opens it after `openDelay` (120 ms) and it stays open for `closeDelay` (200 ms) after the pointer leaves, so the pointer can cross the gap. Selecting any item closes every level and returns focus to the root trigger. A disabled sub-trigger neither opens nor takes ArrowRight. In a right-to-left layout use `side="left"` on the sub, and the chevron mirrors.

### Leading icons and brand logos

Pass a leading icon with the `icon` snippet instead of placing it in `children`: it gets a fixed 14px box, the standard gap and `aria-hidden` (the label stays the accessible name), so icon size and alignment never drift between menus. Any `svg` or `img` inside the box fills it, including one wrapped in `SchemeAsset`, whatever `width` or `height` the asset declares. A plain icon (Lucide, any `currentColor` glyph) follows the item's text color, including the highlighted, disabled and destructive states.

A brand logo (a multi-color or fixed-color SVG) must not be recolored: set `brandIcon` on the item and no state color or dimming reaches the icon. A monochrome mark such as the OpenAI blossom needs a black asset on light themes and a white one on dark: wrap both in `SchemeAsset`, which renders the variant of the kit's color scheme (the `.dark` class on `<html>`, or a `data-theme-scope` island) with CSS only, so it is correct in SSR and on first paint and no app has to read the theme store. The same `icon` / `brandIcon` pair exists on `TabsTrigger`. Follow each brand's own guidelines for the marks you ship.

```svelte
<DropdownMenuItem brandIcon onclick={openCodex}>
  {#snippet icon()}
    <SchemeAsset>
      {#snippet light()}<img src="/logos/codex-black.svg" alt="" />{/snippet}
      {#snippet dark()}<img src="/logos/codex-white.svg" alt="" />{/snippet}
    </SchemeAsset>
  {/snippet}
  Codex
</DropdownMenuItem>
```

### Default

A button trigger with a label, items, a separator and a destructive item.

### Leading icons and brand logos

The icon slot gives every item the same box and gap. brandIcon keeps a logo's own colors, and SchemeAsset swaps a monochrome mark between light and dark.

### Checkbox and radio items

Two toggles and a sort order. The menu stays open while options change; each item reports its state with aria-checked.

### Context menu

Right-click opens the menu at the pointer and a second right-click moves it. Shift+F10 or the ContextMenu key opens it from the keyboard.

### Submenus

Color and Move to open beside their item. ArrowRight opens, ArrowLeft or Escape closes one level, hover opens after a short delay.

### Icon trigger

An IconButton trigger. IconButton needs an aria-label.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `triggerChild` | `Snippet<[Record<string, unknown>]>` |  | Interactive trigger. Receives the trigger props to spread onto your Button or IconButton. |
| `trigger` | `Snippet` |  | Non-interactive trigger content (text, icon), wrapped in the menu's own button. |
| `children` | `Snippet` |  | Menu content: items, labels, separators, checkbox and radio items and submenus. |
| `open` | `boolean` | false | Bindable. Whether the menu is open. Set it from code to open or close the menu. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the user opens or closes the menu. |
| `anchor` | `{ x: number; y: number } \| null` | null | Viewport point the menu opens at (a context menu). Changing it while open moves the menu. Omit `trigger` when you use it. |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | 'bottom' | Preferred side of the trigger. |
| `align` | `'start' \| 'center' \| 'end'` | 'start' | Alignment against the trigger. |
| `sideOffset` | `number` | 6 | Distance from the trigger in pixels (0 when opened at an `anchor` point). |
| `class` | `string` | '' | Extra CSS classes on the content. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `onclick` | `() => void` |  | Called when the item is selected. |
| `variant` | `'default' \| 'destructive'` | 'default' | destructive colors the item with the error token. |
| `disabled` | `boolean` | false | Prevents selection. |
| `icon` | `Snippet` |  | Leading icon in a fixed 14px box, `aria-hidden`. A plain icon follows the item's text color. |
| `brandIcon` | `boolean` | false | The icon is a brand mark with its own colors: no highlighted, disabled or destructive color reaches it. Pair with `SchemeAsset` for light and dark assets. |
| `children` | `Snippet` |  | Item label. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `checked` | `boolean` | false | Bindable. Whether the item is checked. |
| `onCheckedChange` | `(checked: boolean) => void` |  | Called with the new state when the user toggles the item. |
| `disabled` | `boolean` | false | Prevents toggling; arrow keys skip the item. |
| `closeOnSelect` | `boolean` | false | Close the menu after toggling. |
| `children` | `Snippet` |  | Item label. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Bindable. Value of the checked radio item. |
| `onValueChange` | `(value: string) => void` |  | Called with the new value when the user picks an item. |
| `children` | `Snippet` |  | DropdownMenuRadioItem children (and an optional DropdownMenuLabel). |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Required. The group value this item sets. |
| `disabled` | `boolean` | false | Prevents selection; arrow keys skip the item. |
| `closeOnSelect` | `boolean` | false | Close the menu after picking. |
| `children` | `Snippet` |  | Item label. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `trigger` | `Snippet` |  | Required. The `DropdownMenuSubTrigger` item that opens the submenu. |
| `children` | `Snippet` |  | Submenu content: items, labels, separators and nested submenus. |
| `open` | `boolean` | false | Bindable. Whether the submenu is open. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the submenu opens or closes. |
| `disabled` | `boolean` | false | The trigger is aria-disabled and the submenu never opens. |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | 'right' | Preferred side of the trigger item. |
| `align` | `'start' \| 'center' \| 'end'` | 'start' | Alignment against the trigger item. |
| `sideOffset` | `number` | 2 | Distance from the trigger item in pixels. |
| `openDelay` | `number` | 120 | Milliseconds the pointer rests on the trigger before it opens. |
| `closeDelay` | `number` | 200 | Milliseconds it stays open after the pointer leaves. |
| `class` | `string` | '' | Extra CSS classes on the submenu content. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `icon` | `Snippet` |  | Leading icon in a fixed 14px box, `aria-hidden`. |
| `children` | `Snippet` |  | Item label. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` |  | Heading text. |
| `class` | `string` | '' | Extra CSS classes. |

Every item, the radio group and the checkbox item forward their remaining attributes (`data-*`, `id`, `aria-*`, `title`) to their element, so `data-testid` and `aria-keyshortcuts` land on the `menuitem`. `role` and `tabindex` stay owned by the component.

`DropdownMenuSeparator` takes no props.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `light` | `Snippet` |  | Required. Rendered while the light scheme is active. |
| `dark` | `Snippet` |  | Required. Rendered while the dark scheme is active. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Popover

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/popover/

A floating overlay anchored to a trigger, for short content or small forms.

```svelte
<script>
  import { Popover, Button } from "@codeatlasdev/ui";
</script>

<Popover side="bottom" align="start">
  {#snippet triggerChild(props)}<Button {...props}>Open</Button>{/snippet}
  Popover content
</Popover>
```

Escape closes the popover and returns focus to the trigger, and a press outside dismisses it. It is a popover layer in the browser top layer, positioned with CSS anchor positioning where supported, so it stays above a dialog it opens from. Pass an interactive trigger through `triggerChild` and spread the received `props` on it; use `trigger` only for non-interactive content. For a hint that appears on hover, use [Tooltip](/docs/display/tooltip/) instead.

To control it, `bind:open` reads and sets the open state, and `onOpenChange` fires when the user opens or closes it (not when your code sets the value). The `children` snippet receives `close`, which closes the popover and returns focus to the trigger: call it after a choice is made inside, the way [DropdownMenu](/docs/navigation/menu/) closes on selection.

```svelte
<Popover bind:open>
  {#snippet triggerChild(props)}<Button {...props}>Pick a date</Button>{/snippet}
  {#snippet children({ close })}
    <Calendar onchange={() => close()} />
  {/snippet}
</Popover>
```

### Basic

Text and an action inside the popover.

### Form

A small form anchored to its trigger, aligned to the start.

### Close on pick

A calendar inside a popover that closes itself when a day is chosen.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `triggerChild` | `Snippet<[Record<string, unknown>]>` |  | Interactive trigger. Receives the trigger props to spread onto your Button or IconButton. |
| `trigger` | `Snippet` |  | Non-interactive trigger content (text, icon), wrapped in the popover's own button. |
| `children` | `Snippet<[{ close: () => void }]>` |  | Popover content. Receives `close`, which closes the popover and returns focus to the trigger. |
| `open` | `boolean` | false | Bindable. Whether the popover is open. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the user opens or closes the popover, not when the bound value is set from code. |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | 'bottom' | Preferred side of the trigger. |
| `align` | `'start' \| 'center' \| 'end'` | 'center' | Alignment against the trigger. |
| `sideOffset` | `number` | 8 | Distance from the trigger in pixels. |
| `class` | `string` | '' | Extra CSS classes on the content. |

---

# Tabs

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/tabs/

Keyboard-navigable tab panels with roving focus, controlled or uncontrolled.

```svelte
<script>
  import { Tabs, TabsList, TabsTrigger, TabsContent } from "@codeatlasdev/ui";
</script>

<Tabs value="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="props">Props</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">...</TabsContent>
  <TabsContent value="props">...</TabsContent>
</Tabs>
```

Arrow keys move between tabs, Home and End jump to the first and last, and focusing a tab selects it (automatic activation). Disabled tabs are skipped. The panels use the `tabpanel` role and are focusable. Each `TabsTrigger` and `TabsContent` pair must share a `value`. `Tabs` is horizontal only.

`TabsList` keeps the width of its tabs (it never stretches across the column) and, when the tabs do not fit, scrolls sideways on its own with the scrollbar hidden. The selected tab is scrolled into view on mount and whenever it changes. The leading `icon` snippet and brand logos are covered on the [Dropdown Menu](/docs/navigation/menu/) page too (same `icon` / `brandIcon` pair). Add `fade` to mask the edge that still has tabs to reveal. No wrapper element or CSS is needed for 7 tabs on a phone.

`variant="line"` drops the glass pill: bare text tabs with a hairline under the strip and a 2px underline on the active tab, the usual look in a page header. Tabs that only switch a view (no `TabsContent`) are fine: a trigger points `aria-controls` at its panel only while a `TabsContent` with the same `value` is mounted, so nothing references a missing element. Name the strip with `aria-label` (or `aria-labelledby`) on `TabsList`; `TabsList` and `TabsTrigger` forward any other attribute (`data-*`, `id`, `aria-*`, event handlers) to their element.

`TabsTrigger` forwards any other button attribute (`data-testid`, `id`, `aria-*`, `onclick`, `onfocus`) to its `<button role="tab">`, and `TabsList` forwards `data-*`, `id` and `aria-*` to the `role="tablist"` element. `role`, `type` and the roving `tabindex` stay owned by the component.

### Default

Three tabs with content panels.

### Controlled

The parent owns the active tab with bind:value.

### Icons

A leading icon per tab. A brand logo keeps its own colors with brandIcon; SchemeAsset swaps a monochrome mark between light and dark.

### Line

variant=line as a view switcher: aria-label on the list, data-testid on a trigger, no panels.

### Scrollable

Seven tabs in a narrow column: the list scrolls on its own, the active tab starts in view, and fade marks the edge.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Bindable active tab value. |
| `onchange` | `(v: string) => void` |  | Fires when the active tab changes by click or keyboard. |
| `variant` | `'pill' \| 'line'` | 'pill' | `pill` fills the active tab on a glass list. `line` is bare text with an underline on the active tab, for page headers. |
| `children` | `Snippet` |  | `TabsList` and `TabsContent` children. |
| `class` | `string` | '' | Extra classes on the root. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Required. Links the trigger to its TabsContent. |
| `disabled` | `boolean` | false | Prevents selecting the tab. |
| `icon` | `Snippet` |  | Leading icon in a fixed 14px box, `aria-hidden`: the label stays the accessible name. Any `svg` or `img` inside the box fills it, including one wrapped in `SchemeAsset`. A plain icon follows the tab's text color. |
| `brandIcon` | `boolean` | false | The icon is a brand mark with its own colors: no active, hover or disabled color reaches it. Pair it with `SchemeAsset` when the mark needs a light and a dark asset. |
| `children` | `Snippet` |  | Trigger label. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Required. Shown while the matching trigger is active. |
| `children` | `Snippet` |  | Panel content. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `fade` | `boolean` | false | Fade the edge(s) that still hide tabs, so the strip reads as scrollable. |
| `aria-label` | `string` |  | Accessible name of the tablist (also `aria-labelledby`). Name it whenever the page has more than one tablist or the purpose is not obvious. |
| `children` | `Snippet` |  | The `TabsTrigger` elements. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Breadcrumb

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/breadcrumb/

An accessible navigation trail that is framework-agnostic, so you pass the items directly.

```svelte
<script>
  import { Breadcrumb } from "@codeatlasdev/ui";
</script>

<Breadcrumb items={[{ label: "Home", href: "/" }, { label: "Components" }]} />
```

Rendered as a `nav` landmark with an ordered list. The last item is the current page: it has `aria-current="page"` and is never a link. Items without `href` render as plain text.

### Levels

Two, three and five levels, and a single root item.

### Custom separator

Using › instead of /.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `BreadcrumbItem[]` |  | Array of { label, href? }. The last item is always rendered as the current page, without a link. |
| `separator` | `string` | '/' | Character rendered between crumbs. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Stepper

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/stepper/

Multi-step wizard navigation with completed, active and pending states.

```svelte
<script>
  import { Stepper } from "@codeatlasdev/ui";
  let step = $state(0);
  const steps = [{ label: "Account" }, { label: "Profile" }, { label: "Review" }];
</script>

<Stepper {steps} bind:current={step} />
```

The Stepper shows progress and each step bubble is a button that sets `current` when clicked. It does not render the step content or the Back and Next buttons. Drive `current` from your own form state, as in the demo.

### Horizontal stepper

Four steps with Back and Next controls.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `steps` | `StepItem[]` |  | Array of { label, description? }. |
| `current` | `number` | 0 | Bindable, zero-indexed active step. Earlier steps render as completed. |
| `class` | `string` | '' | Extra CSS classes. |

---

# GlassAppBar

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/app-bar/

A top application bar with glass blur and leading, content and trailing slots.

```svelte
<script>
  import { GlassAppBar, IconButton } from "@codeatlasdev/ui";
</script>

<GlassAppBar>
  My Application
  {#snippet trailing()}<IconButton aria-label="Search">...</IconButton>{/snippet}
</GlassAppBar>
```

Renders a `<header>`. Icon-only buttons inside it need an `aria-label`. Inside [AppShell](/docs/layout/app-shell/) use the shell's own header; this bar is for standalone pages.

### Default

Content in the middle and actions in the trailing slot.

### With leading icon

A menu button in the leading slot.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` |  | Main content, for example the title. |
| `leading` | `Snippet` |  | Content at the start, usually a menu button. |
| `trailing` | `Snippet` |  | Content at the end, usually actions and an avatar. |
| `class` | `string` | '' | Extra CSS classes. |

---

# Drawer (navigation)

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/drawer/

The Drawer used for navigation and settings panels that slide in from the left or right edge.

```svelte
<script>
  import { Drawer } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<Drawer bind:open side="left" title="Navigation">...</Drawer>
```

This is the same component as the [Drawer in Feedback](/docs/feedback/drawer/), shown here with the two navigation patterns: a left menu and a right settings panel. It is a native modal `<dialog>` in the top layer: focus is trapped, Escape and a press on the overlay close it, and focus returns to the trigger. See that page for the full props table, the bottom side and the footer `actions` snippet.

### Left and right

Left for navigation, right for settings or details.

---

# Actions

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/actions/

Svelte actions from the @codeatlasdev/ui/actions subpath for outside clicks, focus trapping, autofocus, clipboard and long press.

```svelte
<script>
  import { clickOutside, focusTrap, autofocus, clipboard, longpress, scrollFocusable, keyboardAware, primeKeyboard, focusTextField } from "@codeatlasdev/ui/actions";
</script>

<div use:clickOutside={() => (open = false)}>...</div>
```

Actions attach behavior to a plain element with `use:`. They are exported from `@codeatlasdev/ui/actions`, which keeps them out of the main bundle. Dialog, Sheet, Drawer and Popover already handle focus, Escape and outside presses through the layer engine, so reach for these actions on your own elements.

### clickOutside

Calls the handler for every click that lands outside the element. It listens on the capture phase of `document`.

### focusTrap

Keeps Tab and Shift+Tab inside the element while enabled.

### autofocus

Focuses the element when it mounts.

### clipboard

Copies the given text on click and dispatches a copy event (listen with `oncopy`) once the copy succeeded.

### longpress

Dispatches a longpress event (listen with `onlongpress`) after the pointer is held for the given duration.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `clickOutside` | `Action<HTMLElement, () => void>` |  | Calls the handler when a click lands outside the element. |
| `focusTrap` | `Action<HTMLElement, boolean>` |  | Traps Tab focus inside the element while the parameter is true. |
| `autofocus` | `Action<HTMLElement, { touch?: boolean } \| undefined>` |  | Focuses the element on mount without scrolling. On touch devices it only focuses when primeKeyboard() ran in the opening gesture; pass { touch: true } to focus anyway. |
| `clipboard` | `Action<HTMLElement, string>` |  | Copies the text to the clipboard on click and, once the copy succeeded, dispatches a copy CustomEvent with the text as detail. Nothing is dispatched when the Clipboard API is unavailable, for example on a non-HTTPS page. |
| `longpress` | `Action<HTMLElement, number>` |  | Dispatches a longpress CustomEvent after the pointer is held for the given milliseconds (default 500). Releasing or leaving the element cancels it. |
| `scrollFocusable` | `Action<HTMLElement>` |  | Makes a scroll container keyboard-reachable only while it overflows: sets tabindex="0" when the content is wider or taller than the box and removes it otherwise. SimpleTable and ScrollArea use it. |
| `keyboardAware` | `Action<HTMLElement>` |  | Pads the element's bottom by --ca-kb-inset and scrolls the focused field into view when the on-screen keyboard opens. Use on composers and sticky action bars. |
| `primeKeyboard` | `() => void` |  | Helper, not an action. Call synchronously in the tap handler that opens a view with an autofocused field so iOS and Android open the on-screen keyboard. No-op with a fine pointer. |
| `focusTextField` | `(el: HTMLElement \| null \| undefined, force?: boolean) => boolean` |  | Helper used by autofocus. Focuses the element with a fine pointer, or on touch only after primeKeyboard(). Returns whether it focused. |

---

# Loading boundary

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/loading-boundary/

A loading UI that never flashes, plus a top progress bar and pending links for SvelteKit navigations.

```svelte
<script>
  import { LoadingBoundary } from "@codeatlasdev/ui";
</script>

<LoadingBoundary label="Loading invoices">
  <Invoices /> <!-- contains: const rows = $derived(await load()) -->
</LoadingBoundary>
```

`LoadingBoundary` wraps `<svelte:boundary>` for content that suspends on `await`. It shows nothing for the first `delay` ms (200 by default), so a fast response never flickers a skeleton. Once the placeholder is visible it stays for at least `minDuration` ms (500), so it never flashes for one frame either. Under a second, show nothing; under ten, a skeleton (NN/g). While waiting the region is `role="group"` with `aria-busy="true"` and an accessible name. The default placeholder is `rows` skeleton lines; pass a `pending` snippet shaped like your content to keep the layout still. It needs the `experimental.async` Svelte compiler option in the app.

### Fast and slow loads

A 100 ms load shows nothing. A 1.5 s load shows the skeleton after 200 ms, then the rows.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` |  | The suspending content. |
| `pending` | `Snippet` |  | What to show while waiting. Defaults to skeleton lines. |
| `delay` | `number` | 200 | Milliseconds to wait before showing the placeholder. |
| `minDuration` | `number` | 500 | Minimum milliseconds the placeholder stays once shown. |
| `label` | `string` |  | Accessible name of the busy region. Defaults to a localised 'Loading…'. |
| `rows` | `number` | 3 | Skeleton lines of the default placeholder. |

## Navigation progress

`NavigationProgress` (from `@codeatlasdev/ui/kit`, because it reads `navigating` from SvelteKit's `$app/state`) draws a thin bar at the top of the viewport while a client-side navigation is pending. It appears after `delay` ms (120), so quick navigations show nothing, and it sets `data-ca-navigating` on `<html>`. Mount it once in the root layout, next to `RouteAnnouncer`.

```svelte
<script>
  import { NavigationProgress, RouteAnnouncer, pendingLink } from "@codeatlasdev/ui/kit";
</script>

<NavigationProgress />
<RouteAnnouncer />

<a href="/billing" {@attach pendingLink()}>Billing</a>
```

`pendingLink()` is a link attachment: the `<a>` being navigated to carries `data-pending` and `aria-busy="true"` until the page is ready, so you can style the tapped link (`a[data-pending] { opacity: .6 }`). The AppShell stays mounted through the navigation: only the page below it changes.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `delay` | `number` | 120 | Milliseconds to wait before showing the bar. |
| `label` | `string` |  | Accessible name. Defaults to a localised 'Loading…'. |

---

# App navigation

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/app-navigation/

Make SvelteKit navigations feel instant. Preload defaults, where to mount NavigationProgress and RouteAnnouncer, LoadingBoundary for slow data, pendingLink for the tapped link and view transitions.

A navigation feels fast when the next page is already loaded, and honest when it is not. This page puts the pieces in one root layout: SvelteKit preloading so most clicks finish before the user lifts a finger, then [`NavigationProgress`](#where-to-mount-the-progress-bar), [`LoadingBoundary`](#slow-data-loadingboundary) and [`pendingLink`](#the-tapped-link-pendinglink) for the navigations that still take time.

The package never imports `$app/*` outside `@codeatlasdev/ui/kit`, and it does not set any `data-sveltekit-*` attribute for you. Everything below is app code you copy into your SvelteKit project.

## Preload defaults

SvelteKit preloads from `data-sveltekit-preload-data` (the page's `load` data) and `data-sveltekit-preload-code` (its JavaScript). Put the defaults once on `<body>` in `src/app.html`; every link below it inherits them.

```html
<body data-sveltekit-preload-data="hover" data-sveltekit-preload-code="viewport">
  <div style="display: contents">%sveltekit.body%</div>
</body>
```

| Attribute | Value | What happens |
|---|---|---|
| `data-sveltekit-preload-data` | `hover` | Loads the page's data when the pointer rests on the link, or on `touchstart` on phones. The default for an app: no wasted requests, and the data is usually ready by the time the click lands. |
| `data-sveltekit-preload-data` | `tap` | Loads the data on `mousedown` / `touchstart`. Use it for links to expensive or personalised pages. |
| `data-sveltekit-preload-data` | `off` | No data preloading. Use it where a `load` has side effects or costs money. |
| `data-sveltekit-preload-code` | `viewport` | Downloads the route's JavaScript as soon as the link enters the viewport. The right default for navigation chrome. |
| `data-sveltekit-preload-code` | `eager` | Downloads the code immediately on page load. Reserve it for the one or two most likely next pages. |
| `data-sveltekit-preload-code` | `hover`, `tap` | Same triggers as the data option, for code only. |

Override per link or per region. The nearest ancestor wins, so the AppShell rail and panel can preload more eagerly than a long list of links in the page:

```svelte
<nav data-sveltekit-preload-code="eager">
  <a href="/dashboard">Dashboard</a>
</nav>

<a href="/reports/export" data-sveltekit-preload-data="off">Export</a>
```

Preloading runs the destination's `load` before the user commits to the click. Keep `load` functions free of side effects (writes, counters, one-time tokens) and mark the exceptions `data-sveltekit-preload-data="off"`.

[`AppShellLayout`](/docs/layout/app-shell/) renders its panel items as plain `<a href>` links, so they inherit the `<body>` defaults with no extra wiring. Switching module from the rail or the bottom navigation calls your `onNavigate(path)`: use `goto` there, which runs the same load pipeline.

```svelte
<AppShellLayout {modules} pathname={page.url.pathname} onNavigate={(path) => goto(path)}>
  {@render children()}
</AppShellLayout>
```

## Where to mount the progress bar

`NavigationProgress` and `RouteAnnouncer` come from `@codeatlasdev/ui/kit` (not the main entry), because they read SvelteKit state. Mount both once in the root `src/routes/+layout.svelte`, outside the `AppShellLayout`, so the bar stays fixed to the top of the viewport through every navigation, including those on routes that have no shell.

```svelte
<script lang="ts">
  import "@codeatlasdev/ui/styles/global.css";
  import { NavigationProgress, RouteAnnouncer } from "@codeatlasdev/ui/kit";

  let { children } = $props();
</script>

<NavigationProgress />
<RouteAnnouncer />

{@render children()}
```

- `NavigationProgress` draws a thin bar while `navigating.to` is set. It appears after `delay` ms (120 by default), so a navigation that finishes first, including every preloaded one, shows nothing. While visible it sets `data-ca-navigating` on `<html>`, so you can dim or disable UI during the wait: `html[data-ca-navigating] main { opacity: .7 }`.
- `RouteAnnouncer` announces the new `document.title` (or the page `<h1>`) to screen readers after each client-side navigation. See [Accessibility](/docs/getting-started/accessibility/).
- Keep the AppShell on application routes only, in a route group such as `src/routes/(app)/+layout.svelte`. Marketing routes keep the root layout and the progress bar, without the shell.

```svelte
<!-- src/routes/(app)/+layout.svelte -->
<script lang="ts">
  import { AppShellLayout } from "@codeatlasdev/ui";
  import { goto } from "$app/navigation";
  import { page } from "$app/state";

  let { children } = $props();
</script>

<AppShellLayout {modules} pathname={page.url.pathname} onNavigate={(path) => goto(path)}>
  {@render children()}
</AppShellLayout>
```

The shell stays mounted through a navigation: only the page below it changes, and the progress bar sits above both.

## Slow data: LoadingBoundary

Preloading covers the common case. When a page still suspends on `await`, wrap the part that waits in [`LoadingBoundary`](/docs/navigation/loading-boundary/). It shows nothing for the first 200 ms, then a skeleton that stays at least 500 ms, so neither a fast nor a slow response flashes. It needs the `experimental.async` Svelte compiler option.

```svelte
<script lang="ts">
  import { LoadingBoundary, Skeleton } from "@codeatlasdev/ui";

  async function loadInvoices(): Promise<{ id: string; total: string }[]> {
    return (await fetch("/api/invoices")).json();
  }
</script>

<h1>Invoices</h1>

<LoadingBoundary label="Loading invoices">
  <ul>
    {#each await loadInvoices() as invoice (invoice.id)}
      <li>{invoice.id}: {invoice.total}</li>
    {/each}
  </ul>
  {#snippet pending()}<Skeleton height="12rem" />{/snippet}
</LoadingBoundary>
```

Put the boundary around the data, not around the page: the heading and layout paint at once and only the region that waits shows the placeholder. Shape the `pending` snippet like the real content so nothing jumps when it arrives.

## The tapped link: pendingLink

`pendingLink()` is an attachment for `<a>`. While SvelteKit navigates to that link's `href`, the link carries `data-pending` and `aria-busy="true"`, so the item the user tapped can react before the next page is ready.

```svelte
<script lang="ts">
  import { pendingLink } from "@codeatlasdev/ui/kit";
</script>

<a href="/billing" {@attach pendingLink()}>Billing</a>

<style>
  a[data-pending] { opacity: .6; }
</style>
```

Use it on links you render yourself (a list of records, a card, a custom tab). It matches on pathname, so a link to `/billing?tab=plans` is also marked while `/billing` loads. Like the progress bar it only changes after SvelteKit reports a pending navigation, and a preloaded navigation is usually over before it shows.

## View transitions

For a cross-fade between routes, SvelteKit's `onNavigate` hook starts a browser view transition and waits for the new page. Add it once in the root layout. Skip it when the user prefers reduced motion.

```svelte
<script lang="ts">
  import { onNavigate } from "$app/navigation";

  onNavigate((navigation) => {
    if (!document.startViewTransition) return;
    if (matchMedia("(prefers-reduced-motion: reduce)").matches) return;

    return new Promise((resolve) => {
      document.startViewTransition(async () => {
        resolve();
        await navigation.complete;
      });
    });
  });
</script>
```

The browser cross-fades screenshots, so there is no per-element code. It does not replace the progress bar: for a navigation that takes time, `NavigationProgress` is what tells the user something is happening, and the transition runs once the page is ready.

## Putting it together

| Layer | Handles | Tool |
|---|---|---|
| Preload | Most navigations finish before the click completes | `data-sveltekit-preload-data="hover"` and `data-sveltekit-preload-code="viewport"` on `<body>` |
| Whole navigation | A route that still takes more than 120 ms | `NavigationProgress` in the root layout |
| Tapped link | Feedback where the finger is | `pendingLink()` on the link |
| Data inside a page | A region that awaits | `LoadingBoundary` around it |
| Screen reader | The page changed | `RouteAnnouncer` in the root layout |
| Between routes | A smooth change | `onNavigate` with `document.startViewTransition` |

---

# StickyActions

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/sticky-actions/

A form action bar pinned to the bottom of a scrolling container, with safe-area and virtual keyboard support.

```svelte
<script>
  import { StickyActions, Button } from "@codeatlasdev/ui";
</script>

<StickyActions show={dirty}>
  <Button variant="ghost">Cancel</Button>
  <Button variant="filled">Save</Button>
</StickyActions>
```

Place it as the last child of the element that scrolls. On screens narrower than 900px it sticks to the bottom edge with the `--ca-glass-bg` fill (blurred only under the `glass` and `frosted` styles), respects the home-indicator inset (`--ca-safe-bottom`) and rises with the virtual keyboard. From 900px up it becomes a plain inline row without chrome.

### End aligned

Buttons sit on the right. The bar only renders while the form is dirty (show).

### Stretch

On touch screens the primary button fills the width and the ghost button stays compact.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` |  | The buttons of the bar. |
| `align` | `'end' \| 'stretch'` | 'end' | 'end' packs the buttons to the right. 'stretch' makes the buttons fill the width on touch screens. |
| `show` | `boolean` | true | Renders the bar only while there is something to confirm. |
| `class` | `string` | '' | Extra class names. |

---

# SkipLink

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/skip-link/

A "Skip to content" link that appears on keyboard focus and moves focus to the main landmark. Built into the page shells.

```svelte
<script>
  import { SkipLink } from "@codeatlasdev/ui";
</script>

<SkipLink />
<header>…</header>
<main id="main" tabindex="-1">…</main>
```

`AppShellLayout`, `DocsShell` and `AuthLayout` already render it, so you only need `SkipLink` in shells you build yourself. Press Tab on any docs page to see it: it is the first focusable element and stays off-screen until focused.

The link scrolls to the target and moves focus to it, so the next Tab continues inside the content. The target needs `tabindex="-1"`; the package hides the focus ring on `main[tabindex="-1"]` because that focus is only programmatic.

Keep exactly one `id="main"` and one `<main>` per page. See [Skip link and landmarks](/docs/getting-started/accessibility/#skip-link-and-landmarks) for who owns `#main` in each shell.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `href` | `string` | '#main' | Fragment of the target landmark. It must match the `id` of the element. |
| `children` | `Snippet` |  | Replaces the localized label (`skipLink.label` in the i18n catalog). |
| `class` | `string` | '' | Extra class names. |

---

# Layout primitives

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/layout-primitives/

Box, Flex, Stack, Grid, Container and Section: spacing and alignment as token props, rendered as data attributes with no inline style.

```svelte
<script>
  import { Stack, Flex, Grid, Box, Container, Section } from "@codeatlasdev/ui";
</script>

<Container size="md">
  <Section>
    <Stack as="ul" gap="4">…</Stack>
    <Grid columns={{ base: 1, md: 3 }} gap="4">…</Grid>
  </Section>
</Container>
```

Every primitive renders any element (`as`) and forwards `class` and other attributes. `Box`, `Flex`, `Stack` and `Grid` are typed on the tag: `as="form"` takes the form's own attributes and handlers (`novalidate`, `action`, `onsubmit` with `currentTarget: HTMLFormElement`), `as="a"` takes `href`, `as="label"` takes `for`, and an attribute of another tag is a type error. A token prop never becomes inline CSS: it is a `data-*` attribute (`<div data-gap="4">`) styled by one stylesheet in `@layer ca.utilities`, so the markup is cache-friendly, passes a strict CSP, and an app can override any step with a plain class.

| Primitive | Renders | Props |
|---|---|---|
| `Box` | `div`, padding | `p`, `px`, `py` |
| `Flex` | `display: flex` | `gap`, `p`, `px`, `py`, `align`, `justify`, `direction`, `wrap` |
| `Stack` | a Flex column | `gap`, `p`, `px`, `py`, `align`, `justify` |
| `Grid` | `display: grid`, equal tracks | `columns`, `gap`, `p`, `px`, `py`, `align` |
| `Container` | centered, width-capped, fluid gutter | `size` (`sm` `md` `lg` `xl`), `px`, `py` |
| `Section` | a `<section>` with the page rhythm | `size` (`1` `2` `3`), `px`, `py` |

Spacing values are steps of the spacing scale as strings (`"4"` is `--ca-space-4`, 16px at the default density; `"0.5"` is 2px). The scale is `0 0.5 1 1.5 2 2.5 3 3.5 4 4.5 5 6 7 8 10 11 12 16 20 24`. A value off the scale logs a `[ca-ui]` warning in development and renders unstyled: for a one-off value add a class.

`align` is `start | center | end | stretch | baseline`, `justify` is `start | center | end | between | around | evenly`, `direction` is `row | column | row-reverse | column-reverse`, and `columns` is 1 to 12 equal tracks. For a template like `2fr 1fr` or `repeat(auto-fill, minmax(200px, 1fr))` write `grid-template-columns` in a class.

## Responsive values

Pass an object instead of a value. `base` applies everywhere, and each breakpoint applies from its width up, on the shared scale: `sm` 600, `md` 900, `lg` 1200, `xl` 1536 px. The object becomes `data-gap="2" data-md-gap="4"`.

### Flex, Stack and Box

### Responsive Grid

### Container and Section

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `as` | `keyof SvelteHTMLElements` | per component | Element to render (`div`, `section`, `ul`, `form`...). Box, Flex, Stack and Grid also accept that element's own attributes and event types. |
| `gap` | `Space \| responsive` | undefined | Gap between children. |
| `p, px, py` | `Space \| responsive` | undefined | Padding on every side, horizontal, vertical. |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline' \| responsive` | undefined | `align-items`. |
| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly' \| responsive` | undefined | `justify-content`. |
| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse' \| responsive` | 'row' | Flex only. |
| `wrap` | `boolean \| responsive` | false | Flex only: `flex-wrap: wrap`. |
| `columns` | `1–12 \| responsive` | undefined | Grid only: equal tracks. |

## Migrating from Stack, Grid and Row

`Stack`'s `gap` used to be pixels (`gap={16}`) and `Grid` took `cols`. They now take spacing steps (`gap="4"`) and `columns`, and `Row` is deprecated in favor of `Flex`. Run the codemod, which converts every static usage and leaves the rest for you:

```sh
bunx @codeatlasdev/ui migrate --write src
```

| Before | After |
|---|---|
| `<Stack gap={16}>` | `<Stack gap="4">` |
| `<Stack align="flex-end" justify="space-between">` | `<Stack align="end" justify="between">` |
| `<Row gap={8} wrap>` | `<Flex gap="2" wrap>` |
| `<Grid cols={3} gap={8}>` | `<Grid columns={3} gap="2">` |
| `<Grid cols="2fr 1fr" gap={20}>` | `<Grid cols="2fr 1fr" gap="5">` and a class with `grid-template-columns: 2fr 1fr` (`cols` is reported, the gap is still converted) |

What the codemod cannot map is left as it was and listed at the end with file, line, reason and recipe, for example `src/T.svelte:5 Grid: cols is a template string (write grid-template-columns in a class)` or `src/T.svelte:6 Stack: dynamic gap (use a step string: px / 4, e.g. gap={16} is gap="4")`. A `gap={gap}` left untouched is not harmless: it is now a step, so `16` means 64px. Add `--strict` to exit with code 1 when anything was left (CI, scripts).

---

# MobilePane

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/mobile-pane/

A full-screen pane above the shell for mobile drill-down such as chat threads, history and detail views.

```svelte
<script>
  import { MobilePane } from "@codeatlasdev/ui";
  let open = $state(false);
</script>

<MobilePane bind:open title="Maria Souza" onback={() => (chatId = null)}>
  <Messages />
</MobilePane>
```

The pane is `position: fixed` and covers the viewport, with a header that has a back button. Escape and the back button close it, focus moves into the pane on open and returns to the previous element on close, and the body respects safe-area insets and the virtual keyboard. It replaces hand-rolled fixed panels.

### Chat

Open the pane. On a phone the text field rises with the virtual keyboard.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Visibility (bindable). The back button and Escape set it to false. |
| `title` | `string` |  | Header title and accessible name of the pane. |
| `onback` | `() => void` |  | Called after the back button or Escape closes the pane. |
| `children` | `Snippet` |  | Scrollable body. |
| `actions` | `Snippet` |  | Right side of the header. |
| `headerTitle` | `Snippet` |  | Replaces the title text in the header (for example avatar plus name). title stays as the accessible name. |
| `scroll` | `boolean` | true | false renders the body as a flex column without its own scroll, for layouts with a scrollable area and a fixed composer. |
| `class` | `string` | '' | Extra class names on the pane. |

---

# AppShell

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/app-shell/

Application layout with a module rail, a navigation panel, a mobile header and a bottom navigation, independent of any router.

```svelte
<script lang="ts">
  import { AppShellLayout, SiteHeader, type NavModule } from "@codeatlasdev/ui";
  import { goto } from "$app/navigation"; // or any router
  import { page } from "$app/state";

  let { children } = $props();

  const modules: NavModule[] = [/* id, label, icon, basePath, items */];
</script>

<AppShellLayout {modules} pathname={page.url.pathname} onNavigate={(path) => goto(path)}>
  {#snippet header()}<SiteHeader />{/snippet}
  {@render children()}
</AppShellLayout>
```

The shell never imports a router. You pass the current `pathname` and handle `onNavigate`, so it works with SvelteKit, Astro, or plain state. `onNavigate` fires when the user switches module from the rail or the bottom navigation. Panel items are plain `<a href>` links, so a client-side router takes them over like any other link. Put it only on application routes, never on marketing pages. The panel is skipped for a module with fewer than two destinations, since it would only repeat the rail icon and the page title. Below 900px the rail and panel disappear and the mobile header plus bottom navigation take over. See the [templates](/templates/) for complete applications built on it.

The rail magnifies the module icon under the pointer, like a dock. Only the glyph grows, never the button, so the hover background cannot cover the active neighbour. The effect follows the motion scale: it is off with `motion: { scale: 0 }` in the theme and under `prefers-reduced-motion`.

### Anatomy

Rail (52px), panel (200px by default) and the main content area.

### Live shell

The real component inside a fixed-height frame. The pathname lives in local state; click the rail and panel to navigate.

### Panel width

panelWidth={280} with resizablePanel: drag the edge or focus it and use the arrow keys.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `modules` | `NavModule[]` |  | Navigation modules. Each has id, label, icon, basePath, optional pathPrefixes and items (NavItem or NavSection). Prefixes match whole path segments and the longest one wins, so a module at `basePath: "/"` only gets the pages no other module claims. |
| `pathname` | `string` |  | Current location. Decides the active module and item. An item at `path: "/"` is active on `/` only. |
| `onNavigate` | `(path: string) => void` |  | Called with the first path of the module when the rail or the bottom navigation switches module. Panel items are links and do not call it. |
| `defaultModule` | `number` | 0 | Module index used when the URL matches no module and none was stored. |
| `persistPanel` | `boolean` | true | Keeps the shell across page loads: panel open or closed, selected module and expanded sections (localStorage), panel scroll (sessionStorage). Restored before the first paint. Turn it off for demos and embeds that must always start from the defaults. |
| `panelWidth` | `number` | 200 | Width of the navigation panel in px, for lists with long labels. Held between 160 and 480. The content offset and the open and close animation follow it, so nothing misaligns. Prefer it to overriding `--ca-panel-width`, which the layout does not read. |
| `resizablePanel` | `boolean` | false | Adds a drag handle on the panel's trailing edge. It is a keyboard-operable separator: Arrow keys move it by 8px, Shift by 32px, Home and End jump to the bounds. With `persistPanel` the chosen width is kept like the open state and restored before the first paint; `panelWidth` is the width used until the user picks one. |
| `reorder` | `Component` |  | Pass the exported `NavReorder` to enable `onReorder` on sections and modules. Opt-in so the drag engine is only bundled by apps that reorder. |
| `itemMenu` | `Component` |  | Pass the exported `NavItemMenu` to render `NavItem.actions` as a "…" menu. Opt-in so the dropdown menu is only bundled by apps that use it. |
| `header` | `Snippet` |  | Desktop header rendered above the page content. Hidden below 900px. |
| `brand` | `Snippet` |  | Logo shown at the top of the rail and in the mobile header. |
| `railBottom` | `Snippet` |  | Items pinned to the bottom of the rail, such as an avatar or notifications. |
| `mobileHeaderActions` | `Snippet` |  | Controls at the trailing edge of the mobile header. Use it for anything that must stay reachable below 900px. |
| `mobileTitle` | `Snippet` |  | Replaces the plain page title in the mobile header, for example a tappable title that opens a sheet. |
| `mainId` | `string \| null` | 'main' | `id` of the content region, which is the page `<main tabindex="-1">` landmark and the skip link target. Pass `null` when your page renders its own `<main id="main" tabindex="-1">`: the region becomes a plain `div`. |
| `skipLink` | `boolean` | true | Renders the SkipLink. Turn it off when the shell is embedded in a page that already has one. |
| `children` | `Snippet` |  | Page content. |

## Panel width

The panel is 200px by default. For lists with long names pass `panelWidth` (px, held between 160 and 480): the content offset and the open and close animation follow it, so the page never misaligns. Add `resizablePanel` to let people choose: a handle sits on the panel's trailing edge and is a keyboard-operable separator (`role="separator"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`). Arrow keys move it by 8px, Shift by 32px, Home and End jump to the bounds. While the pointer holds the edge the panel follows it with no spring in between. With `persistPanel` the width is stored with the open state and restored before the first paint; `panelWidth` is the width used until the user picks one. A stored width is ignored when `resizablePanel` is off, so the prop stays the contract.

## Rich panel items

A `NavItem` takes more than an icon and a label:

| Field | What it does |
|---|---|
| `color` | A decorative dot before the label, any CSS color. The icon stays. |
| `leading` | A snippet that replaces the icon (a color swatch, an avatar, an emoji). Decorative: the label is the name. |
| `count` | A neutral total after the label (`1.2k` above 999). The link's name carries the exact number, never "unread". `0` renders. |
| `badge` | Unread-style count: announced "N unread", capped at 99+. Use `count` for a plain total. |
| `actions` | A snippet of `DropdownMenuItem`s. The row gets a "…" button named `Actions for <label>`, a sibling of the link, shown on hover and focus. Needs `itemMenu={NavItemMenu}` on the shell. |

Reordering is per list: set `onReorder` on a `NavSection` (or on the `NavModule` for the items that sit outside any section) and pass `reorder={NavReorder}` to `AppShellLayout`. Each row gets a grip that works with the mouse, touch (press and hold) and the keyboard (Space lifts, arrows move, Enter drops, Escape cancels), and every step is announced. It is the same `useDnd` engine as [drag and drop](/docs/foundation/drag-and-drop/). The shell never reorders `items` for you: commit the move in your state and the new order flows back in. `onReorder` is not called when the drop lands where it started.

`NavReorder` and `NavItemMenu` are opt-in on purpose: the drag engine and the dropdown menu are only bundled by apps that import them, so a shell without per-item menus or reordering stays small.

```svelte
<script lang="ts">
  import { AppShellLayout, DropdownMenuItem, NavItemMenu, NavReorder, type NavModule, type NavReorderEvent } from "@codeatlasdev/ui";

  type Row = { id: string; name: string; color: string; count: number };
  let rows = $state<Row[]>([]);
  function archive() {}

  function reorder(e: NavReorderEvent) {
    const next = rows.slice();
    next.splice(e.to, 0, ...next.splice(e.from, 1));
    rows = next;
  }
</script>

{#snippet menu()}
  <DropdownMenuItem onclick={archive}>{#snippet children()}Archive{/snippet}</DropdownMenuItem>
{/snippet}

<!-- items: rows.map((r) => ({ id: r.id, label: r.name, icon: Folder, path: `/p/${r.id}`, color: r.color, count: r.count, actions: menu })) -->
<!-- <AppShellLayout {modules} {pathname} reorder={NavReorder} itemMenu={NavItemMenu}> -->
```

### Color, count, actions and reorder

Each row has a color dot, a neutral count and a … menu; drag a row by its grip.

## State across page loads

On a multi-page site (Astro, a full reload) every link loads a new document, so a shell that only keeps state in memory reopens at its defaults: the panel, the module, the expanded groups and the panel scroll are all lost. With `persistPanel` (the default) the shell keeps them and puts them back before the first paint, the same way the theme script does.

| What | Where | Key |
|---|---|---|
| Panel open or closed, selected module, dragged panel width, section open map | `localStorage` | `ca-shell` |
| Panel scroll, per module | `sessionStorage` | `ca-shell-scroll` |

An inline script emitted right after the sidebar reads those keys and sets `data-ca-panel="open|closed"` and `data-ca-module="<id>"` on `<html>` before anything paints, so a panel the user closed is laid out closed from the first frame instead of flashing open. Stored values are validated and discarded when malformed. A section's last open or closed choice wins over `defaultOpen`, but the section that holds the current page always opens. The module comes from the URL when `modules` matches it, and from the stored choice otherwise.

Render the shell on the server so the first paint is not blank: the inline script and the markup travel together. A client-only mount gets the same restore on hydration, and a page whose CSP blocks inline scripts too. Keep `id` stable on each `NavModule` (it is the stored module key) and each section `label` unique within a module (it is the stored section key).

## Building blocks for a custom panel

`AppShellLayout` renders the panel for you. `Rail`, `Panel`, `BottomNav` and `MobileHeader` are exported too, and two of them are the pieces to reuse when you lay out your own navigation: `PanelNavItem` is the row the panel draws for one `NavItem` (icon or `leading`, `color` dot, label, `count`, unread badge, new dot, the `actions` menu and the active pip), and `SectionGroup` is a titled group of items that collapses.

```svelte
<script lang="ts">
  import { PanelNavItem, SectionGroup, type NavSection } from "@codeatlasdev/ui";

  const section: NavSection = { label: "Reports", collapsible: true, items };
</script>

<SectionGroup {section} {pathname} />
<PanelNavItem item={items[0]} isActive={pathname === items[0].path} href={items[0].path} />
```

`PanelNavItem` renders a row with a plain `<a>` inside it (`aria-current="page"` when active); the actions button and the grip are siblings of the link, because a link cannot contain controls. `SectionGroup` opens itself when it holds the current page, and inside an `AppShellLayout` with `persistPanel` it stores its open state under the section `label`; a bare `SectionGroup` keeps nothing.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `item` | `NavItem` |  | The destination: `id`, `label`, `icon`, `path`, and optional `badge`, `count`, `color`, `leading`, `actions`, `isNew`, `shortcut`, `description`. Required. |
| `isActive` | `boolean` |  | Marks the row as the current page (`aria-current="page"`, active pip). Required. |
| `href` | `string` |  | Link target. Required. |
| `grip` | `boolean` | false | Adds the drag grip. Set it when the list the row sits in is reorderable (`NavSection.onReorder`). |
| `describedby` | `string` |  | `id` of the node that describes the keyboard drag (`dnd.instructionsId`), set on the grip. |
| `class` | `string` | '' | Extra class names. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `section` | `NavSection` |  | `label`, `items`, and optional `collapsible` (default `true`), `defaultOpen` (default `true`) and `onReorder` (makes the items reorderable). Required. |
| `pathname` | `string` |  | Current location, used to mark the active item and to keep the group holding it open. Required. |
| `class` | `string` | '' | Extra class names. |

---

# PageShell

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/page-shell/

The standard page container with a title, a description and an actions slot.

```svelte
<script>
  import { PageShell, Button } from "@codeatlasdev/ui";
</script>

<PageShell title="Dashboard" description="Overview of this month">
  {#snippet actions()}<Button size="sm">New report</Button>{/snippet}
  <!-- page content -->
</PageShell>
```

Below 900px the header stacks: the description leads and `actions` wrap onto their own row. Labeled buttons share that row full-width (large tap targets); icon-only controls (`IconButton`, `ThemeToggle`) keep their natural size and stay at the end of the row.

The shell renders `title` as the page `<h1>`; below 900px inside an `AppShellLayout` it is hidden visually because the mobile header already shows it. Inside a `PageShell`, `AppSettings` or `AppForm`, `EmptyState` and `FormSection` titles default to `<h2>` (under the page `<h1>`). Pass `headingLevel` to `EmptyState`, `FormSection` or `Card` to pick the level explicitly.

### Dashboard page

KPI cards and a content card inside a PageShell.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Page title. |
| `description` | `string` |  | Supporting text under the title. |
| `gap` | `number` | undefined | Vertical gap between the header and the content, in px. Omit for `--ca-space-7` (28px at the default density). |
| `maxWidth` | `string` | undefined | Maximum width of the content column, any CSS length. Omit for 80rem (1280px at the default 4px spacing unit). |
| `actions` | `Snippet` |  | Right side of the page header. |
| `children` | `Snippet` |  | Page content. |
| `class` | `string` | '' | Extra class names. |

---

# Page layouts

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/list-page/

Ready-made page layouts for lists, forms, settings and dashboards, built from AppList, AppForm, AppSettings and PageShell.

```svelte
<script>
  import { AppList, AppForm, AppSettings, PageShell } from "@codeatlasdev/ui";
</script>
```

These layouts fill the content area of the [app shell](/docs/layout/app-shell/) and manage their own scrolling, so give them a parent with a fixed or flexible height. AppForm has its own page, see [AppForm](/docs/layout/form-page/).

### AppList

Pass data and the layout handles search, filters and pagination.

### AppSettings

Side navigation plus content. The active tab is managed internally.

### PageShell

A scrollable container for dashboards and non-CRUD pages.

### AppList props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Page title. |
| `description` | `string` |  | Subtitle. Derived from the list count when omitted in data mode. |
| `data` | `T[]` |  | Full dataset. When set, AppList manages search, filters and pagination. |
| `searchKeys` | `(keyof T)[]` |  | Fields included in text search. Defaults to all string fields. |
| `perPage` | `number` | 20 | Rows per page. |
| `idKey` | `keyof T` | 'id' | Row identifier field. |
| `searchPlaceholder` | `string` |  | Placeholder of the search input. |
| `ofLabel` | `string` | 'of' | Word between the numbers in the count and page info. |
| `filters` | `Snippet<[ListCtx]>` |  | Extra filter controls after the search input. |
| `children` | `Snippet<[ListCtx]> \| Snippet` |  | Table or grid content. Receives the list context in data mode. |
| `actions` | `Snippet` |  | Top-right slot for the primary action. |
| `toolbar` | `Snippet` |  | Manual toolbar, used only without data. |
| `empty` | `Snippet<[ListCtx]> \| Snippet` |  | Shown when filtered rows are zero. |
| `footer` | `Snippet` |  | Manual footer, used only without data. |
| `maxWidth` | `string` |  | Maximum width of the content. |
| `class` | `string` | '' | Extra class names. |

### AppSettings props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Page title. |
| `description` | `string` |  | Subtitle. |
| `tabs` | `{ value, label, icon?, badge?, danger? }[]` |  | Side navigation entries. |
| `defaultTab` | `string` |  | Initial tab. Defaults to the first. |
| `activeTab` | `string` |  | Bindable active tab for external control. |
| `onTabChange` | `(value: string) => void` |  | Called when the tab changes. |
| `actions` | `Snippet` |  | Top-right slot for save and cancel buttons. |
| `children` | `Snippet<[string]>` |  | Content. Receives the active tab value. |
| `class` | `string` | '' | Extra class names. |

---

# KpiCard

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/kpi-card/

A metric card with a title, a value, an optional unit, a trend and an icon.

```svelte
<script>
  import { KpiCard } from "@codeatlasdev/ui";
  import { DollarSign } from "@lucide/svelte";
</script>

<KpiCard title="Monthly Revenue" value="$48,200" trend={12.4} icon={DollarSign} />
```

Put several cards in a [KpiGrid](/docs/layout/kpi-grid/) so a row never ends on an empty cell.

### Basic metrics

### Without trend

Omit trend and the indicator disappears.

### Negative trend

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Metric name. |
| `value` | `string \| number` |  | Main value. |
| `unit` | `string` |  | Unit shown after the value (%, s, users). |
| `trend` | `number` |  | Percentage change. Positive is green, negative is red, zero is neutral. |
| `icon` | `IconComponent` |  | Lucide icon. Size and color are managed by the card. |
| `skeleton` | `boolean` | false | Loading placeholder with the exact size of the loaded card. See Skeleton. |
| `class` | `string` | '' | Extra class names. |

---

# KpiGrid

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/kpi-grid/

A responsive row of KpiCards that never leaves an empty cell, whatever the count.

```svelte
<script>
  import { KpiCard, KpiGrid } from "@codeatlasdev/ui";
</script>

<KpiGrid>
  <KpiCard title="Revenue" value="$112k" />
  <KpiCard title="Users" value="24.8k" />
  <KpiCard title="Orders" value="1.4k" />
</KpiGrid>
```

`Grid cols="repeat(auto-fill, minmax(160px, 1fr))"` does not know how many cards it holds, so three cards on a 390px phone become two plus one with an empty cell. `KpiGrid` counts its children in CSS and only picks a column count that divides that number: three cards are three across when they fit and a single column when they do not, four cards are four across, then 2 x 2, then one column. It reacts to its own width, not the viewport, so it behaves the same in a sidebar layout or a narrow card, and it needs no JavaScript, so server-rendered pages are correct from the first paint.

| Cards | 344px | 528px | 712px | 896px | 1080px |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 1 | 1 | 1 |
| 2 | 2 | 2 | 2 | 2 | 2 |
| 3 | 1 + 1 + 1 | 3 | 3 | 3 | 3 |
| 4 | 2 + 2 | 2 + 2 | 4 | 4 | 4 |
| 5 | 1 per row | 1 per row | 1 per row | 5 | 5 |
| 6 | 2 + 2 + 2 | 3 + 3 | 3 + 3 | 3 + 3 | 6 |

Widths are the grid's own width (it uses a container query), which is smaller than the viewport inside a shell with a sidebar. A 390px phone with the usual page padding is the 344px column.

Tiles are at least 10rem wide. Above 12 children there is no useful even split, so the grid falls back to `auto-fill` and may end on a partial row: use several `KpiGrid`s in that case. Odd prime counts (5, 7, 11) stack to one column below the width that fits them all, because no smaller column count divides them evenly.

### Three cards

One row when it fits, one column on a phone, never 2 + 1.

### Four cards

Four across, then 2 x 2, then one column.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `gap` | `number \| string` | var(--ca-space-3) | Gap between cards. A number is pixels. |
| `class` | `string` | '' | Extra class names on the wrapper. |
| `children` | `Snippet` |  | The KpiCards (or any equal-weight tiles). |

---

# RecordList

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/record-list/

Records as dense rows (identity, a few columns, a row menu) that re-flow to a compact two-line row on a phone.

```svelte
<script>
  import { RecordList, RecordRow, RecordCell } from "@codeatlasdev/ui";
</script>

<RecordList columns="minmax(0,1.2fr) minmax(0,1.6fr) 5rem 2.75rem" labels={["App", "Scopes", "Installs"]} aria-label="Apps">
  {#each apps as app (app.id)}
    <RecordRow>
      {#snippet identity()}{app.name}{/snippet}
      <RecordCell label="Scopes">{app.scopes}</RecordCell>
      <RecordCell label="Installs">{app.installs}</RecordCell>
      {#snippet actions()}<DropdownMenu>…</DropdownMenu>{/snippet}
    </RecordRow>
  {/each}
</RecordList>
```

The usual dashboard list is neither a table nor a card per record. `Table` with `responsive="cards"` makes each row three or four times taller on a phone, and a `Card` per record repeats the chrome. `RecordList` owns what every app hand-rolls around that shape: the flush container, the separators, one column template shared by the header and every row, the re-flow below a width, and a 44px actions cell.

`columns` is one `grid-template-columns` value: the identity first, one track per `RecordCell`, the actions track last. `labels` are the column headers of the identity and the cells. A row without `actions` simply leaves the last track out of `columns`.

## Wide and stacked

Wide, the header is an `aria-hidden` row and every `RecordCell` keeps its `label` as a visually hidden `dt`, so assistive technology still gets "Scopes: read:invoices" per cell. Below 36rem of the **list's own width** (a container query, not the viewport) the header disappears and the row becomes two lines: identity and actions on the first, the cells below as small label/value pairs that wrap. The same list behaves the same in a narrow card or beside a sidebar, and it needs no JavaScript, so server-rendered pages are correct from the first paint.

With no rows, render your own [empty state](/docs/layout/empty-state/) instead of the list.

### Apps

Identity with avatar, status chip and a row menu. Narrow the window or the container to see it stack.

### Phone width

A 344px slot: the same list stacked, because the list reads its own width.

### Without a menu

No actions slot and no actions track: three columns that stack the same way.

## Accessibility

The list is a real `<ul>` with one `<li>` per record: give it an `aria-label`. Per-cell labels are `dt`/`dd` pairs inside a `dl`, so they are announced with their value in both layouts. Put an `aria-label` that names the record on every action button ("Actions for Billing"), because the visible column header is hidden from assistive technology.

### RecordList props

| Prop | Type | Default | Description |
|---|---|---|---|
| `columns` | `string` |  | `grid-template-columns` shared by the header and every row: identity, one track per cell, then actions. |
| `labels` | `string[]` |  | Column headers for the identity and each cell, in order. Omit for no header row. |
| `class` | `string` | '' | Extra class names on the wrapper. |
| `children` | `Snippet` |  | The RecordRows. |

### RecordRow props

| Prop | Type | Default | Description |
|---|---|---|---|
| `identity` | `Snippet` |  | First column: what the record is. Heads the stacked row. |
| `actions` | `Snippet` |  | Last column, usually a DropdownMenu. At least 44px square. |
| `class` | `string` | '' | Extra class names on the row. |
| `children` | `Snippet` |  | The RecordCells, in the order of the `columns` tracks. |

### RecordCell props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | The column name: kept for assistive technology on wide rows, painted above the value when stacked. |
| `class` | `string` | '' | Extra class names on the cell. |
| `children` | `Snippet` |  | The value. |

---

# AppForm

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/form-page/

A page-level form layout with a fixed header, a scrollable body and a sticky footer.

```svelte
<script>
  import { AppForm, FormSection, TextField, Button } from "@codeatlasdev/ui";
</script>

<AppForm title="New user" backHref="/users">
  <FormSection title="Account">
    <TextField label="Name" bind:value={name} />
  </FormSection>
  {#snippet footer()}
    <Button variant="ghost" href="/users">Cancel</Button>
    <Button variant="filled" onclick={save}>Save</Button>
  {/snippet}
</AppForm>
```

`FormSection` titles inside an AppForm are `<h2>` under the page `<h1>` (pass `headingLevel` on the section to override).

AppForm fills its parent, so give the parent a height. It replaces the removed FormPage. For a floating action bar inside your own scroll container, use [StickyActions](/docs/layout/sticky-actions/).

### Basic form

Header with a back button, a grid of fields, a list of switches and a sticky footer.

### Without header

Omit title, description, leading, trailing and backHref to drop the header.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Page title in the header. |
| `description` | `string` |  | Subtitle under the title. |
| `backHref` | `string` |  | Renders a back-arrow button linking here. Ignored when leading is provided. |
| `backLabel` | `string` | 'Back' | Accessible label of the automatic back button. |
| `leading` | `Snippet` |  | Left side of the header, such as a back button or breadcrumb. Overrides backHref. |
| `trailing` | `Snippet` |  | Right side of the header, such as a status chip or secondary actions. |
| `footer` | `Snippet` |  | Sticky bottom bar for cancel, save and delete buttons. |
| `children` | `Snippet` |  | Form body. Usually FormSection components. |
| `class` | `string` | '' | Extra class names. |

---

# EmptyState

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/empty-state/

A placeholder for empty views with an icon, a title, a description and actions.

```svelte
<script>
  import { EmptyState, Button } from "@codeatlasdev/ui";
  import { Inbox } from "@lucide/svelte";
</script>

<EmptyState icon={Inbox} title="No messages yet" description="New messages will appear here.">
  {#snippet actions()}<Button size="sm">Compose</Button>{/snippet}
</EmptyState>
```

### Basic

Icon, title, description and a primary action.

### No results

For searches and filters that match nothing.

### Error or offline

Failed network requests and loading errors.

### Hero

A larger, brand-tinted tile with a glow. On mobile the actions stack full width, so put the primary one first.

### No icon

A minimal version without an icon.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `icon` | `IconComponent` |  | Lucide icon. Size and color are managed by the component. |
| `title` | `string` |  | Main title. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | 2 inside PageShell/AppSettings/AppForm, 5 elsewhere | Heading level of the title. Only the tag changes; the look stays on `.ca-empty__title`. Keeps the outline valid under the page's `<h1>`. |
| `variant` | `'default' \| 'hero'` | 'default' | 'default' is a compact inline state. 'hero' adds a larger brand-tinted icon tile with a glow and bigger title. |
| `description` | `string` |  | Supporting text. |
| `actions` | `Snippet` |  | Call-to-action buttons. |
| `children` | `Snippet` |  | Extra content below the description. |
| `class` | `string` | '' | Extra class names. |

---

# ErrorPage

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/error-page/

A full-page error state for 404, 403, 500 and 503 with localized copy and home and back actions.

```svelte
<!-- src/routes/+error.svelte -->
<script>
  import { page } from "$app/state";
  import { ErrorPage } from "@codeatlasdev/ui";
</script>

<ErrorPage status={page.status} message={page.error?.message} />
```

Known statuses (404, 403, 500, 503) get an icon, a title and a hint in the active locale. Any other status falls back to a generic title. An explicit `message` replaces the hint and `title` replaces the title. The actions go back in history and to `/`. `caErrorPlugin({ scaffold: true })` writes a `+error.svelte` like this one for you (see [Installation](/docs/getting-started/installation/)).

### 404 without actions

hideActions removes the back and home buttons.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `status` | `number` | 500 | HTTP status shown as the large number. Picks the icon, title and hint for 404, 403, 500 and 503. |
| `message` | `string` |  | Replaces the preset hint under the title. |
| `title` | `string` |  | Replaces the preset title. |
| `hideActions` | `boolean` | false | Hides the back and home buttons. |
| `class` | `string` | '' | Extra classes on the root. |

---

# AuthLayout

Group: Layout. URL: https://ui.codeatlas.com.br/docs/layout/auth-layout/

A two-column page for sign in, sign up and password reset, with AuthCard for the form.

```svelte
<script>
  import { AuthLayout, AuthCard, TextField, Button, Stack } from "@codeatlasdev/ui";
</script>

<AuthLayout logoName="Acme">
  {#snippet panel()}
    <blockquote>Ship the boring parts in a day.</blockquote>
  {/snippet}

  <AuthCard title="Welcome back" subtitle="Sign in to continue">
    <form>
      <Stack gap="3">
        <TextField label="Email" type="email" />
        <Button type="submit" fullWidth>Sign in</Button>
      </Stack>
    </form>
    {#snippet footer()}
      <a href="/sign-up">Create an account</a>
    {/snippet}
  </AuthCard>
</AuthLayout>
```

`AuthLayout` renders the page `<main id="main">`, so a route that uses it must not add another one. The `panel` snippet fills the side column; below 768px it is hidden and `mobileBrand` shows a compact brand strip above the form. The full pages live in the [sign in, sign up and forgot password templates](/templates/).

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `logoMark` | `string` | 'CA' | Text inside the logo square. |
| `logoName` | `string` | 'CodeAtlas UI' | Product name next to the mark. |
| `logoHref` | `string` | '/' | Where the logo links to. |
| `mobileBrand` | `boolean` | true | Shows the compact brand strip below 768px, where the side panel is hidden. |
| `brand` | `Snippet` |  | Replaces the default logo. |
| `panel` | `Snippet` |  | Content of the side column. |
| `children` | `Snippet` |  | The form column, usually an AuthCard. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` |  | Heading of the card. |
| `subtitle` | `string` |  | Text under the heading. |
| `footer` | `Snippet` |  | Links under the form, such as sign up. |
| `children` | `Snippet` |  | The form. |

---

# Motion

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/

A vocabulary of named motion: live samples, exact timing, and a way to ask an AI for a motion by name or number.

Motion is hard to describe and easy to get wrong. "Make it fade in nicely" gives a different animation every time. This section gives every effect a **name**, a **number** and **exact values**, so a person can point at it and an AI can reproduce it without guessing.

## The vocabulary idea

Each motion demo is a real, running element with four things attached:

- **A name**: `Split text reveal`, `Fade rise`. The first name is canonical; the sidecar lists aliases, including other languages (`Subir com fade`).
- **A number**: the same `#NNN` as every other demo in the [gallery](/gallery/).
- **A spec**: the property, duration, easing, delay, stagger or spring. Each value appears verbatim in the demo source, and the build fails if one does not.
- **A way to ask**: one line for your AI.

## Ask an AI by name or number

Name it, or give the number. Both resolve to the same reference.

```text
Use @codeatlasdev/ui motion "Fade rise" on the invoice cards.
Use @codeatlasdev/ui demo #256 on the invoice cards.
```

With the MCP server, `search_demos({ query: "fade rise" })` matches names and aliases first, and `get_demo({ ids: ["#256"] })` returns the source, the `Motion:` lines and the instruction to reproduce the values exactly. Without MCP, fetch `/api/v1/en/p/256.txt`: it is the prompt, ready to paste.

## The contract every motion demo follows

It is implemented once, by [`MotionStage`](/docs/motion/motion-stage/), exported from `@codeatlasdev/ui`.

- **Plays in view.** A demo starts when at least half of it is visible and stops when it leaves the viewport or the tab is hidden. A gallery full of motion never animates everything at once.
- **You can take over.** Touching, clicking or focusing the demo stops the autoplay and makes it interactive. A **Replay** button appears.
- **You can pause.** A visible **Pause** button (`aria-pressed` when stopped) is always there while motion can run, so no motion lasts more than five seconds without a control (WCAG 2.2.2).
- **Reduced motion renders the final state.** Under `prefers-reduced-motion: reduce` nothing animates, the Pause and Replay buttons are not shown (there is nothing to stop), and the demo shows where the motion ends. Your code must do the same.

## Pages

---

# Basics

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/basics/

The smallest motion demos: one effect, one name, exact timing, wrapped in MotionStage.

Every motion demo is wrapped in [`MotionStage`](/docs/motion/motion-stage/): it plays only while it is in view, stops when you touch it, and shows its final state under `prefers-reduced-motion`. Read [Motion](/docs/motion/) for the contract.

### Fade rise

---

# MotionStage

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/motion-stage/

The frame of a motion demo: plays only in view, hands control to the user on touch, always pauses, and renders the final state under reduced motion.

```svelte
<script>
  import { MotionStage } from "@codeatlasdev/ui";
</script>

<MotionStage label="Fade rise: a card fades in while rising" loop={2400}>
  {#snippet children(m)}
    {#key m.cycle}
      <div class:rise={!m.reduced}>Invoice paid</div>
    {/key}
  {/snippet}
</MotionStage>
```

`MotionStage` owns the timing contract so a demo only has to draw. It starts when at least half of it is in view and stops when it leaves the viewport or the tab is hidden, so a page full of motion never animates everything at once. Pointer, key or focus inside the demo takes over: autoplay stops, the demo stays interactive and a **Replay** button appears. A **Pause** button (`aria-pressed` while stopped) is always there while motion can run (WCAG 2.2.2). Under `prefers-reduced-motion: reduce`, or in a theme with `motion: { enter: "none" }` (`--ca-enter-scale: 0`), nothing autoplays, the buttons are not rendered and `m.reduced` is `true`: render the final state.

The snippet receives `m` with `playing`, `reduced`, `cycle`, `takeover()`, `play()` and `pause()`. `cycle` increments on every loop and on Replay: key the animated element on it (`{#key m.cycle}`) so the animation runs again. Keep the animation in CSS and never start your own timers.

### Fade rise

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | Accessible name of the stage (the group label). Say what the demo shows. |
| `loop` | `number` | 3200 | Autoplay loop length in milliseconds. `cycle` increments once per loop. |
| `pauseLabel` | `string` |  | Label of the pause button. Defaults to the i18n catalog (`motionStage.pause`). |
| `replayLabel` | `string` |  | Label of the replay button. Defaults to the i18n catalog (`motionStage.replay`). |
| `children` | `Snippet<[MotionCtx]>` |  | The demo. Receives `{ playing, reduced, cycle, takeover, play, pause }`. |

---

# Hero and ambient

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/hero-ambient/

Cursor spotlight, grid ripple, gradient field, compare slider, cursor trail, hero intro and card tilt: named, numbered, with exact values.

The effects people ask for on a first screen: a light that follows the cursor, a surface that reacts to a click, a background that never sits still. Every one runs inside [`MotionStage`](/docs/motion/motion-stage/), so it plays only in view, stops when you touch it and shows its final state under `prefers-reduced-motion`. Ambient effects are decoration: keep them behind the content and never carry meaning in them.

### Cursor spotlight

### Grid ripple

### Animated gradient field

### Before and after slider

### Cursor trail

### Hero intro sequence

### Card tilt with glare

---

# Micro-interactions

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/micro-interactions/

Named micro-interactions with exact values: magnetic button, press spring, morphing toggle, like burst, hold to confirm, copy to check, add to cart fly.

A micro-interaction is the small reply an element gives to a touch: it leans, presses, flips, confirms. Each demo below plays itself while in view with a faint fake pointer (hidden from assistive tech), and the moment you touch it, it is yours: the real pointer or keyboard drives the same effect. Under reduced motion every demo shows its final state. Read [Motion](/docs/motion/) for the contract.

## Hover and pointer

### Magnetic button

### Tilt card

## Press and toggle

### Press spring

### Morphing toggle

### Spring switch

## Feedback

### Like burst

### Hold to confirm

### Copy to check

### Add to cart fly

---

# Text motion

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/text/

Named text effects with exact timing: split reveal, scramble, odometer, count up, marquee, typewriter, shine sweep and blur in.

Text is the cheapest place to add motion and the easiest to break: split words that a screen reader spells out, counters that announce every frame, tickers nobody can stop. Every demo here keeps the real sentence or number as the accessible name, hides the animated copy with `aria-hidden`, shows the final text under `prefers-reduced-motion`, and can be taken over by touching it. Ask an AI for one by name or by number: `Use #300` or `Use a split text reveal on the hero headline`.

## Reveal

### Split text reveal

### Blur in

## Transform and decode

### Text scramble

### Typewriter

## Numbers

### Odometer roll

### Count up

## Loops and highlights

### Infinite marquee

### Shine sweep

---

# Transitions

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/transitions/

Shared element, FLIP reorder, spring height, sliding tab indicator, stacked toasts, drag-to-dismiss sheet and filter exits: named, numbered, with exact values.

A transition is the motion between two states of the same screen. Each demo below wraps real package components (`Card`, `Tabs`, `Chip`, `Button`) and animates around them; none of them is forked. Every demo is wrapped in [`MotionStage`](/docs/motion/motion-stage/): it plays only in view, stops when you touch it, and shows the final state under `prefers-reduced-motion`.

## How to ask for one

Say the name, or the number. `Use #360 for the plan cards` and `Use a shared element transition from the plan list to its detail` resolve to the same reference, with the exact values.

### Shared element

### FLIP reorder

### Height spring

### Tab indicator

### Stacked toasts

### Sheet spring

### Filter list

---

# Scroll

Group: Motion. URL: https://ui.codeatlas.com.br/docs/motion/scroll/

Scroll-linked motion with names and exact values: staggered reveal, view-timeline reveal, parallax, reading progress, horizontal scroll, pinned steps and scroll-driven counters.

Scroll motion ties an effect to where the reader is on the page. Every demo below scrolls **inside its own container**, so it works in a card, a gallery tile or a modal, and the stage scrolls it for you while it is in view. Scroll it yourself (wheel, trackpad or touch) to take over; the Pause button stops the autoplay.

Where the browser supports **CSS scroll-driven animations** (`animation-timeline: scroll()` and `view()`), the effect runs on the compositor with no JavaScript. Where it does not, a passive `scroll` listener writes the same progress to a custom property and the same transforms read it. Under `prefers-reduced-motion` the container shows its final state and does not scroll by itself.

### Staggered reveal on scroll

### View timeline reveal

### Parallax

### Reading progress bar

### Horizontal scroll section

### Pinned step story

### Scroll-linked counter and chart draw

---

# Charts overview

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/

Apache ECharts wrapped by the design system. Pass data only; themes, animation and glass tooltips are automatic.

```svelte
<script>
  import { LineChart } from "@codeatlasdev/ui/charts";
</script>

<LineChart series={[{ name: "Revenue", data: [42, 58, 51, 74] }]} categories={["Jan", "Feb", "Mar", "Apr"]} />
```

Charts live in the `@codeatlasdev/ui/charts` subpath and need the optional peer dependency `echarts` (`bun add echarts`, version 6). Every chart takes data and a few semantic props. There is no style or font prop on purpose: the palette follows the active preset, axes, legend and tooltips read the `--ca-*` tokens, and charts re-theme when the color scheme, preset or surface style changes. Series can take an explicit `color`; use hex or rgb, because ECharts paints on a canvas and cannot parse `oklch()`. Charts render on the client, so hydrate them with `client:visible` in Astro.

|Component|Use for|
|---|---|
|[LineChart](/docs/charts/line/)|Trends over time, areas, live streams|
|[BarChart](/docs/charts/bar/)|Vertical, horizontal, stacked and grouped bars|
|[PieChart](/docs/charts/pie/)|Pie, donut and rose proportions|
|[ScatterChart](/docs/charts/scatter/)|Correlations and bubble sizing|
|[RadarChart](/docs/charts/radar/)|Multi-dimension profiles|
|[GaugeChart](/docs/charts/gauge/)|KPI gauges and progress rings|
|[HeatmapChart](/docs/charts/heatmap/)|Calendar and matrix density|
|[Sparkline](/docs/charts/sparklines/)|Inline micro charts|

All chart components also accept `height` (CSS length, each chart has its own default) and `class`.

### Dashboard

Every chart type together inside glass cards.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `height` | `string` |  | CSS height of the chart. Defaults differ per chart (320px for line, bar and scatter; 300px for pie; 340px for radar; 280px for gauge; 240px for heatmap; 48px for sparkline). |
| `class` | `string` | '' | Extra class names on the chart container. |

---

# LineChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/line/

Temporal trends, multi-series comparisons, gradient area fills and live data.

```svelte
<script>
  import { LineChart } from "@codeatlasdev/ui/charts";
</script>

<LineChart
  series={[{ name: "Revenue", data: revenue }]}
  categories={months}
  valueFormatter={(v) => `$${v / 1000}k`}
/>
```

### Simple line

### Multi-line comparison

Each series gets its own palette color.

### Area with gradient fill

area fills under each line with a gradient that fades to transparent.

### Real-time stream

Replace the data array and the chart updates in place.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `series` | `ChartSeries[]` |  | Named series sharing one category axis. Each is { name, data: number[], color? }. |
| `categories` | `string[]` |  | X-axis labels, one per data point. |
| `valueFormatter` | `(value: number) => string` |  | Formats y-axis ticks and tooltip values. |
| `area` | `boolean` | false | Fills the area under each line with a gradient. |
| `height` | `string` | '320px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# BarChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/bar/

Vertical, horizontal, stacked and grouped bars.

```svelte
<script>
  import { BarChart } from "@codeatlasdev/ui/charts";
</script>

<BarChart series={[{ name: "Revenue", data: [38400, 54200, 71600, 89800] }]} categories={["Q1", "Q2", "Q3", "Q4"]} />
```

Multiple series render grouped by default. Set `stacked` to stack them into one column per category.

### Vertical bars

### Horizontal bars

Good for long category names and rankings.

### Stacked bars

### Grouped and stacked

Toggling stacked animates between both layouts.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `series` | `ChartSeries[]` |  | Named series sharing one category axis. Each is { name, data: number[], color? }. |
| `categories` | `string[]` |  | Category labels, one per bar group. |
| `valueFormatter` | `(value: number) => string` |  | Formats value-axis ticks and tooltip values. |
| `horizontal` | `boolean` | false | Renders bars horizontally. |
| `stacked` | `boolean` | false | Stacks all series into one column per category. |
| `height` | `string` | '320px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# PieChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/pie/

Proportional data as pie, donut or Nightingale rose, with an optional center label.

```svelte
<script>
  import { PieChart } from "@codeatlasdev/ui/charts";
</script>

<PieChart data={[{ name: "Cloud", value: 38 }, { name: "SaaS", value: 24 }]} donut />
```

### Basic donut

### Donut with center KPI

centerLabel overlays a value and caption in the hole of a donut.

### Rose chart

Nightingale rose: the radius of each slice scales with its value.

### Animated proportions

Swap the data and the slices animate to the new proportions.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `ChartSlice[]` |  | Slices as { name, value }. |
| `donut` | `boolean` | false | Renders a ring instead of a solid pie. |
| `rose` | `boolean` | false | Nightingale rose, where the slice radius scales with the value. |
| `centerLabel` | `{ value: string; label: string }` |  | Text centered in a donut, such as a KPI total. Use with donut. |
| `height` | `string` | '300px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# ScatterChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/scatter/

Correlation plots, bubble charts and clustered scatter by group.

```svelte
<script>
  import { ScatterChart } from "@codeatlasdev/ui/charts";
</script>

<ScatterChart series={[{ name: "Accounts", data: [[1200, 3.4], [4800, 5.1]] }]} yName="Conversion %" />
```

Points are `[x, y]` or `[x, y, size]`. When any point has a third value the chart switches to bubble mode automatically and scales the symbols by size.

### Basic scatter

Visits against conversion rate.

### Bubble chart

The third value of each point sets the bubble size.

### Clustered by tier

One series per group, each with its own palette color.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `series` | `ScatterSeries[]` |  | Named series as { name, data: [x, y] \| [x, y, size][], color? }. |
| `xName` | `string` |  | Label of the x axis. |
| `yName` | `string` |  | Label of the y axis. |
| `xFormatter` | `(v: number) => string` |  | Formats x ticks and tooltip. Overrides valueFormatter for x. |
| `yFormatter` | `(v: number) => string` |  | Formats y ticks and tooltip. Overrides valueFormatter for y. |
| `valueFormatter` | `(v: number) => string` |  | Fallback formatter used for both axes. |
| `height` | `string` | '320px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# RadarChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/radar/

Multi-dimensional profiles from single skill sets to interactive comparisons.

```svelte
<script>
  import { RadarChart } from "@codeatlasdev/ui/charts";
</script>

<RadarChart
  indicators={[{ name: "Speed", max: 100 }, { name: "Quality", max: 100 }, { name: "Support", max: 100 }]}
  series={[{ name: "Team A", values: [88, 92, 94] }]}
/>
```

`values` must follow the order of `indicators`. A legend appears automatically when there is more than one series.

### Simple radar

### Comparison

Two series with a legend and focus on hover.

### Interactive team builder

Drag the sliders and the radar updates live.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `indicators` | `RadarIndicator[]` |  | Axes as { name, max }. |
| `series` | `RadarSeries[]` |  | Named series as { name, values: number[], color? }, aligned to indicators. |
| `height` | `string` | '340px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# GaugeChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/gauge/

KPI gauges, progress rings and animated counters.

```svelte
<script>
  import { GaugeChart } from "@codeatlasdev/ui/charts";
</script>

<GaugeChart value={78} label="Score" />
<GaugeChart value={65} variant="ring" />
```

The default gauge colors its arc in three zones (error, warning, success). Override them with `zones`, where `until` is a fraction of `min` to `max`.

### Simple gauge

### Progress ring

variant ring draws a single brand-colored arc with the value in the center.

### Custom zones

Reverse the default zones when a high value is bad, such as CPU load.

### Animated counter

Updating value animates the ring and counts the number.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` |  | Current value. |
| `min` | `number` | 0 | Lower bound of the scale. |
| `max` | `number` | 100 | Upper bound of the scale. |
| `variant` | `'default' \| 'ring'` | 'default' | 'default' is a speedometer arc with a pointer. 'ring' is a full progress ring. |
| `zones` | `GaugeZone[]` | error to 0.3, warning to 0.7, success to 1 | Colored arc zones as { until, color }. until is a fraction of min to max; color is success, warning, error, info, brand or any CSS color. |
| `label` | `string` |  | Caption shown above the value in the default variant. |
| `formatter` | `(value: number) => string` | v => `${v}%` | Formats the displayed value. |
| `animated` | `boolean` | true | Counts the displayed number up or down when value changes. The arc always animates. |
| `height` | `string` | '280px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# HeatmapChart

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/heatmap/

Density and pattern visualization as calendar grids and hour-by-day matrices.

```svelte
<script>
  import { HeatmapChart } from "@codeatlasdev/ui/charts";
</script>

<HeatmapChart variant="calendar" data={[["2026-03-01", 4]]} range={["2026-01-01", "2026-09-15"]} />
<HeatmapChart variant="matrix" matrixData={[[0, 0, 3]]} xCategories={hours} yCategories={days} />
```

`variant` is required. The calendar variant reads `data` and `range`; the matrix variant reads `matrixData`, `xCategories` and `yCategories`.

### Calendar heatmap

Daily commit activity from January to September.

### Hour by day matrix

Points are [xIndex, yIndex, value] into xCategories and yCategories.

### Year toggle

Swap data and range to move between years.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `'calendar' \| 'matrix'` |  | Which layout to render. Required. |
| `data` | `CalendarHeatmapPoint[]` | [] | Calendar variant: [date as YYYY-MM-DD, value] per day. |
| `range` | `[string, string]` |  | Calendar variant: first and last date shown. |
| `matrixData` | `MatrixHeatmapPoint[]` | [] | Matrix variant: [xIndex, yIndex, value]. |
| `xCategories` | `string[]` | [] | Matrix variant: x-axis labels. |
| `yCategories` | `string[]` | [] | Matrix variant: y-axis labels. |
| `color` | `string` |  | Hex or rgb color of the high end of the ramp. Defaults to the first palette color. Use hex or rgb, not oklch. |
| `max` | `number` |  | Value that maps to the full color. Defaults to the data maximum. |
| `tooltipFormatter` | `(value: number) => string` |  | Formats the value in the tooltip. |
| `height` | `string` | '240px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# Sparkline

Group: Charts. URL: https://ui.codeatlas.com.br/docs/charts/sparklines/

Inline micro charts for KPI cards, table rows and live streams.

```svelte
<script>
  import { Sparkline } from "@codeatlasdev/ui/charts";
</script>

<Sparkline data={[42, 51, 58, 63, 72]} trend="up" height="32px" />
```

A sparkline has no axes, legend or tooltip. `trend` picks the color: success for `up`, error for `down` and a neutral tone otherwise.

### KPI cards with trend lines

### Table row sparklines

### Bar sparklines

variant bar draws narrow columns instead of a line.

### Live streaming micro charts

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` | `number[]` |  | Values to plot. |
| `variant` | `'line' \| 'bar'` | 'line' | Line with a soft area, or narrow bars. |
| `trend` | `'up' \| 'down' \| 'neutral'` |  | Colors the series: success, error or neutral. |
| `color` | `string` |  | Explicit hex or rgb color. Overrides trend. Use hex or rgb, not oklch. |
| `height` | `string` | '48px' | CSS height of the chart. |
| `class` | `string` | '' | Extra class names. |

---

# Docs primitives

Group: Docs kit. URL: https://ui.codeatlas.com.br/docs/docs-kit/docs/

Components for developer documentation sites, from the page shell and navigation to code tabs, callouts and prose typography.

This site is built with these primitives. The kit covers `DocsShell` (header, sidebar, page index and a mobile Sheet menu), `DocsNav`, `TableOfContents`, `DocsSearch`, `CodeTabs`, `Callout`, `Steps`, `LinkCard`, `CardGrid`, `MethodBadge` and the `ca-prose` typography.

```svelte
<script>
  import { DocsShell } from "@codeatlasdev/ui";
</script>

<DocsShell
  {sections} active="guide" {groups} {pathname} {headings}
  searchIndex={() => fetch("/search.json").then((r) => r.json())}
  onnavigate={(href) => (location.href = href)}
>
  {#snippet brand()}<Logo /> Acme Docs{/snippet}
  <article class="ca-prose">...</article>
</DocsShell>
```

`DocsShell` is a full-page frame, so it is not embedded here. The page you are reading is the reference integration: see `SiteDocsShell.svelte` in the `site/` workspace. On desktop (1024px and up) it is a sticky glass header over a three-column grid: sidebar, content and a "On this page" rail from 1280px. Below 1024px it becomes one compact header, the menu opens a bottom Sheet and the page index turns into an inline disclosure. `Cmd+K`, `Ctrl+K` and `/` open the search.

The sidebar keeps its place between pages, also on a static site where every link loads a new document. Its scroll position is saved per section in `sessionStorage` and restored by a small inline script right after the sidebar, before the first paint. The current page is scrolled into the sidebar's view when it is outside it; the window scroll and focus are never touched. Under a Content Security Policy that blocks inline scripts, the position is restored on hydration instead.

### ca-prose, Callout and Steps

Wrap rendered markdown in .ca-prose. Callout is an Alert vocabulary (note, tip, caution, danger); keep two per page. Steps turns an ordered list into a numbered rail.

### CodeTabs

Language tabs with a copy button. Groups that share a sync key follow each other and persist the choice in localStorage. Highlighting stays with you: wrap each block in .ca-code.

### LinkCard, CardGrid and MethodBadge

### DocsNav and TableOfContents

The sidebar tree and the page index. The inline variant is shown; DocsShell uses the rail variant on desktop.

### DocsSearch

Full-text search. A dialog on desktop and a full-height sheet with a 16px input on phones. Pass entries or an async loader.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `sections` | `DocsSection[]` |  | { id, label, href } entries shown as header tabs and in the mobile Sheet. |
| `active` | `string` |  | id of the current section. |
| `groups` | `DocsNavGroup[]` | [] | Sidebar tree of the current section. Empty hides the sidebar and the page index. |
| `pathname` | `string` |  | Current path, used to mark aria-current in the tree. |
| `headings` | `DocsHeading[]` | [] | Page index: a rail from 1280px and an inline disclosure below. |
| `searchIndex` | `DocsSearchEntry[] \| () => Promise<DocsSearchEntry[]>` |  | Required. Entries, or a lazy loader called on first open. |
| `onnavigate` | `(href: string) => void` |  | Required. Called when a search result is picked (pass goto). |
| `brandHref` | `string` | '/' | Link target of the brand. |
| `brandLabel` | `string` |  | Accessible label of the brand link. |
| `brand` | `Snippet` |  | Required. Brand mark and name inside the header link. |
| `actions` | `Snippet` |  | Extra header actions on the right. Keep to one or two icon buttons. |
| `menuFooter` | `Snippet` |  | Content below the sidebar tree in the mobile Sheet, such as external links. |
| `pager` | `{ prev?: DocsPagerLink; next?: DocsPagerLink }` |  | Previous and next pages, as { href, title }. Cards at the end of the article on wide screens, a fixed bottom action bar on narrow ones. |
| `children` | `Snippet` |  | Required. Page content. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `groups` | `DocsNavGroup[]` |  | Groups of { label?, items } where an item is { href, title, badge? }. A badge is an HTTP method shown as a MethodBadge. |
| `pathname` | `string` |  | Current path, marks the current page with aria-current. |
| `label` | `string` |  | Accessible label of the nav landmark. |
| `onNavigate` | `() => void` |  | Called after a link is followed, to close the mobile Sheet. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `headings` | `DocsHeading[]` |  | { id, text, depth: 2 \| 3 } entries. Renders nothing for fewer than 2 headings. |
| `variant` | `'rail' \| 'inline'` | 'rail' | A sticky list, or a collapsible disclosure that shows the current section. |
| `label` | `string` |  | Accessible label of the nav landmark. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `index` | `DocsSearchEntry[] \| () => Promise<DocsSearchEntry[]>` |  | Required. Entries, or a loader called once on first open. |
| `onselect` | `(href: string) => void` |  | Required. Called with the picked result's href. |
| `placeholder` | `string` |  | Input placeholder. Defaults to the localized string. |
| `hint` | `string` |  | Footer hint text. Defaults to the localized string. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `CodeTabs.sync` | `string` | 'lang' | Groups with the same key follow the chosen label. An empty string disables sync. |
| `CodeTabs.tabs` | `{ label: string; code?: string; html?: string }[]` |  | Tabs as data instead of CodeTab children, for Astro and MDX pages where each island is its own Svelte tree. `html` is pre-highlighted markup. |
| `CodeTab.label` | `string` |  | Tab text and sync key, for example 'cURL' or 'Node.js'. |
| `Callout.type` | `'note' \| 'tip' \| 'caution' \| 'danger'` | 'note' | Maps to Alert severity (info, success, warning, error). |
| `Callout.title` | `string` |  | Overrides the default localized title. |
| `Steps` | `Snippet` |  | Wraps an ordered list; each top-level item becomes a numbered step. |
| `LinkCard.title / description / href` | `string` |  | Whole-card link. title and href are required; the minimum height is 44px. |
| `CardGrid` | `Snippet` |  | Responsive auto-fill grid for LinkCard: 16rem minimum, one column on phones. |
| `MethodBadge.method` | `string` |  | HTTP method label: GET, POST, PUT, PATCH or DELETE. |
| `MethodBadge.variant` | `'pill' \| 'plain'` | 'pill' | plain drops the tinted pill, for tight lists like a sidebar. |

---

# Release lists

Group: Docs kit. URL: https://ui.codeatlas.com.br/docs/docs-kit/release-lists/

The markup contract for changelog and release-notes pages inside .ca-prose, and how the heading anchors and the version index are linked.

`.ca-prose` styles a changelog page with no custom CSS, as long as the markup follows the contract below. The package ships only the CSS: it never generates the ids, the anchors or the version index. Your app (its markdown pipeline or its template) renders them. The [changelog page](/changelog/) of this site is the reference: `site/functions/_lib/page.ts` builds exactly this markup.

## Markup

```html
<div class="ca-prose">
  <nav class="ca-release-jump" aria-label="Versions">
    <ul>
      <li><a href="#v3-0-0">3.0.0</a></li>
      <li><a href="#v2-4-0-beta-1">2.4.0-beta.1</a></li>
    </ul>
  </nav>

  <section class="ca-release" id="v3-0-0" aria-labelledby="v3-0-0-h">
    <h2 id="v3-0-0-h">
      <a href="#v3-0-0">3.0.0</a>
      <span class="ca-chip ca-chip--sm ca-chip--brand"><span class="ca-chip__label">latest</span></span>
    </h2>
    <p class="ca-release__meta">
      <time datetime="2026-10-15">October 15, 2026</time>
      <a href="https://www.npmjs.com/package/@codeatlasdev/ui/v/3.0.0">npm</a>
      <a href="https://github.com/codeatlasdev/ui/releases/tag/%40codeatlasdev%2Fui%403.0.0">GitHub release</a>
    </p>
    <h3 id="v3-0-0-minor-changes">Minor Changes</h3>
    <ul><li>The rendered notes.</li></ul>
  </section>

  <footer class="ca-release-thanks">
    <h2 id="special-thanks">Special thanks</h2>
    <p>To our supporters.</p>
  </footer>
</div>
```

| Class | Element | Role |
|---|---|---|
| `ca-release` | `<section>` | One per version, newest first. Draws the rule between versions and sets `scroll-margin-top` so a jump lands clear of the sticky header (`--ca-docs-header-h`). |
| `ca-release-jump` | `<nav>` | The version index as a wrapping row of pills. Holds a `<ul>` of links; each pill is a 44px touch target. |
| `ca-release__meta` | `<p>` | Row under the heading: a `<time>`, then links (npm, GitHub release). Wraps on small screens; links are 44px tall. |
| `ca-release-thanks` | `<footer>` | Closes the page, set apart from the last release by a rule. |

The channel badge in the heading is a regular [Chip](/docs/display/chip/) (`ca-chip--sm`). The package only styles `h2 > a` inside a release (inherits the heading color, underline on hover); the chip, the date and the links are yours.

## Anchors

Two kinds of anchors exist on a release page, and both are generated by the app:

- **Version id.** The `id` of each `ca-release` section, the `href` of its heading link and the `href` of its pill in `ca-release-jump` must be the same string. The convention used by this site: `v` plus the version with every run of non-alphanumeric characters replaced by `-`, so `3.0.0` is `#v3-0-0` and `2.4.0-beta.1` is `#v2-4-0-beta-1`. If your versions are dates (`2026-10-14 (1.1.0)`), pick your own slug and use the same function for the pill and the section. Nothing in the package computes it.
- **Heading ids inside the notes.** Slugify the heading text (lowercase, non-alphanumerics to `-`, trim dashes) and prefix it with the version id, so two `### Patch Changes` in different versions never collide: `v3-0-0-patch-changes`. Repeat headings inside one version get `-2`, `-3`.

Give the section `aria-labelledby` pointing at its heading id (`<version id>-h`) so the landmark has an accessible name. Do not give the heading the same id as the section: ids must be unique per page.

## Heading anchor link

`.ca-prose` styles an optional `<a class="ca-prose-anchor" href="#id">#</a>` placed first inside an `h2`, `h3` or `h4`. It sits in the left margin, appears on heading hover and on focus, and stays visible on touch screens (`hover: none`), where there is no hover to reveal it. You inject it, the package does not.

Inside `ca-release`, the `h2` is a flex row and its link is the version itself, so skip `ca-prose-anchor` there and let the version link carry the anchor.

---

Agent guide: AGENTS.md from https://github.com/codeatlasdev/ui/blob/main/AGENTS.md

# AGENTS.md: Guide for AI Agents

This document covers everything an AI agent needs to know to work in this repository.

---

## What this project is

`@codeatlasdev/ui` is CodeAtlas's UI package. It is a Svelte 5 library published publicly on npm. Every company frontend imports components, tokens and styles from here.

---

## Monorepo structure

```
packages/ui/          → publishable library (@codeatlasdev/ui)
  bin/                → CLIs: codeatlas-ui (init, migrate) and ca-ui-mcp (MCP server)
  scripts/            → build-manifest.ts (components/tokens/guides.json), build-bin.ts, build-themes.ts
  src/cli/            → init and migrate logic (tested in tests/cli.test.ts)
  src/lib/
    components/       → Svelte 5 components
    styles/           → CSS: global.css (everything), core.css (no extra presets), presets/*.css, base.css, tokens.css, materials.css
    tokens/           → TypeScript constants (colors, typography, shadows, etc.)
    stores/           → reactive svelte $state (colorScheme, responsive, reducedMotion)
    utils/            → debounce, clipboard, localStorage, palette-generator
    index.ts          → main barrel export
site/                 → Astro site (landing + MDX docs + templates) at ui.codeatlas.com.br
  functions/          → Cloudflare Pages Functions: /changelog/ (live GitHub Releases), /changelog.json, /changelog/feed.xml; tested with `bun run test:unit`
```

---

## Issue workflow (agents and humans)

- **Claim before coding:** `bun run issue:start <n>` creates `../ui-worktrees/<n>-<slug>` on `fix|feat/<n>-<slug>`, opens a draft PR (`Closes #<n>`), labels `in progress`, assigns and comments on the issue. Parallel agents each take their own issue and worktree; never share a checkout.
- **Stay in the worktree:** use absolute paths under `../ui-worktrees/<n>-<slug>/` for every read, edit and command (`cwd`). A relative path resolves against the main checkout and silently edits `main`. Never `git stash` (the stash is shared by all worktrees).
- **Contributor PRs come first:** if an issue already has an open PR (a fork included), `issue:start` refuses and names it. Review it, approve its CI run (first-time contributors need approval), suggest changes on the PR, and land theirs. Never open a competing PR, and never push to a contributor's branch without saying so on the PR.
- **Triage before a batch ("fix all issues"):** never start coding first. (1) `bun run issue:triage` creates the labels and writes every open issue with comments, linked PRs and the commits on `main` that close it (closing keyword or `(#issue) (#pr)` subject; a bare `(#n)` is a PR number) to `.cache/triage.md`. (2) Read all of them and check each against current `main` source (issues usually quote an older `dist/`). (3) Already fixed: prove it as in **Check first** (a passing test on `main`), comment the evidence and close (`gh issue close <n> --reason completed`); duplicate: close as `duplicate` pointing to the survivor; not planned: `not planned` with the reason. (4) Every remaining issue gets exactly one type (`bug` / `enhancement` / `documentation`) and one or more `area:*` labels. (5) Link related issues with a comment `Related: #a, #b (same file/root cause)` on each side; when one must land first, label `blocked` and comment `Blocked by #n`. (6) Order the work: blockers, then bugs, then enhancements and docs; fix issues sharing a file in the same worktree sequence, never in parallel worktrees. Tooling edits go through a worktree and PR too, never on the main checkout.
- **Check first:** `bun run issue:status`. Skip issues labeled `in progress` by someone else. Re-read the issue against current `main`: if it is already fixed, prove it with a passing test, comment the evidence and close it.
- **Test first** (critical rule 0): failing regression test, then the fix, then the passing run. Both outputs go in the PR body. A test you did not run proves nothing: run every test you add or change (Playwright included) before pushing.
- **CI is paused** (pre-stable): `ci.yml` is disabled and `CI ok` is not required on `main`; the pre-push `validate` is the gate, and run the browser suites locally when you touch them. Resume: `gh workflow enable ci.yml` + re-add `CI ok` to the `main` ruleset.
- **Gates are real:** never push with `--no-verify` or `LEFTHOOK=0`. A gate that fails only under load is a bug to fix (#73 was exponential regex backtracking; #75, #76, #81 were real races), not to bypass. Open an issue for it.
- **Done:** `bun run validate`, changeset when the package changes, docs when behavior changes; leave the PR as draft. A maintainer lands it with `sh scripts/issue-land.sh <n>`: rebase on `main` (generated files are rebuilt, real conflicts stop it), validate, regenerate visual baselines on CI, wait until every check on the final head passed (`scripts/pr-gate.ts`), squash-merge, `issue:done`.

---

## Tests

Unit tests run on `bun test` (repo root, `bunfig.toml`); component and visual tests need a real Chromium and stay on Vitest. Use `bun run test` (everything) or the scripts below. A bare `bun test` at the root runs only the unit tests.

| Command | What it runs |
|---|---|
| `bun run test` | unit + browser + fixtures + E2E |
| `bun run test:unit` | `bun test` on `packages/ui/tests/*.test.ts` (fails any test without an `expect`) |
| `bun run test:browser` | Vitest `browser` project (real Chromium, axe) |
| `bun run test:fixtures` | `packages/ui/tests/*.e2e.ts`: builds a real fixture app (Astro, Kit) and drives it in Chromium (e.g. `caUI` + `<ClientRouter />`). Never name these `*.test.ts`: the unit suite runs in `validate` and in the release job, which have no browsers (`tests/unit-suite.test.ts` guards it) |
| `bun run test:e2e` / `test:a11y` | Playwright against the static site (build + preview) |
| `bun run lighthouse` | Lighthouse (SEO and accessibility must be 100, performance floor) plus the installability contract (standalone manifest with `id`, 192/512/maskable icons, `twitter:title`, `og:image`, `lang`) on the built site served locally, offline. Not in `validate`: it needs a production build and a Chrome, is CPU-heavy and its performance score moves with machine load, which AGENTS.md forbids as a gate. Run it when you touch SEO, the manifest, `<Seo>` or `init` output; `E2E_PREBUILT=1` skips the build |
| `bun run test:vrt:update` | regenerate baselines on CI (the only place they are rendered, no Docker) for the pushed branch and pull the bot commit |
| `bun run test:status` | live and dead test runs of this repo, with their browser count |
| `bun run test:reap` | kill the browsers of runs whose runner died (this repo only) |

**Never call `vitest` / `playwright test` directly for browser tests: always go through the scripts above.** They run under `scripts/test-run.ts`, which:
- records each run in `.cache/test-runs/<id>.json` and tags every browser it starts with `--ca-test-run=<id>`;
- tears down the whole test process group on exit, Ctrl+C, SIGTERM or SIGHUP;
- at the start of every run, kills browsers left by runs whose runner died (SIGKILL, closed terminal, killed agent job).

Ownership is explicit: only processes carrying the tag of a dead run of this repo are touched. Other projects on the machine (`../ac`, …) share `~/Library/Caches/ms-playwright`; never kill Playwright browsers by name or path. To pass extra args: `bun run test:browser -- src/lib/components/Button`. Local runs use a quarter of the cores (`maxWorkers`, Playwright `workers: "25%"`); behavior tests use the headless shell, VRT uses full Chromium so pixels match the CI baselines.

Naming conventions:
- `*.test.ts` in `packages/ui/tests/`: unit test on `bun:test` (`mock`/`spyOn`/`jest.useFakeTimers`; DOM only through happy-dom's `GlobalRegistrator` inside that file; fresh module via `import("…?fresh=n")`). Types checked by `bun --check`.
- `*.svelte.test.ts`: component in the browser, next to the component.
- `*.vrt.test.ts`: per-component screenshot; matrix harness `NameMatrix.test.svelte`.
- `*.test.svelte`: harness for snippets/`bind:` (not shipped in `dist`).
- `site/tests/*.spec.ts` (desktop+mobile+iphone), `*.a11y.spec.ts`, `*.visual.spec.ts`.
- Keep test titles short: `describe` + `it` combined at most ~80 characters. Vitest names the trace attachment with path + title + hash, and names over 255 bytes fail with `ENAMETOOLONG`, losing the trace exactly when the test fails.

Rule: every new component needs a `.svelte.test.ts` with `expect(await checkA11y(screen.container)).toHaveNoViolations()` in each state (open/closed). `render` from `vitest-browser-svelte` is async. `a11y_*` warnings are errors: `bun run check` uses `--fail-on-warnings` and the site build fails via `onwarn` (`site/svelte.config.js`). (`svelte-package` does not compile `.svelte`, so in the package it is `check` that blocks.)

Accessibility rules (package and apps):
- A page has exactly one `<main>` and one `id="main"`. `DocsShell` and `AuthLayout` already provide them; `AppShellLayout` renders `<main id="main" tabindex="-1" class="ca-shell__content">` as the `SkipLink` target (pass `mainId={null}` if the page renders its own `<main id="main" tabindex="-1">`: the region becomes a plain `div`, and `skipLink={false}` when embedding the shell in a page that already has a skip link). `PageShell` never emits `<main>`.
- Screen reader announcements go through `announce(msg, politeness)` (one shared live region); do not create a new local `role="status"`. In SvelteKit, mount `RouteAnnouncer` (`@codeatlasdev/ui/kit`) once in the root layout.
- An `aria-label` on a button must contain the visible text (WCAG 2.5.3); compose with `aria-labelledby` as `Combobox` does with `ariaLabel`.
- New surface CSS with glass/shadow/`border: none` needs an entry in the `@media (forced-colors: active)` block of `materials.css` (`CanvasText` border). Contrast tokens (`prefers-contrast: more`) come from `themeCSS`/`presetCSS`; `tests/contrast.test.ts` measures 7:1 for text and 3:1 for outlines in every preset.
- `site/tests/routes.a11y.spec.ts` runs axe in dark, light and `forcedColors: "active"` on every route, and ensures at most one `#main`, one `<main>` and one skip link per page.

Reading failures: locators fail with an ARIA snapshot; traces are in `__traces__/` (Vitest) and `site/test-results/<id>/trace.zip` (`bunx playwright trace open <zip>`); visual diffs are in `packages/ui/.vitest/attachments` and `site/playwright-report`. For lean output: `bunx vitest run --reporter=minimal`. Optional: `npx @playwright/mcp` to inspect the site.

---

## Critical rules

0. **Test first, always.** Every bug fix and issue starts with a regression test that reproduces the problem. Run it and confirm it fails on the current code, then fix, then confirm it passes. A PR reports that fail-before/pass-after evidence. Tests exist to prove a behavior or a fix, never to pad coverage: no tests of wiring, copies, mock echoes or incidental defaults. If a test cannot fail for a plausible bug, delete it.

1. **Required setup**: consumers import the CSS once (it already includes `materials.css`, themes and utilities), register both Vite plugins (`caThemePlugin`: anti-FOUC script + `ssr.noExternal` for TanStack Table and Shiki; `caErrorPlugin`: scaffolds `+error.svelte`/`error.html`) and export `handle` + `handleError` from the server hook. Plugin order in `plugins` does not matter (built with every order on Kit 3.0.1 / Vite 8.3); `init` writes them after `sveltekit()`:
   ```ts
   import "@codeatlasdev/ui/styles/global.css";
   ```
   ```ts
   // vite.config.ts
   import { caErrorPlugin, caThemePlugin } from "@codeatlasdev/ui/vite";
   import { theme } from "./src/lib/theme.ts";
   export default defineConfig({
     plugins: [sveltekit(), caThemePlugin(theme), caErrorPlugin({ scaffold: true, theme })],
   });
   ```
   ```ts
   // src/hooks.server.ts: injects the theme script into SSR/prerendered pages, sanitizes server errors
   import { sequence } from "@sveltejs/kit/hooks";
   import { caThemeHandle, createErrorHandler } from "@codeatlasdev/ui/kit";
   import { theme } from "$lib/theme"; // Kit 3: "#lib/theme.ts"
   export const handle = sequence(caThemeHandle(theme));
   export const handleError = createErrorHandler();
   ```
   SvelteKit 3 (`@sveltejs/kit ^3`): config goes into `sveltekit({ adapter, ... })` (no `svelte.config.js`, no `kit` namespace), `tsconfig.json` extends `$app/tsconfig`, `$lib` is removed in favor of `#lib/*` (with the `.ts` extension), and `vite.config.ts` imports the theme with its `.ts` extension. `bunx @codeatlasdev/ui init` detects the Kit version. Details: the SvelteKit 3 section of `.agents/skills/codeatlas-ui/SKILL.md`.

2. **`backdrop-filter` + `will-change: transform`**: never combine the two on the same element or an ancestor. It kills the glass blur. `backdrop-filter` is declared in `styles/surface.css` and `styles/materials.css` only: a component sets `data-ca-blur="<role>"` (roles: `ultra-thin`, `thin`, `regular`, `thick`, `chrome`, `mat-thin`, `mat-regular`, `overlay`, `chrome-layer`, `tooltip`; `FloatingLayer` takes it as `blur="overlay"|"tooltip"`), or is a `.ca-surface`, so `html[data-style]` drives every blur. The role rules write `-webkit-backdrop-filter` first. `data-ca-blur-wide-off` drops it from 900px up (an inline layout); `.ca-btn--glass` and `.ca-icon-btn--glass` are the `regular` role through their own class and lose it while disabled. The modal scrim is `dialog.ca-overlay::backdrop` in `surface.css`. New blurred element: add the attribute, never the property; the migration is guarded by `src/lib/theme/surface-migration.svelte.test.ts` (computed styles against `surface-migration.baseline.json`).

3. **`isolation: isolate`**: `backdrop-filter` inside an `isolation: isolate` parent captures the isolated context, not the real backdrop.

4. **Svelte 5 runes**: all code uses runes (`$state`, `$derived`, `$effect`, `$props`). Never use legacy `writable`/`readable`.

5. **`{@const}`**: valid only as an immediate child of `{#each}`, `{#if}`, `{#snippet}`, `{:else}`, or `Component`. Never inside `<div>` or another element.

6. **`svelte:component`**: deprecated in runes mode. Use `{@const Icon = X}<Icon />` or `<X />` directly.

7. **Sub-components**: `DropdownMenuItem` etc. are separate `.svelte` files exported by name; there are no dotted namespaces.

8. **OKLCH**: the whole color palette uses OKLCH. MUI does not accept OKLCH directly; if you integrate with MUI, convert to hex.

9. **No inline CSS**: never `style="padding: 20px"` or `style="max-width: 480px"`. Use CSS classes with tokens (`var(--ca-space-5)`). The only exception is dynamic CSS custom properties: `style="--bar-w:{pct}%"`.

10. **No `Stack`/`Row` for field layout inside `FormSection`**: `FormSection` already has `layout="grid"` (default), `layout="list"` and `layout="stack"`. Do not wrap fields in `Stack gap={N}` as a layout workaround.

11. **`ca-*` classes are a public contract**: consuming apps use the BEM classes (`.ca-btn`, `.ca-dialog__body`, …) as CSS targets. Renaming or removing a `ca-*` class listed in [`docs/css-api.md`](docs/css-api.md) is a **breaking change**. When you create or rename a component, update that file.

12. **Mobile**: heights use `var(--ca-vh)` (never `100vh`/`100dvh`); `fixed` UI uses `var(--ca-safe-*)`; a form with a keyboard uses `use:keyboardAware` (`@codeatlasdev/ui/actions`); a full-screen mobile view is `MobilePane`, an action bar is `StickyActions`; the 44px touch target is global under `(pointer: coarse)`, so do not write an override in the app. App viewport: `width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content`.

13. **Theme**: a single `ThemeOptions` in `src/lib/theme.ts` (plain object, `import type` only: `vite.config`/`astro.config` load the file in Node, where the package root does not evaluate `.svelte`), passed to `caThemeHandle` + `caThemePlugin` (SvelteKit) or `caUI` (Astro). Override a token by declaring `--ca-*` on `:root` in the app, without `!important`. Local islands: `data-theme-scope="dark|light"`. Automatic setup: `bunx @codeatlasdev/ui init`.

14. **SEO**: a public page uses `<Seo>` from `@codeatlasdev/ui/seo` with a required `canonical`; a private page passes `noindex`.

    **A11y tests**: test every state (open, error, empty, light, dark) with `await expectNoA11yViolations(container)` from `@codeatlasdev/ui/testing` (needs the optional peer `axe-core`). Inside this repo `packages/ui/tests/a11y.ts` re-exports the same `checkA11y`; never fork the axe options.

15. **Discovering the API**: never guess a prop. Use the `ca-ui-mcp` MCP server (`get_component`, `get_export`, `list_components`, `search_tokens`, `list_surfaces`, `get_guide`) or `.agents/skills/codeatlas-ui/API.md`; both cover components and every non-component export (stores, `kit`, `vite`, `astro`, `actions`, `seo`, `forms`, `tokens`: signature + summary) and are generated from the code by `packages/ui/scripts/build-manifest.ts` (runs on `build`). `[ca-ui]` dev warnings (via `devWarn`, `esm-env`) flag an `IconButton` without `aria-label` and a `Dialog` without `title`.

16. **Agent skills layout** (`npx skills add codeatlasdev/ui`): one folder per skill under `.agents/skills/`, named exactly like the `name:` in its `SKILL.md` (`codeatlas-ui`, `codeatlas-dx`, `codeatlas-writing`). Never put a `SKILL.md` directly in `.agents/skills/` (the CLI then treats the directory as a single skill and lists nothing else), and quote any `description:` that contains `: ` (an unquoted one is a YAML error and the CLI silently skips the skill). `packages/ui/tests/skills.test.ts` enforces this.

---

## Spacing system (global tokens)

**Every component uses CSS variables, never hardcoded px values.**

```css
/* Spacing scale: base 4px */
--ca-space-1:  4px
--ca-space-2:  8px
--ca-space-3:  12px
--ca-space-4:  16px
--ca-space-5:  20px
--ca-space-6:  24px
--ca-space-7:  28px
--ca-space-8:  32px
--ca-space-10: 40px
--ca-space-12: 48px
--ca-space-16: 64px

/* Page layout: consistent padding across ALL page layouts */
--ca-page-px:    24px   /* default horizontal padding */
--ca-page-px-sm: 16px   /* mobile horizontal padding */
--ca-page-pt:    20px   /* default top padding */
--ca-page-pt-sm: 14px   /* mobile top padding */
--ca-page-gap:   20px   /* gap between sections */
```

---

## Utility classes (`global.css` → available in every app)

Imported automatically via `global.css`. No extra configuration needed.

| Class | Use |
|---|---|
| `ca-search-field` | Toolbar search field: `flex:1`, `min-width:180px`, `max-width:320px` |
| `ca-toolbar-spacer` | `flex:1`: pushes items to the right side of the toolbar |
| `ca-page-info` | "1–8 of 240" text in the pagination footer |
| `ca-row-actions` | Row actions: hidden by default, visible on hover |
| `ca-btn-danger` | Red outlined button |
| `ca-btn-danger-ghost` | Red ghost/text button |
| `ca-bar-fill` | Dynamic progress bar: uses the `--bar-w` CSS var |
| `ca-bar-fill--warn` | Warning variant of the bar |
| `ca-pricing-cta` | CTA button at the bottom of a pricing card (`width:100%; margin-top:auto`) |
| `ca-sr-only` | Visually hidden, still in the a11y tree (table `<caption>`, unlabeled control, extra AT-only text). Never `display:none`/`aria-hidden` for this |
| `ca-sr-only ca-sr-only--focusable` | Same, but shown again while it or a descendant has focus (skip links) |

---

This is the most important rule for staying consistent across the site and real apps.

### `AppList`: fullscreen list/CRUD

**When to use:** an entity list page (users, orders, invoices, etc.)

Behavior: the page does NOT scroll. Only the table scrolls. Header, toolbar and pagination footer stay fixed.

```svelte
<AppList title="Users" data={users} searchKeys={['name', 'email']} perPage={8}>
  {#snippet actions()}
    <Button variant="filled" href="/users/new">+ New user</Button>
  {/snippet}

  {#snippet filters(list)}
    <FilterGroup options={roleOpts} value={list.filters['role']}
                 onchange={(v) => list.setFilter('role', v)} />
  {/snippet}

  {#snippet children(list)}
    <SimpleTable>
      <thead><tr><th>Name</th><th>Role</th><th>Status</th></tr></thead>
      <tbody>
        {#each list.rows as u (u.id)}
          <tr>
            <td class="primary"><UserCell name={u.name} email={u.email} /></td>
            <td>{u.role}</td>
            <td><StatusChip status={u.status === 'active' ? 'success' : 'neutral'} /></td>
          </tr>
        {/each}
      </tbody>
    </SimpleTable>
  {/snippet}
</AppList>
```

With `data`, `AppList` renders search, count, pagination and empty state on its own. Use manual `toolbar`/`footer` only when pagination happens on the server.

---

### `AppForm`: create/edit form

**When to use:** a page to create or edit an entity (New User, Edit Post, etc.)

Behavior: header and footer stay fixed. Only the form body scrolls.

```svelte
<AppForm title="New User" description="Fill in the details to create a new user.">
  {#snippet leading()}
    <!-- back button goes here -->
    <Button variant="ghost" size="sm" href="/users">
      {#snippet leading()}<ArrowLeft size={15} />{/snippet}
    </Button>
  {/snippet}

  <!-- FormSection layout="grid" is the default: text fields sit in 2 columns -->
  <FormSection title="Account details" description="Basic information.">
    <TextField label="Full name" bind:value={name} />
    <TextField label="Email" type="email" bind:value={email} />
    <Select label="Role" bind:value={role} options={roleOpts} />
  </FormSection>

  <!-- layout="list" for Switch, SettingItem, Divider -->
  <FormSection title="Notifications" layout="list">
    <Switch label="Send welcome email" bind:checked={notify} />
  </FormSection>

  {#snippet footer()}
    <Button variant="ghost" href="/users">Cancel</Button>
    <Button variant="filled" onclick={save} disabled={saving || !name || !email}>
      {saving ? 'Saving…' : 'Create user'}
    </Button>
  {/snippet}
</AppForm>
```

**`AppForm` rules:**
- The back button goes in `{#snippet leading()}`, not as the first child of the form
- Cancel/save actions go in `{#snippet footer()}`, never in the body
- Do not pass `maxWidth`: the content takes all available space
- `FormSection` default `layout="grid"` works for text fields
- `FormSection layout="list"` for Switch/SettingItem (no gap, flush)
- `FormSection layout="stack"` for composite blocks (Avatar + fields)

---

### `AppSettings`: settings with side navigation

**When to use:** a settings page with multiple sections (Workspace, Notifications, Security, etc.)

Behavior: fixed side nav on the left. The right content scrolls.

```svelte
<script lang="ts">
  import { AppSettings, FormSection, SettingItem, Switch, Button, Divider } from '@codeatlasdev/ui';
  import { Settings, Bell, Shield } from '@lucide/svelte';

  const TABS = [
    { value: 'general',  label: 'General',       icon: Settings },
    { value: 'notifs',   label: 'Notifications',  icon: Bell     },
    { value: 'security', label: 'Security',       icon: Shield   },
  ];

  let tab    = $state('general');
  let saving = $state(false);

  function save() { saving = true; setTimeout(() => (saving = false), 900); }
</script>

<AppSettings
  title="Settings"
  description="Manage your workspace."
  tabs={TABS}
  activeTab={tab}
  onTabChange={(t) => (tab = t)}
>
  {#snippet actions()}
    <Button variant="filled" size="sm" onclick={save} disabled={saving}>
      {saving ? 'Saving…' : 'Save changes'}
    </Button>
  {/snippet}

  {#if tab === 'general'}
    <FormSection title="Workspace">
      <TextField label="Name" bind:value={workspaceName} />
      <Select label="Timezone" bind:value={timezone} options={tzOpts} />
    </FormSection>
  {/if}

  {#if tab === 'notifs'}
    <FormSection title="Email" layout="list">
      <SettingItem label="New signups" description="Email on every new user.">
        <Switch bind:checked={emailSignup} />
      </SettingItem>
      <Divider />
      <SettingItem label="System errors" description="Critical alerts.">
        <Switch bind:checked={emailErrors} />
      </SettingItem>
    </FormSection>
  {/if}
</AppSettings>
```

**`AppSettings` rules:**
- Do not pass `maxWidth`: the content takes the whole available area
- Each tab renders with `{#if tab === 'x'}` in the body
- `FormSection layout="list"` for `SettingItem` + `Switch` (the most common pattern in settings)
- `FormSection layout="grid"` for text fields (name, email, etc.)
- Global actions (Save/Cancel) go in `{#snippet actions()}`

---

### `MobilePane` and `StickyActions`: native-feeling mobile

```svelte
<MobilePane bind:open={chatOpen} title="Maria" onback={() => (chatId = null)}>
  {#snippet actions()}<IconButton aria-label="More">…</IconButton>{/snippet}
  <Messages />
</MobilePane>

<StickyActions align="stretch" show={dirty}>
  <Button variant="ghost">Cancel</Button>
  <Button variant="filled">Save</Button>
</StickyActions>
```

`MobilePane`: `bind:open`, `title`, `onback?`, `actions?`, `headerTitle?` (replaces the title text), `scroll=true` (`false` when the body has its own scroll and composer). Never hand-roll `position: fixed` for full-screen mobile views. `AuthLayout` shows a brand strip below 768px (`mobileBrand`, default `true`); do not create a local `AuthBrand`.

---

### `PageShell`: dashboards and free-form content pages

**When to use:** dashboards, reports, analytics. Any page that is not a list, form or settings page.

```svelte
<PageShell title="Dashboard" description="Monday, Sep 22, 2026" maxWidth="1200px" gap={24}>
  {#snippet actions()}
    <Button variant="ghost" size="sm">Export</Button>
  {/snippet}

  <KpiGrid>
    <KpiCard title="Revenue" value="$112k" trend={18.4} icon={DollarSign} />
    <KpiCard title="Users"   value="24.8k" trend={12.1} icon={Users}      />
  </KpiGrid>

  <GlassCard title="Revenue vs Expenses">
    <LineChart series={[...]} categories={months} area height="260px" />
  </GlassCard>
</PageShell>
```

---

## `FormSection`: quick reference

| `layout` | Use when | Behavior |
|---|---|---|
| `"grid"` (default) | `TextField`, `Select`, `NumberField` | Auto-fill 2 columns, `minmax(260px, 1fr)` |
| `"list"` | `Switch`, `SettingItem`, `Divider` | Single column, no gap between items |
| `"stack"` | Composite blocks (Avatar + fields, groups) | Single column, `gap: 16px` |

**Never** wrap fields in `<Stack gap={N}>` inside `FormSection`. Let `layout` do the work.

---

## Available components

### Page layout (App-level)
| Component | Use |
|---|---|
| `AppList` | Fullscreen list: table with internal scroll, fixed pagination |
| `AppForm` | Form: header + scrolling body + sticky footer |
| `AppSettings` | Settings: side nav + scrollable content |
| `PageShell` | Dashboard/content: normal scroll, max-width, configurable gap |
| `MobilePane` | Full screen above the shell on mobile (chat thread, history, detail): header with back, Escape closes, focus enters/returns, safe-area and virtual keyboard |
| `StickyActions` | Form action bar stuck to the end of the scroll (`align="end" \| "stretch"`, `show`): glass, safe-area and virtual keyboard |

### Content layout
| Component | Use |
|---|---|
| `FormSection` | Form section: title, description, grid/list/stack of fields |
| `SettingItem` | Settings row: label + description + control (Switch, Button) |
| `GlassCard` | Generic glass container |
| `KpiCard` | Metric card: value, trend, icon |
| `KpiGrid` | Row of KpiCards that never ends on an empty cell (counts the children; never use `Grid` auto-fill for KPIs) |
| `Grid` | CSS grid with configurable `cols` and `gap` |
| `Row` | Flex row with `gap`, `align`, `justify` |
| `Stack` | Flex column with `gap` |
| `EmptyState` | Empty state with icon, title, action |

### AppShell (app shell)
| Component | Description |
|---|---|
| `AppShellLayout` | Root layout: Rail + Panel + content |
| `Rail` | 52px side dock. Logo via `{#snippet brand()}`, actions via `{#snippet railBottom()}` |
| `Panel` | 200px navigation panel with spring animation |
| `BottomNav` | Bottom navigation for mobile |
| `MobileHeader` | Mobile header |

### Glass surfaces
| Component | Use |
|---|---|
| `GlassSurface` | Generic glass container with configurable material and thickness |
| `GlassCard` | Glass card with default padding, optional title, `flush`, `full` |
| `LiquidGlass` | Liquid Glass effect with background distortion |

### DataTable (TanStack Table v9)
```ts
import { DataTable, createCaTable, createCaColumnHelper, caTableFeatures } from "@codeatlasdev/ui/table";
```
- Server-side: `createCaTable` + `caTableFeatures` for server-side sorting/filtering/pagination
- `CaColumnDef<T>`: column type with metadata (`meta.label`, `meta.filterVariant`)
- For simple lists use `SimpleTable` + `UserCell` + `StatusChip`, which is lighter

### Display
`Avatar` · `Image` · `Badge` · `Alert` · `Chip` · `StatusChip` · `KpiCard` · `KpiGrid` · `EmptyState` · `Timeline` · `Sparkline` · `SimpleTable` · `LiveList` · `ExternalLink`

- **Streaming rows (SSE/WebSocket/bulk job)**: `LiveList` (`items`, `item` snippet, `total`, `status`, `label`). It is a `role="log"` with `aria-live="off"`: rows are summarised as one polite announcement per batch, auto-scroll follows only while the user is at the bottom (scrolling up pauses it and shows a "N new" button) and nothing ever calls `focus()`. Do not put `StatusChip` (it has `role="status"`) or any live region inside a row; use `Chip` or text.
- **External links**: `ExternalLink` (never hand-write `target="_blank"`): sets `rel="noopener noreferrer"`, an `aria-hidden` icon and a localised "(opens in a new tab)" for screen readers (`externalLink.newTab`). `Button href target="_blank"` already sets `rel`.
- **Export (CSV/JSON)**: `ExportMenu` (`data`, `filename`, `columns`, `formats`, `onexport`) or the helpers `toCsv` / `toJson` / `downloadFile` from the package root. CSV is RFC 4180 and neutralises spreadsheet formulas.

- **`SimpleTable` `responsive`**: `"scroll"` (default) or `"cards"`. With `cards`, below `md` each `<tr>` becomes a card and each `<td>` shows its label via `::before { content: attr(data-label) }`. **Required: pass `data-label="Column"` on every `<td>`** (a cell without `data-label` has no label). No local scroll wrappers needed.
  ```svelte
  <SimpleTable responsive="cards">
    <thead><tr><th>Name</th><th>Status</th></tr></thead>
    <tbody>{#each rows as r}<tr><td data-label="Name">{r.name}</td><td data-label="Status">{r.status}</td></tr>{/each}</tbody>
  </SimpleTable>
  ```
- **Touch target**: `--ca-touch-target: 44px` (`tokens.css`). Under `@media (pointer: coarse)` it becomes `min-height`/`min-width` of `IconButton`, the `Select` trigger, `TabsTrigger`, `ToggleGroup`, `SegmentedControl`, `PinInput` and calendar cells. It is a media query, not a prop: do not write 44px overrides in the app.

### Inputs (own primitives with glass tokens)
`Button` · `IconButton` · `TextField` · `TextArea` · `Select` · `Combobox` · `Checkbox` · `Switch` · `Slider` · `NumberField` · `FileUpload` · `ToggleGroup` · `SegmentedControl` · `SwatchGroup` · `PinInput` · `CopyButton` · `DatePicker` · `DateRangePicker` · `DateField` · `TimeField` · `Calendar` · `RangeCalendar`

- **`Button` / `IconButton` `loading`**: swaps `leading` (Button) or the icon (IconButton) for a `Spinner`, applies `aria-busy="true"`, disables the click (`onclick` does not fire) and keeps the label. Class: `ca-btn--loading`.
- **`ToggleGroup`**: `type="single" | "multiple"`, `bind:value` (`string` or `string[]`), `items: { value, label?, icon?, disabled?, 'aria-label'? }[]` (an icon-only item requires `aria-label`), `size="sm" | "md"`, `variant="outlined" | "ghost"`, `orientation`, `onchange`.
- **`SegmentedControl`**: single `ToggleGroup` with a sliding pill (`.ca-seg__thumb`, no animation under `reducedMotion`). Props: `bind:value`, `items`, `size="sm" | "md"`, `fullWidth`, `disabled`, `onchange`.
- **`SwatchGroup`**: single-choice color picker (`role="radiogroup"`). `bind:value`, `items: { value, label?, color?, disabled? }[]` (without `color` the swatch paints from `data-preset={value}`; `value=""` means none selected), `size="sm" | "md"`, `disabled`, `onchange`. Under `pointer: coarse` the swatch itself is the 44px target.
- **`PinInput`**: OTP. `length=6`, `bind:value`, `type="numeric" | "text"`, `label`, `description`, `error`, `mask`, `oncomplete(value)`.
- **`CopyButton`**: `value`, `label="Copy"` (`''` = icon only), `size`, `variant="ghost"`, `toast?: string` (success message), `oncopy`. The icon becomes `Check` for 2s.
- **Dates** (`DateValue` values from `@internationalized/date`, re-exported by the root: `CalendarDate`, `Time`, `today`, `parseDate`…): `locale="pt-BR"`, `weekStartsOn=1`, `minValue`, `maxValue`, `label`, `description`, `error`, `disabled`, `required`, `bind:value`.
  - `DatePicker`: field + popover with a calendar (`bind:open`, `granularity`, `numberOfMonths`, `closeOnDateSelect`, `name`, `triggerLabel`)
  - `DateRangePicker`: `value: DateRange` (`{ start, end }`), `closeOnRangeSelect`
  - `DateField`: only the typeable segments, no popover
  - `TimeField`: `value: Time`, `granularity="hour" | "minute" | "second"`, `hourCycle`
  - `Calendar` / `RangeCalendar`: inline grid (`fixedWeeks`, `isDateDisabled`, `isDateUnavailable`)

```svelte
<Button loading={saving} onclick={save}>Save</Button>
<SegmentedControl bind:value={view} items={[{ value: "list", label: "List" }, { value: "grid", label: "Grid" }]} />
<DatePicker label="Delivery" bind:value={date} minValue={today(getLocalTimeZone())} />
<TimeField label="Time" bind:value={time} />
<PinInput length={6} oncomplete={verify} />
```

### Overlays
`Dialog` · `AlertDialog` · `Drawer` · `DropdownMenu` · `Popover` · `Tooltip` · `CommandPalette` · `NotificationBell`

- **`AlertDialog`**: confirmation that requires an answer (`role="alertdialog"`, no "X", clicking outside does not close). Props: `bind:open`, `title`, `description?`, `confirmLabel="Confirm"`, `cancelLabel="Cancel"`, `destructive?`, `pending?`, `onconfirm: () => void | Promise<void>`, `oncancel?`. With an async `onconfirm`: confirming shows a spinner, Cancel is disabled, and it closes on resolve (stays open if it throws). Replaces native `confirm()`.
- **`Sheet`**: bottom sheet below 768px, centered dialog above. `swipeToDismiss = true` (bottom layout only): drag the handle or the header (`.ca-sheet__grab`, `touch-action: none`, pointer capture) downward; it closes past 30% of the height or a velocity above 0.5 px/ms, otherwise it springs back with `Spring`. Disabled under `reducedMotion`. The panel moves via `translate` (no `transform`, no backdrop-filter on the panel). The overlay and scrollable bodies of Sheet/Drawer/Dialog use `touch-action: none` / `overscroll-behavior: contain`; the primitives' scroll lock (`primitives/scroll-lock.ts`) is enough on WebKit.
- **`Dialog`**: `size="sm" | "md" | "lg" | "xl" | "split"`. `split` = 1100×720, 2-column grid at ≥`md`, 1 column below. `chromeless` omits header/description/actions and zeroes the body padding (pass `title` for the accessible name; it stays visually hidden).
```svelte
<AlertDialog bind:open title="Delete lead?" description="This cannot be undone." confirmLabel="Delete" destructive onconfirm={() => api.remove(id)} />
<Dialog bind:open size="split" chromeless title="Lead">…</Dialog>
```

### Navigation
`Tabs` · `TabsList` · `TabsTrigger` · `TabsContent` · `Breadcrumb` · `Pagination` · `Stepper`

### Docs (documentation sites)
`DocsShell` (header + sidebar + page index; on mobile a compact header and menu in a `Sheet`) · `DocsNav` · `TableOfContents` (`variant="rail" | "inline"`) · `DocsSearch` + `searchDocs` · `CodeTabs`/`CodeTab` (copy, `sync` across groups) · `Callout` · `Steps` · `LinkCard` · `CardGrid` · `MethodBadge`. Markdown typography: wrap the HTML in `<div class="ca-prose">`; tables in `.ca-table-wrap`, code in `.ca-code` (shiki dual theme). Syntax highlighting is up to the consumer (shiki at build).

```svelte
<DocsShell {sections} active="api" {groups} {pathname} {headings}
  searchIndex={() => fetch('/search.json').then((r) => r.json())} onnavigate={goto}>
  {#snippet brand()}<Logo /> Docs{/snippet}
  <article class="ca-prose">…</article>
</DocsShell>
```

### Feedback
`Spinner` · `Skeleton` · `Progress` · `Toast` · `Toaster`

### Charts (ECharts): `@codeatlasdev/ui/charts`, requires `echarts` installed
`LineChart` · `BarChart` · `PieChart` · `ScatterChart` · `HeatmapChart` · `GaugeChart` · `RadarChart` · `Sparkline`

### Subpaths with an optional peer
Charts, DataTable and CodeSnippet are NOT in the root import. Each subpath requires its peer:

| import | peer |
|---|---|
| `@codeatlasdev/ui/charts` | `echarts` |
| `@codeatlasdev/ui/table` | `@tanstack/svelte-table` |
| `@codeatlasdev/ui/code` | `shiki` |
| `@codeatlasdev/ui/forms` | none (Brazilian masks, `MoneyInput`, ready-made fields) |
| `@codeatlasdev/ui/testing` | `axe-core` (test-only: `expectNoA11yViolations`, `checkA11y`) |

### `@codeatlasdev/ui/forms`: Brazilian fields
```ts
import { MaskedField, MoneyInput, PhoneField, CepField, mask,
  maskCPF, maskCNPJ, maskCPFCNPJ, maskCEP, maskPhoneBR, maskDateBR, maskRG,
  isValidCPF, isValidCNPJ, isValidDateBR, centsToDisplay, parseInputToCents, currencyDecimals } from "@codeatlasdev/ui/forms";
```
| Symbol | Use |
|---|---|
| `MaskedField` | `TextField` + `mask: (raw) => string` + `validate?: (v) => string \| undefined` (runs on blur). Automatic `inputmode` (`numeric` for CPF/CEP/phone/date) |
| `MoneyInput` | `value` in the currency's **minor unit** (integer, bindable). `123456` displays `R$ 1.234,56` (BRL default). Props: `currency` (ISO 4217, decimals from `Intl`: USD 2, JPY 0, BHD 3), `locale` (BCP 47; defaults to the active i18n locale when `currency` is set, `pt-BR` when it is not), `min`, `max`, `allowNegative` (default `false`), `onchange(minorUnits)` |
| `PhoneField` | bindable `value` in **E.164** (`+5511987654321`; `''` if incomplete). `country="BR"` |
| `CepField` | masked `bind:value` + `onlookup?: (cep) => Promise<CepAddress \| null>` (the package does no fetching: inject ViaCEP), `onresolve(address)`, `bind:lookupPending` to disable dependent fields |
| `maskCPF` `maskCNPJ` `maskCPFCNPJ` `maskCEP` `maskPhoneBR` `maskDateBR` `maskRG` | Pure functions `(raw: string) => string` |
| `isValidCPF` `isValidCNPJ` `isValidDateBR` | Validation (check digits / real date) |
| `centsToDisplay(n, {currency, locale}?)` · `parseInputToCents(text, {currency, locale}?)` · `currencyDecimals(currency)` | `123456` ⇄ `"R$ 1.234,56"` (BRL / pt-BR default); `centsToDisplay(123456, {currency:"USD", locale:"en-US"})` → `"$1,234.56"` |
| `use:mask={maskCPF}` | Action for a native `<input>`; preserves the cursor (counts digits before the caret) |

```svelte
<MaskedField label="CPF" mask={maskCPF} validate={(v) => (isValidCPF(v) ? undefined : "Invalid CPF")} bind:value={cpf} />
<MoneyInput label="Amount" bind:value={cents} min={0} />
<MoneyInput label="Price" currency="USD" locale="en-US" bind:value={usdCents} />
<PhoneField label="WhatsApp" bind:value={e164} />
<CepField label="CEP" bind:value={cep} bind:lookupPending onlookup={viaCep} onresolve={(a) => (street = a.logradouro)} />
```

`useForm` (root) accepts `arrays` for repeatable rows. Each array is a `FieldArrayState<T>` with `items`, `add(item)`, `remove(index)` and `move(from, to)`:
```ts
const form = useForm({ name: "" }, { arrays: { phones: [{ number: "" }] } });
form.arrays.phones.add({ number: "" });
form.arrays.phones.move(0, 1);
```

---

## TypeScript tokens

```ts
import {
  caColors,      // full OKLCH palette per preset
  caTypography,  // type scale (h1..h6, body1, body2, caption, label, button)
  caShape,       // border radii (xs, sm, md, lg, xl, pill)
  caTransitions, // easing and duration (fast, base, slow, spring)
  caZIndex,      // z-index scale (nav, dropdown, sticky, fixed, drawer, modal, snackbar, tooltip)
  caShadows,     // shadows
  caMaterials,   // material tokens (regular, thick, thin, ultrathin, ultrachick)
} from "@codeatlasdev/ui";
```

---

## CSS tokens (CSS variables)

```
/* Typography */
--ca-font-size-h1..h6 / body1 / body2 / caption / label / button

/* Radius */
--ca-radius-xs / sm / md / lg / xl / pill

/* Z-index */
--ca-z-nav / dropdown / sticky / fixed / drawer / modal / snackbar / tooltip

/* Animation */
--ca-ease-standard / decelerate / accelerate / spring
--ca-duration-fast / base / slow

/* Glass */
--ca-glass-bg / --ca-glass-separator / --ca-glass-tint-* / --ca-glass-border
--ca-blur-ultra-thin / thin / regular / thick / chrome

/* Semantic colors */
--ca-brand-main / --ca-brand-light / --ca-brand-dark / --ca-brand-contrast / --ca-brand-h
--ca-semantic-success / warning / error / info
--ca-text-primary / secondary / disabled   (disabled = label of disabled controls only, >= 3:1; de-emphasised information uses --ca-text-hint)
--ca-surface-base / raised / sunken / overlay
--ca-outline-subtle / default / strong / control   (control = field and control edge, >= 3:1; subtle = dividers only)
--ca-focus-ring / --ca-state-indicator   (>= 3:1 on every surface and on hover/selected fills; components read these, never --ca-brand-main)
--ca-semantic-error-fill / --ca-semantic-error-contrast   (pair, like brand-fill / brand-contrast)
--ca-action-hover / selected / disabled / disabled-bg   (disabled controls use tokens, never opacity)
--ca-overlay-bg / --ca-panel-bg   (near-opaque by default; --ca-overlay-bg-glass / --ca-panel-bg-glass are the see-through tints)

/* Spacing (base 4px) */
--ca-space-1 (4px) .. --ca-space-16 (64px)

/* Page layout */
--ca-page-px    (24px)  ← horizontal padding on every page
--ca-page-px-sm (16px)  ← mobile
--ca-page-pt    (20px)  ← top padding
--ca-page-gap   (20px)  ← gap between sections
```

---

## Themes

```html
<html data-preset="ocean">
<!-- ocean | amber | crimson | cyan | violet | emerald | rose | slate -->
<html class="dark">
```

### Brand theme

Does the product have its own color? Generate a preset from the logo hex. The library derives hue, chroma and lightness (OKLCH) and emits the full token set, light and dark, inline in the `<head>`. No flash.

```ts
// src/lib/theme.ts: one place, used by the hook and the plugin
import type { ThemeOptions } from "@codeatlasdev/ui/vite"; // = Partial<ThemeDefinition>; "/astro" in Astro. Never the package root: Node cannot load its .svelte files

export const theme: ThemeOptions = {
  presets: [{ id: "acme", color: "#2563eb" }],
  defaultPreset: "acme",   // used until the user picks another
  defaultScheme: "system", // "light" | "dark" | "system"
  defaultStyle: "glass",   // "glass" | "frosted" | "solid" | "flat"
  fonts: { body: "Geist, system-ui, sans-serif" },
  radius: 1,               // multiplier of the radius scale
  density: "comfortable",  // or "compact"
  overrides: { light: { "--ca-card-padding": "16px" } },
};

// src/hooks.server.ts
export const handle = sequence(caThemeHandle(theme));

// vite.config.ts
plugins: [sveltekit(), caThemePlugin(theme)]
```

- `id` must not collide with a built-in preset; `defaultPreset` must exist (build error).
- The init script discards saved values the app does not know (old preset, invalid scheme/style) and falls back to the default.
- Sets `<meta name="theme-color">` to the preset surface and follows the OS in `system` before JS loads.
- Charts use the brand hex as the first series.
- `colorScheme` inherits the defaults: `colorScheme.preset` starts at `"acme"`.

### Cascade and overriding tokens

`core.css` declares `@layer ca.reset, ca.tokens, ca.themes, ca.base, ca.materials, ca.utilities, ca.components`. `ca.reset` (`styles/reset.css`) makes `button, input, select, textarea` inherit the page font (`font: inherit`); a control needs no font rule of its own unless it sets a different one. **Every component `<style>` block (and `Dialog/dialog.css`, `Date/date.css`) is wrapped in `@layer ca.components { ... }`**, the last kit layer; app CSS is unlayered. Unlayered beats any layer regardless of specificity or source order, so an app overrides a kit rule with the same single-class selector (`.ca-btn:disabled`, `.ca-tf__wrap`, `.ca-dialog__body`), no `!important`, no doubled classes. To override package tokens, declare `--ca-*` on `:root`.

Rules when editing components: (1) new component CSS goes inside `@layer ca.components { ... }` and the `<style>` starts with the full order statement (`@layer ca.reset, ..., ca.components;`), because the first mention of a layer name fixes its priority and a bundler can emit a component chunk before `core.css`; `tests/component-layer.test.ts` fails otherwise. (2) Inside the layer, `:global(...)` and scoped selectors both work (Svelte keeps the hash class; app rules still win by layer). (3) Avoid `!important` in component CSS: a layered `!important` beats unlayered app CSS (the reverse of normal declarations), so apps could not override it. Same-layer conflicts (error vs focus) are settled by selector order/specificity. Allowed only to beat an inline `style=` the component itself sets (Progress indeterminate width, `.ca-main` spring margin, Shiki inline background) and for `prefers-reduced-motion`; `base.css` focus rules use it on purpose. (4) Unlayered kit CSS is not allowed except `marks.css` and inline brand `<style id="ca-theme">`, which are intentionally app-level.

`global.css` = `core.css` (includes only the `amber` preset) + the other 7 presets. Apps that use a single preset import only `styles/core.css` + `styles/presets/<id>.css` (see `site/.../getting-started/performance.mdx`).

The built-in presets are generated: edit `packages/ui/src/lib/theme/builtins.ts` and run `bun run --cwd packages/ui themes` (`validate` fails if `styles/presets/*.css` is out of date).

### Theme islands

```svelte
<section data-theme-scope="dark">…dark mode tokens in here, on any page…</section>
```

### Runtime tokens

`colorScheme.setTokens({ "--ca-brand-main": "#ff5500" })` writes a single `<style id="ca-runtime-tokens">`, persists it, and the init script reapplies it before the first paint. `setTokens({})` clears it.

---

## Stores

```ts
import { colorScheme, reducedMotion, responsive } from "@codeatlasdev/ui";

colorScheme.init()          // in the root layout (onMount); returns cleanup
colorScheme.toggle()        // switch dark/light
colorScheme.setPreset(id)   // change the color preset (colorScheme.presets lists the valid ones)
colorScheme.isDark          // reactive boolean

responsive.init()           // measures and starts following resize; returns cleanup
responsive.current          // 'xs' | 'sm' | 'md' | 'lg' | 'xl'; before init it is desktop
```

---

## Language (i18n)

Every piece of visible text the package generates (aria-label, placeholder, empty states, toasts, "Copy", "On this page"…) comes from a catalog. The default is **English**. `Locale` is any BCP 47 string; `en` and `pt-BR` are built in, others are added with `registerLocale`.

```svelte
<!-- SSR apps: src/routes/+layout.svelte. Request-scoped, never shared between requests. -->
<script>
  import { I18nProvider } from "@codeatlasdev/ui";
  let { data, children } = $props();
</script>
<I18nProvider locale={data.locale}>{@render children()}</I18nProvider>
```

```ts
// Client-only apps (SPA, Astro islands): one module-level locale.
import { registerLocale, setLocale } from "@codeatlasdev/ui";
registerLocale("es", { common: { close: "Cerrar" } }); // partial; missing keys fall back to en
setLocale("es");
```

- **Never call `setLocale` on the server**: it is a no-op there (dev warning), because module state would leak between concurrent requests. Use `I18nProvider`. A provider always wins over `setLocale`.
- `createErrorHandler({ locale })` takes the fallback-message language explicitly (string or `(event) => locale`); it reads no global state.
- The client `$state` behind `setLocale` is module-level: all islands on the same page share the language and re-render on change. `locale.value` reads it; inside a provider use `useLocale()`.
- **An explicit prop always wins** over the catalog: `<TableOfContents label="In this article" />`. Text props (`label`, `placeholder`, `confirmLabel`, `emptyText`, `ofLabel`…) no longer have a default; without the prop, the component uses the catalog.
- **Override phrases** without creating a locale: `<I18nProvider locale="pt-BR" messages={{ docs: { toc: "In this article" } }}>` or `setLocale("pt-BR", { … })`. Deep-merged over the catalog; a new `setLocale` call replaces the previous overrides.
- Catalog: one module per group in `packages/ui/src/lib/i18n/groups/<name>.ts` (e.g. `docs`, `dialog`), each a `defineGroup("docs", { en: {…}, "pt-BR": {…} })`. `en` is the source of truth; `pt-BR` is typed against it (a missing key is a type error). Strings with a value are functions: `notificationBell.label(unread)`. Groups are registered in `all.ts` (the `Messages` type, `getMessages`, public `useT()`); the rune-free `catalog.ts` holds `defineGroup`, `getGroup(group, locale, override?)` and the `registerLocale` registry.
- **A component pays only for its own strings.** The built-in locales travel inside each group and a component imports only the groups it reads, so tree-shaking drops the rest. Never import `all.ts`, `getMessages` or the public `useT()` inside the package: they name every group and ship the whole catalog (`tests/i18n-split.test.ts` fails if Button's bundle contains another component's text).
- New text in a component: add the key to the group's `en` **and** `pt-BR` (new group: new file in `groups/` plus one line in `all.ts`), then in `<script>` `import { group } from "../../i18n/groups/<name>.js"` and call `const t = useMessages(group);` at the top level (or in a `.svelte.ts` helper called at component init; `useMessages` reads Svelte context, so it cannot run in event handlers or module scope). Read `t().group.key` in markup/`$derived`, and use `label ?? t().group.key` when there is a prop. Several groups: `useMessages(a, b)`. Never import a global `t`.
- In browser tests, call `setLocale("pt-BR")` where the test checks Portuguese text and `setLocale("en")` in `afterEach`; the default is English. SSR tests (`*.ssr.test.ts`, `bun run test:ssr`) wrap the tree in `I18nProvider`.
- The date/number `locale` (`DatePicker locale="pt-BR"`, masks) is independent of the UI language.

---

## AppShell: usage pattern

```svelte
<!-- In any authenticated app layout -->
<AppShellLayout
  modules={MODULES}
  pathname={$page.url.pathname}
  persistPanel={false}
  onNavigate={(path) => goto(path)}
>
  {#snippet brand()}
    <!-- Logo at the top of the Rail and in the mobile header. Without it: "CA" -->
    <a href="/" aria-label="Acme"><AcmeLogo size={28} /></a>
  {/snippet}

  {#snippet railBottom()}
    <!-- Fixed items at the bottom of the rail: notifications, avatar, search -->
    <button class="ca-rail-btn" onclick={() => (cmdOpen = true)}>
      <Search size={16} />
    </button>
    <NotificationBell {notifications} />
    <a href="/profile" class="ca-rail-avatar">
      <Avatar alt={user.name} size="sm" />
    </a>
  {/snippet}

  <!-- No {#snippet header()}. The global header was removed -->
  <!-- Each page defines its own "header" via AppList/AppForm/AppSettings/PageShell -->

  {@render children?.()}
</AppShellLayout>
```

**Rule:** `AppShellLayout` has no global header. Each page defines its own top via `AppList` (header+toolbar), `AppForm` (header), `AppSettings` (header), or `PageShell` (header+body).

---

## Relationship with consuming projects

Every app that consumes the package must:
1. Install `@codeatlasdev/ui` from public npm (no `.npmrc`/auth)
2. Import `@codeatlasdev/ui/styles/global.css` in the root layout and register `caThemePlugin()` in `vite.config.ts`
3. Define the brand theme (`ThemeOptions`) and pass it to `caThemeHandle` and `caThemePlugin`
4. Use `AppShellLayout` as the root layout wrapper, with `brand` for the logo and `railBottom` for user actions
5. Build pages with `AppList`, `AppForm`, `AppSettings`, or `PageShell`, never manual wrappers

---

## Code conventions

- Indentation: tabs (Biome)
- Quotes: double (Biome)
- Semicolons: always
- `lineWidth`: 100
- No Tailwind: styles via CSS vars and classes
- No MUI in this package: it is pure Svelte on its own primitives layer (`src/lib/primitives`)
- No inline CSS except dynamic CSS custom properties (`style="--bar-w:{pct}%"`)


## Performance (package guards)

- `bun run --cwd packages/ui size` (part of `validate`) bundles each entry with esbuild and compares the gzip size with `packages/ui/size-limit.json`. The limit only goes down: `size:update` lowers limits with some headroom; raising a limit is a manual decision, explained in the PR. To add an entry, edit `ENTRIES` in `scripts/size-limit.ts`.
- `bun run --cwd packages/ui lint:tokens` (part of `validate`) rejects: `backdrop-filter` (either spelling) outside `styles/surface.css` and `styles/materials.css` (`backdrop-owner`); `will-change` in a file that declares `backdrop-filter`, uses `data-ca-blur` or `.ca-surface`; a literal `100vh|100dvh|100svh|100lvh` (use `var(--ca-vh)`); `backdrop-filter` declared before `-webkit-backdrop-filter` (Lightning CSS drops the standard one); `font-size` < 16px in an input rule (iOS focus zoom).
- Content images: `Image` (requires `width`/`height`; `alt=""` requires `decorative`; `priority` only on the LCP image).
- Fonts: `defineTheme({ fonts: { body: { family, src, weight, preload, fallback, fallbackMetrics } } })` generates `@font-face`, the fallback with `size-adjust` and the `<link rel="preload">`. A plain string still works.