# 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 glass material system, 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 [bits-ui](https://bits-ui.com) 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, empty state and glass surface, with no CSS written.

## What you get

- **Pages, not primitives.** `AppList`, `AppForm`, `AppSettings`, `PageShell` and `AppShellLayout` bring layout, spacing and empty states.
- **Liquid Glass.** Five material tiers with real `backdrop-filter`, tuned for light and dark, with opaque fallbacks for reduced transparency.
- **Theme engine.** Eight OKLCH presets, brand presets from one hex color, four surface styles, and no flash on load.
- **Native on mobile.** Safe areas, keyboard handling, 44px touch targets, bottom sheets with swipe to dismiss, and browser chrome color that follows the page.
- **Accessible.** bits-ui behavior, axe-tested components, reduced motion and reduced transparency support.
- **Light.** Charts, DataTable and CodeSnippet are separate entry points with optional peers, so they stay out of your bundle unless imported.
- **Built for AI agents.** Closed prop vocabularies, typed props, `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, and prints a diff instead of overwriting any file that already exists. 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 |

Icons come from `@lucide/svelte`, which the package already depends on.

### Release channels

| Channel | Install | When to use it |
|---|---|---|
| `latest` | `bun add @codeatlasdev/ui` | Production. Semver: breaking changes only in a major. |
| `beta` | `bun add @codeatlasdev/ui@beta` | The next minor, feature-complete. Try it before it ships. |
| `alpha` | `bun add @codeatlasdev/ui@alpha` | The next major while it is still moving. Expect breaking changes between alphas. |

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

## SvelteKit

1. **Register the Vite plugin.** It bundles the ESM-only dependencies for SSR (`@tanstack/svelte-table`, `shiki`) and warns at build time if the theme script is not injected.

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

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

2. **Inject the theme script 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.

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

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

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";

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

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.

## Astro

Use the integration together with `@astrojs/svelte`. `caUI` injects the theme into the `<head>` of every page and handles the SSR bundling.

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

Import the stylesheet once in your base layout and add the viewport meta:

```astro
---
// src/layouts/Base.astro
import "@codeatlasdev/ui/styles/global.css";
---
<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" />
  </head>
  <body><slot /></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. In islands, call `colorScheme.init()` from one island that is always on the page, such as your header, or from a small script.

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";

export const theme: ThemeOptions = {
  presets: [{ id: "acme", color: "#2563eb" }],
  defaultPreset: "acme",
  defaultScheme: "system",
  defaultStyle: "glass",
  fonts: { body: "Geist, system-ui, sans-serif" },
  radius: 1,
  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"`. |
| `defaultStyle` | `"glass"` | `"glass"`, `"frosted"`, `"solid"` or `"flat"`. |
| `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` | `1` | Multiplier applied to the `--ca-radius-xs` to `--ca-radius-xl` scale. |
| `density` | `"comfortable"` | `"compact"` tightens card padding and page gaps. |
| `overrides` | `{}` | Raw `--ca-*` token overrides, per scheme (`light`, `dark`). |

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

## 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 |
|---|---|
| `glass` | Liquid Glass: strong blur and saturation, translucent tints. Default. |
| `frosted` | Less blur, calmer mesh background. |
| `solid` | No blur, opaque surfaces, no mesh background. Keeps soft shadows. |
| `flat` | No blur, no mesh, no drop shadows: separation comes from borders. |

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

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

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.components, ca.materials, ca.utilities;
```

Component styles and your app CSS are **unlayered**, so they always win over the package layers, regardless of specificity or import order. That makes overriding predictable:

```css
/* app.css: no !important needed */
:root {
  --ca-card-padding: 16px;
  --ca-radius-lg: 18px;
}
```

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`, `textarea`, `select`, `[contenteditable]`) to `max(16px, 1em)` under `(pointer: coarse), (max-width: 767px)`, with zero specificity (`:where()`) so an app can still opt a field out. Package controls read `--ca-input-font-size`, which does the same. 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 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 updates on theme changes, route changes and scroll. 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. Escape closes it, 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={() => (chatId = null)}>
  {#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. On wide screens it becomes an inline row.

```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 768px and a centered dialog from 768px 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 fast fling, animates with a spring, and 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 below 768px (`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, nav, tabs) 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.

