Getting started

Choosing a component

Decision tables for the pairs and groups of components that look alike, so you pick the right one before writing code.

Several components solve a similar problem and differ in one rule. Find your situation in the table, use the component in the second column, and read its page for props. If a row does not fit, call get_component or search_demos before writing a wrapper, see Common workarounds.

Page layout

A route is one of these templates. They own the header, the scroll area, the footer and the mobile layout, so you fill snippets instead of building a wrapper.

Never: wrap a page in your own div with a title row and a footer bar. Never put AppShellLayout in public or auth routes, only in the signed-in layout.

Maps

Never: create a map in onMount yourself, or hand-measure the panel to offset the map.

Overlay

Every overlay below is a native <dialog> or a popover element in the browser top layer, so none needs a z-index. Pick by how the user got there and what they must answer.

Drawer has two docs pages and one component. Use Drawer in Feedback for the props table, the bottom side and the footer. Drawer (navigation) only shows the left menu and right settings panel patterns of the same component.

Drawer chromeless drops the header, close button and body padding for a side detail panel whose content brings its own header and scroll; name it with title, and add fullBleedBelow="md" to fill a phone screen. Sheet is modal. PageFrame sheet is a non-modal bottom sheet over a map, so the stage stays interactive.

Never: build a fixed full-screen panel by hand, set z-index on an overlay, or use Dialog for a confirmation that needs an explicit answer.

Table and lists

Never: hand-write a <table> with custom sticky CSS, or a mobile card view next to a table. SimpleTable does both.

Container

Layout primitives

All six render any element with as and take spacing as tokens, never inline style.

gap, p, px and py take a spacing step as a string: gap="4" is --ca-space-4. A number such as gap={16} is the old API. Row is deprecated: use Flex. PageShell gap is the exception and takes a number in px.

<script>
  import { Container, Flex, Grid, Stack } from "@codeatlasdev/ui";
</script>

<Container size="md">
  <Stack gap="4">
    <Flex gap="2" align="center" justify="between">…</Flex>
    <Grid columns={{ base: 1, md: 3 }} gap="4">…</Grid>
  </Stack>
</Container>

Pick one of many

Feedback

Buttons and type

Brazilian and formatted inputs

<script lang="ts">
  import { TextField } from "@codeatlasdev/ui";
  import { MoneyInput, PhoneField } from "@codeatlasdev/ui/forms";

  let name = $state("");
  let price = $state(0); // integer, minor unit
  let phone = $state(""); // E.164, empty while incomplete
</script>

<TextField label="Name" bind:value={name} />
<MoneyInput label="Price" bind:value={price} />
<PhoneField label="Phone" bind:value={phone} />

Setup path