# 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` |
| Brand icons (`caBrandPlugin`) | `@codeatlasdev/ui/vite` | `@resvg/resvg-js` and `png-to-ico` |
| `migrate` command | `bunx @codeatlasdev/ui migrate` | `typescript` |

`@sveltejs/kit` and `astro` are optional peers too: install the one your app uses. Icons come from `@lucide/svelte`, which the package already depends on.

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

| Flag | Effect |
|---|---|
| `--write` | Apply the proposed changes to existing files. Files that do not exist yet are always created. |
| `--dir <path>` | Project directory. Defaults to the current directory. |

When diffs are pending it ends with `N existing file(s) left untouched. Re-run with --write to 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). A file that already exists is never overwritten: `init` prints a diff and applies it 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 })`, 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 and `colorScheme.init()` in `onMount` | adds only the missing import or call |
| `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 |

`caErrorPlugin({ scaffold: true })` then creates `src/routes/+error.svelte` and `src/error.html` the first time Vite runs (dev or build), and never overwrites them. 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 })],
});
```

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 })],
});
```

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)` first in `integrations`, with its two imports | adds `caUI(theme)` unless `caUI(` is already there; reports `manual` when there is no `integrations: [` array |
| 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.

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). |
| `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) and `easing`: `"standard"`, `"emphasized"`, `"spring"`, `"linear"` or `"steps"`. |
| `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/astro";
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` is plain data, so `theme.ts` can import it in Node from `@codeatlasdev/ui/astro` (it is also exported from the root and from `@codeatlasdev/ui/kit`, which 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; }
```

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.

## 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, 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` | A plain `div.ca-shell__content` (not a landmark), so a `<main>` you render inside never nests another. Pass `mainId={null}` when your page renders `<main id="main" tabindex="-1">` yourself. |
| `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}>
  <!-- content region is the skip target; use <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`. English (`en.ts`) is the source of truth; `pt-BR.ts` is typed as `Messages`, so a missing key is a type error. A test checks that both locales have identical keys.

## 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). |
| `get_guide` | A documentation page as markdown, by slug (`getting-started/theming`) or title. Without a name it lists every guide. |

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

## 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 dynamic prop it cannot map is left as it was.

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

## 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 and og: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?, 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). |
| `twitter` | `{ card?, site? }` | - | `card` is summary_large_image when an og image is set, otherwise summary. `site` is the @handle. |
| `jsonLd` | `object \| object[]` | - | Structured data. Serialized with '<' escaped, so values cannot close the script tag. |
| `manifest` | `string` | - | URL of the web app manifest. |

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" }),
  ],
});
```

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`, then `src/generated/brand.ts` with their URLs. `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.

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

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" });
```

`@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` exists and registers it for you. The `$service-worker` module lists the hashed build files, static files and the app version, so the cache never serves stale assets after a deploy.

The pattern below 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.

## 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 |

---

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

### 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

---

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

`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"`. |
| `flush` | `boolean` | false | Removes all 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/). |
| `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}` (default) `{4}` `{5}` |
| `tinted` | `tone="brand"` |
| `glowing` | `glow` |
| `padding="24px"` | `p="6"` (a spacing step) |
| `title`, `headingLevel`, `headerActions`, `href`, `target`, `flush`, `full`, `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}` (default) `{4}` `{5}` |
| `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'` | 'button' | HTML button type. |
| `fullWidth` | `boolean` | false | Stretches the button to the width of its container. |
| `href` | `string` |  | Renders an anchor styled as a button. |
| `target` | `string` |  | Anchor target, used with href. |
| `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.

### States

Unchecked, checked and indeterminate.

### Disabled

### Without label

Bare checkbox for table rows or custom layouts.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `checked` | `boolean` | false | Bindable checked state. |
| `indeterminate` | `boolean` | false | Renders the mixed state. |
| `disabled` | `boolean` | false | Disables interaction. |
| `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. |
| `onchange` | `(checked: boolean) => void` |  | Called when the checked state changes. |

---

# 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. Like `Select`, it has no `name` prop and does not submit with a native form: 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.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | '' | Bindable selected value. |
| `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) => void` |  | Called when an option is selected. |

---

# 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=""`) keeps an accessible name from the localized `Copy` label. 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. |
| `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.

### Basic

Multiple files with a size limit and the selected count.

### Images only and disabled

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

### 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. |
| `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` the trigger is named by its `placeholder`. Arrow keys, Enter and Space open the list from the trigger, and Escape closes it. There is no `name` prop, so a `Select` does not submit with a native form: read `value` instead. `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. |
| `error` | `string` |  | Error message. Puts the select in the error state. |
| `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. |
| `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.

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

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` |  | Label text. |
| `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. |
| `class` | `string` |  | Extra classes on the root. |
| `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). |
| `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. Use [SegmentedControl](/docs/inputs/segmented-control/) when a choice is required. 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. type=&quot;multiple&quot; binds a string array.