Controls already apply `touch-action: manipulation` and a transparent tap highlight, grow to 44px under `(pointer: coarse)`, and scale 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 are built on [bits-ui](https://bits-ui.com), which provides the ARIA roles, keyboard handling and focus management of each pattern. The package adds tokens, motion and touch rules on top, and every component is tested with axe in a real browser.

## What you get

| Area | Behavior |
|---|---|
| Focus ring | A global `:focus-visible` outline in `--ca-focus-ring` (the brand color) with a 2px offset. Never remove it; change the token instead. |
| Overlays | `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `Popover` and menus trap focus, restore it on close, close on Escape and lock page scroll. |
| 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) 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-duration-fast`, `--ca-duration-base` and `--ca-duration-slow` become `0ms`, so every token-driven transition is instant. Components with JavaScript-driven motion check the `reducedMotion` store: `Sheet` disables its swipe 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);
}
```

## 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 inactive controls only, never for information.
- `--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

Components are tested with `vitest-browser-svelte` and axe-core. The helper in `packages/ui/tests/a11y.ts` provides `checkA11y` and a `toHaveNoViolations` matcher (this is the pattern used inside the repo):

```ts
import { render } from "vitest-browser-svelte";
import { checkA11y } from "../../../tests/a11y";

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

In your app, run axe on your routes in light and dark, and with an overlay open, using Playwright with `@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**. Call `setLocale` once, in your root layout, to change it:

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import { setLocale } from "@codeatlasdev/ui";

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

It runs on the server too, before the first render, so server-rendered HTML is already in the right language.

## Override phrases

The second argument is a deep partial of the catalog. It is merged over the chosen locale, so you only write the strings you want to change:

```ts
setLocale("en", { docs: { toc: "In this article" }, common: { copy: "Copy link" } });
```

A later call to `setLocale` 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

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

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.nextPage`, `fileUpload`, `dataTable` and `toast`. English (`en.ts`) is the source of truth; `pt-BR.ts` is typed against it, so a missing key is a type error. Both locales are tested to have identical keys.

Unknown locale codes throw:

```
[codeatlasdev/ui] unknown locale "fr" (expected en | pt-BR)
```

To ship another language today, use `setLocale("en", translatedOverrides)` with your full translation as the override object. The exported `Messages` type describes its shape.

## 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. When a test asserts Portuguese text, call `setLocale("pt-BR")` and reset with `setLocale("en")` in `afterEach`, so the module state does not leak between tests.

---

# 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. 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. Written in Portuguese. |

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) server that ships with the package. It reads the manifests generated from the component source at build time, 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 props (type, default, `bind:` or not, docs), snippets and public `ca-*` classes. The name is case-insensitive: `get_component("app list")` finds `AppList`. |
| `search_tokens` | `--ca-*` design tokens matching a name, value or section, with light and dark values. |
| `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) 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: `src/lib/theme.ts`, the theme hook or integration, the `global.css` import, `colorScheme.init()` in the root layout 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. 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` and `.astro` files, so only real references change (not strings or same-named identifiers from other packages). Today it renames the `BrandPreset` type to `PresetDefinition`.

## 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, Row, 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`, `Row` 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`, no `class:` directive on bits-ui components.
- 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.components, ca.materials, ca.utilities`), 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. `defineTheme({ fonts })` handles both. A font is either a plain stack string (as before) or a descriptor:

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

export const theme = defineTheme({
  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, // social images
  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?, imageWidth?, imageHeight?, locale?, localeAlternates?, siteName? }` | - | Open Graph. Image size defaults to 1200x630. |
| `twitter` | `{ card?, site? }` | - | Card is summary_large_image when an og image is set. |
| `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 when the final HTML has no `viewport-fit=cover` 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.

## 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` | `ogImageRoute` or a static file |

---

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

## Manifest

`manifest()` returns the manifest object. `theme_color` and `background_color` come from the same theme definition you give `caThemeHandle`, so the splash screen and the browser chrome match the first paint.

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

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: "/"` and `scope: "/"`. Pass `themeColor` or `backgroundColor` to override the derived colors.

Android crops other icons into a white tile. Keep the artwork of the `maskable` icon inside the central 80% of the canvas. `manifest()` warns when none is present.

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 |
|---|---|
| `apple-mobile-web-app-capable` | Opens without Safari chrome. |
| `apple-mobile-web-app-status-bar-style` | `black-translucent` (default) draws the page under the status bar. Needs `viewport-fit=cover`; pad with `var(--ca-safe-top)`. |
| `apple-touch-icon` | 180x180 PNG. 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 for inactive controls only.

### 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, so they follow the user's browser font size. Fonts are stacks: load Inter and JetBrains Mono yourself (for example with `@fontsource-variable`) or replace them in your theme.

```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 and small screens 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);
}
```

Light mode uses soft warm shadows, dark mode uses deeper black ones, so one token works in both. Glass surfaces rely on inset highlights and borders instead of drop shadows, 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/

Liquid Glass material tiers from ultra-thin translucency to opaque chrome, plus tint, glow and button variants.

Materials are CSS classes (`glass-ultra-thin`, `glass-thin`, `glass-regular`, `glass-thick`, `glass-chrome`) backed by `backdrop-filter`. `GlassSurface` applies them for you and can add a refraction layer.

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

<GlassSurface thickness="thick" tinted>Content</GlassSurface>
```

The surface style on `<html data-style>` changes every material at once: `glass` (default), `frosted` (less blur), `solid` and `flat` (no blur, no mesh). Switch it with `colorScheme.setStyle()`, see [Theming](/docs/getting-started/theming/#surface-styles). Browsers with `prefers-reduced-transparency: reduce` automatically 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.

### Tinted and glowing

glass-tinted adds an accent gradient, glass-glow adds a backlit halo.

### GlassSurface props

| Prop | Type | Default | Description |
|---|---|---|---|
| `thickness` | `'ultra-thin' \| 'thin' \| 'regular' \| 'thick' \| 'chrome'` | 'regular' | Material tier. |
| `tinted` | `boolean` | false | Adds an accent gradient (glass-tinted). |
| `glowing` | `boolean` | false | Adds a backlit halo (glass-glow). |
| `refraction` | `boolean` | true | Renders the LiquidGlass refraction layer behind the content. |
| `class` | `string` | '' | Extra classes. |
| `style` | `string` | '' | Inline style string, for dynamic custom properties only. |
| `children` | `Snippet` |  | Surface content. |

---

# Accordion

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

Vertically stacked collapsible sections backed by Bits UI, 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`, and Arrow, Home and End keys move between them. 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). 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. |

---

# Card

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

GlassCard content patterns: text card, stat cards, accent treatments and a built-in header.

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

<GlassCard title="Team" tinted>…</GlassCard>
```

These are composition patterns built on [Glass Card](/docs/surfaces/glass-card/), which owns the full prop list. Cards render as a link when `href` is set.

### Content card

### Stat cards

### Tinted and glowing

### Header and actions

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `thickness` | `'ultra-thin' \| 'thin' \| 'regular' \| 'thick' \| 'chrome'` | 'regular' | Glass thickness tier. |
| `tinted` | `boolean` | false | Adds the brand accent gradient. |
| `glowing` | `boolean` | false | Adds a backlit glow halo. |
| `title` | `string` | undefined | Header title. |
| `headerActions` | `Snippet` | undefined | Actions aligned to the end of the header. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Card content. |

---

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

A card built on GlassSurface with rounded corners and overflow clipping, the default container for content sections.

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

<GlassCard title="Overview" headerActions={actions}>…</GlassCard>
```

GlassCard is the primary surface of the library. Padding comes from `--ca-card-padding`; use `flush` for content that touches the edges, such as tables, images and code. Backdrop blur needs something behind the card, which is why the demos sit on a gradient.

### Default

### Tinted and glowing

### Thickness tiers

### Flush

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `thickness` | `'ultra-thin' \| 'thin' \| 'regular' \| 'thick' \| 'chrome'` | 'regular' | Glass material tier. |
| `tinted` | `boolean` | false | Adds the brand accent gradient overlay. |
| `glowing` | `boolean` | false | Adds a backlit glow halo. |
| `href` | `string` | undefined | Renders the card as a link. |
| `target` | `string` | undefined | Link target when `href` is set. |
| `padding` | `string \| number` | undefined | Overrides `--ca-card-padding`. Numbers are pixels. |
| `flush` | `boolean` | false | Removes all padding. |
| `full` | `boolean` | false | Sets `width: 100%`. |
| `title` | `string` | undefined | Header title. |
| `headerActions` | `Snippet` | undefined | Actions aligned to the end of the header. |
| `class` | `string` | '' | Extra class names. |
| `children` | `Snippet` | undefined | Card content. |

---

# Glass Surface

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

The foundational glass material component with configurable thickness, tint, glow and optional refraction.

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

<GlassSurface thickness="thin" tinted>…</GlassSurface>
```

GlassSurface is the low-level material. Prefer [Glass Card](/docs/surfaces/glass-card/) for content containers. Extra attributes are forwarded to the root element. Do not add `will-change: transform` to a glass element or its ancestors, since it breaks `backdrop-filter`.

### Interactive

### All tiers side by side

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `thickness` | `'ultra-thin' \| 'thin' \| 'regular' \| 'thick' \| 'chrome'` | 'regular' | Material tier controlling blur and opacity. |
| `tinted` | `boolean` | false | Adds the brand accent gradient overlay. |
| `glowing` | `boolean` | false | Adds a backlit glow halo. |
| `refraction` | `boolean` | true | Renders the LiquidGlass SVG refraction overlay. |
| `class` | `string` | '' | Extra class names. |
| `style` | `string` | '' | Inline style string. |
| `children` | `Snippet` | undefined | Slot content. |

---

# 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, sets aria-busy and disables the button. Adds ca-btn--loading. |
| `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. |
| `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 built on Bits UI 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, built 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 at least a `placeholder`) so the listbox has an accessible name.