### 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. |
| `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`). The background color is generated from the name, so the same person always gets the same color.

### With image

### Initials fallback

### Sizes

### Shape and status

### Avatar stack

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | undefined | Image URL. Initials are shown while loading or when loading fails. |
| `alt` | `string` | '' | Alt text. Initials are derived from it when no `fallback` is set. |
| `fallback` | `string` | undefined | Explicit initials. Overrides the ones 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. |
| `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 global search, column sorting, pagination and a column visibility toggle, 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

### 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. |
| `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. A column that cannot sort renders the plain title.

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

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

---

# 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. Focus returns to the trigger when a layer closes.

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.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `title` | `string` |  | Required. Dialog title and accessible name. |
| `description` | `string` |  | Supporting text below the title. |
| `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. |
| `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.

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

### Text lines

With rows, the last line is shortened to 60% for a natural paragraph.

### Card layout

### 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 image viewer 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" />
```

The image 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

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | false | Bindable open state. |
| `src` | `string` |  | Image URL. Required. |
| `alt` | `string` |  | Image description. Required. |
| `onclose` | `() => void` |  | Called after the viewer closes. |

---

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

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

---

# Dropdown Menu

Group: Navigation. URL: https://ui.codeatlas.com.br/docs/navigation/menu/

A floating action menu with items, labels and separators.

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

### Default

A button trigger with a label, items, a separator and a destructive item.

### 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 and separators. |
| `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. |
| `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. |
| `children` | `Snippet` |  | Item content, usually an icon and a label. |
| `class` | `string` | '' | Extra CSS classes. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` |  | Heading text. |
| `class` | `string` | '' | Extra CSS classes. |

`DropdownMenuSeparator` takes no props.

---

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

### Basic

Text and an action inside the popover.

### Form

A small form anchored to its trigger, aligned to the start.

### 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` |  | Popover content. |
| `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.

### Default

Three tabs with content panels.

### Controlled

The parent owns the active tab with bind:value.

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

---

# 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. 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` | `string` | per component | Element to render (`div`, `section`, `ul`, `nav`...). |
| `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">` | a class with `grid-template-columns: 2fr 1fr` (not migrated) |

---

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

### Anatomy

Rail (52px), panel (200px) 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.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `modules` | `NavModule[]` |  | Navigation modules. Each has id, label, icon, basePath, optional pathPrefixes and items (NavItem or NavSection). |
| `pathname` | `string` |  | Current location. Decides the active module and item. |
| `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. |
| `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, the skip link target. Pass `null` when your page renders its own `<main id="main" tabindex="-1">`. |
| `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. |

## 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, 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, label, unread badge, new dot 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 plain `<a>` with `aria-current="page"` when active. `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`, `isNew`, `shortcut`, `description`. Required. |
| `isActive` | `boolean` |  | Marks the row as the current page (`aria-current="page"`, active pip). Required. |
| `href` | `string` |  | Link target. Required. |
| `class` | `string` | '' | Extra class names. |

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `section` | `NavSection` |  | `label`, `items`, and optional `collapsible` (default `true`) and `defaultOpen` (default `true`). 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`, `EmptyState` titles default to `<h2>` (under the page `<h1>`). Pass `headingLevel` to `EmptyState` 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. |
| `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). |

---

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

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

---

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

---

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.
- **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 + 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:e2e` / `test:a11y` | Playwright against the static site (build + preview) |
| `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` uses a `div.ca-shell__content` as the `SkipLink` target (pass `mainId={null}` if the page renders its own `<main id="main" tabindex="-1">`, 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 })],
   });
   ```
   ```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.

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`, `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"; // = Partial<ThemeDefinition>

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`. **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: `packages/ui/src/lib/i18n/en.ts` (source of truth, grouped by component, e.g. `docs.search.placeholder`) and `pt-BR.ts` (typed as `Messages`: a missing key is a type error). Strings with a value are functions: `notificationBell.label(unread)`. Registry and `getMessages(locale, override?)` live in the rune-free `catalog.ts`.
- New text in a component: add the key to `en.ts` **and** `pt-BR.ts`, call `const t = useT();` at the top level of `<script>` (or of a `.svelte.ts` helper called at component init; `useT` 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. 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: `will-change` in a file with `backdrop-filter`; 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.