### 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, the arrows move by day, 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.

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

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

### PhoneField and CepField 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. |

### Exports

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

BRL currency field. The bound value is integer cents and the display is formatted as you type.

```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 number of cents, 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.

### Helpers

Pure functions exported from @codeatlasdev/ui/forms.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` | 0 | Bindable amount in integer cents. |
| `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` | centsToDisplay(0) | 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 built on Bits UI with roving focus and arrow-key navigation.

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

Arrow keys move focus and selection inside the group, Tab leaves it. The group has no visible title of its own, so wrap it in a `fieldset` with a `legend` when the choice needs a heading.

### Vertical

The default layout.

### Horizontal

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

### Disabled

Disable a single item, or the whole group.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | '' | Bindable selected value. |
| `items` | `RadioItem[]` |  | Options: { value, label, disabled? }. |
| `orientation` | `'vertical' \| 'horizontal'` | 'vertical' | Layout direction and arrow-key axis. |
| `disabled` | `boolean` | false | Disables the entire 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 built on Bits UI with keyboard navigation and a glass content panel.

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

### States

Disabled options, description, error and a disabled select.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Bindable selected value. |
| `options` | `Array<{ value: string; label: string; disabled?: boolean }>` |  | Option items. |
| `placeholder` | `string` | 'Select…' (localized) | Text shown when no value is selected. 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 built on Bits UI 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. |

---

# Switch

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

Toggle control for binary on/off settings, built on Bits UI.

```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, glass styling 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 floats when the field has a value or a placeholder. `description` is hidden while an `error` is shown. 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. Also floats the label. |
| `rows` | `number` | 4 | Initial visible row count. |
| `minRows` | `number` |  | Minimum rows for the min-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. |
| `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 (blur). |
| `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, roving focus and arrow-key navigation.

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

<ToggleGroup type="multiple" aria-label="Text formatting" bind:value={format} items={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. 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.

### useForm(initialValues, options?)

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

### Returned form state

| 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`. Alerts are announced by assistive technology as status messages.

### 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 backed by Bits UI 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 } 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. Add an accessible label to the wrapped control, since the indicator itself is visual.

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

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

### StatusChip 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. |
| `srcset` | `string` | undefined | Candidate renditions. Also set on the preload link when `priority` is on. |
| `sizes` | `string` | undefined | Rendered width hint for `srcset`. |
| `loading` | `'lazy' \| 'eager'` | 'lazy' ('eager' with priority) | Overrides the default. |
| `decoding` | `'async' \| 'sync' \| 'auto'` | 'async' | Decode hint. |
| `class` | `string` | '' | Extra class names. |

---

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

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

---

# 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 `Row` with `align="center"` or 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`.

### 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 item is clicked. |
| `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. |

---

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

### 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 when the page changes. |
| `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, backed by Bits UI.

```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, touch momentum and keyboard scrolling are preserved.

### 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 adds a sticky header, hover rows and an optional card layout on small screens.

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

<SimpleTable responsive="cards">
  <thead>…</thead>
  <tbody>…</tbody>
</SimpleTable>
```

SimpleTable styles plain `thead` and `tbody` markup. For search, sorting and pagination use [DataTable](/docs/display/data-table/). In `cards` mode the header row stays available to screen readers.

### Default (scroll)

### Cards on mobile

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `responsive` | `'scroll' \| 'cards'` | 'scroll' | `cards` turns each row into a card below the md breakpoint (900px). Requires `data-label` on each `td`. |
| `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. |

---

# Tooltip

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

Floating label shown on hover and focus, backed by Bits UI, 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 too, but never put essential information only in a tooltip, because touch devices have no hover.

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

---

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

Built on the Bits UI Dialog: focus is trapped, Escape closes and the panel carries `aria-modal`. 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 md. |
| `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. |

---

# 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. 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 is rethrown. |
| `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 } 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 768px.

```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 768px the sheet rises from the bottom edge with a drag handle, safe-area padding and rounded top corners. From 768px up it renders as a centered dialog. Focus trap, focus restore, Escape, overlay dismissal and scroll lock come from the Bits UI Dialog.

**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 768px. 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 `aria-busy="true"`) rather than on each placeholder.

### 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` and `aria-valuemax`. 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. The fill is clamped between 0 and 100%. |
| `indeterminate` | `boolean` | false | Plays the shimmer animation when progress is unknown. |
| `label` | `string` |  | Accessible aria-label for screen readers. |
| `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.

```svelte
<!-- +layout.svelte: mount once -->
<script>
  import { Toaster } from "@codeatlasdev/ui";
</script>
<Toaster />

<!-- anywhere -->
<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"`. Toasts stack in the bottom right corner. 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.

### API

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

---

# 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/). It registers `Cmd+K` and `Ctrl+K` itself, so mount it once near the root. Results are a listbox: arrow keys move the selection, Enter confirms 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 built on Bits UI with items, labels and separators.

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

<DropdownMenu>
  {#snippet triggerChild(props)}<Button {...props}>Open menu</Button>{/snippet}
  <DropdownMenuItem onclick={edit}>{#snippet children()}Edit{/snippet}</DropdownMenuItem>
  <DropdownMenuSeparator />
  <DropdownMenuItem variant="destructive" onclick={remove}>{#snippet children()}Delete{/snippet}</DropdownMenuItem>
</DropdownMenu>
```

Keyboard support comes from Bits UI: Enter or Space opens the menu, arrows move, Escape closes and focus returns to the trigger. 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.

### Default

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

### Icon trigger

An IconButton trigger. IconButton needs an aria-label.

### DropdownMenu

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

### DropdownMenuItem

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

---

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

Built on the Bits UI Popover: Escape closes it, a click outside dismisses it and focus returns to the trigger. 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 backed by Bits UI, 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 the panels use the `tabpanel` role. Each `TabsTrigger` and `TabsContent` pair must share a `value`.

### Default

Three tabs with content panels.

### Controlled

The parent owns the active tab with bind:value.

### Tabs

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Bindable active tab value. |
| `onchange` | `(v: string) => void` |  | Fires when the active tab changes. |
| `children` | `Snippet` |  | TabsList and TabsContent children. |
| `class` | `string` | '' | Extra classes on the root. |

### TabsTrigger

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

### TabsContent

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` |  | Required. Shown while the matching trigger is active. |
| `children` | `Snippet` |  | Panel content. |
| `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 and is not a link.

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

A sliding panel anchored to the left or right edge, used for navigation and settings.

```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. 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, keyboardAware, primeKeyboard } 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.

### clickOutside

Calls the handler for every click that lands outside the element.

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

### longpress

Dispatches a longpress event after the pointer is held for the given duration.

### Actions

| 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 dispatches a copy CustomEvent with the text as detail. |
| `longpress` | `Action<HTMLElement, number>` |  | Dispatches a longpress CustomEvent after the pointer is held for the given milliseconds (default 500). |
| `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 glass, 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 a glass background, 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. |

---

# 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>
  import { AppShellLayout, type NavModule } from "@codeatlasdev/ui";
  import { goto } from "$app/navigation"; // or any router
  import { page } from "$app/state";

  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. 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 destination path when the rail, panel or bottom navigation is used. |
| `defaultModule` | `number` | 0 | Module index used before any navigation matches. |
| `persistPanel` | `boolean` | true | Persists the open or closed state of the panel in localStorage. |
| `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. |

---

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

### 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` | 28 | Vertical gap between the header and the content, in px. |
| `maxWidth` | `string` | '1280px' | Maximum width of the content column. |
| `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} />
```

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

---

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

---

# 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`). Every chart takes data and a few semantic props. There are no color, font or style props on purpose: the palette follows the active preset, tooltips use the glass material, and charts re-theme when the color scheme, preset or surface style changes. Chart components 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.

### Shared 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 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 | Animates the displayed value between updates. |
| `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.

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

### DocsShell

| 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. |
| `children` | `Snippet` |  | Required. Page content. |

### DocsNav

| Prop | Type | Default | Description |
|---|---|---|---|
| `groups` | `DocsNavGroup[]` |  | Labelled groups of { href, title, badge? } links. |
| `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. |

### TableOfContents

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

### DocsSearch

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

### Prose blocks

| Prop | Type | Default | Description |
|---|---|---|---|
| `CodeTabs.sync` | `string` | 'lang' | Groups with the same key follow the chosen label. An empty string disables sync. |
| `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. |