# Admin table (/docs/blocks/admin-table)

The screen behind "Settings → Team" in most SaaS apps, inside the app's shell: header, sidebar (an icon rail on tablets, a menu drawer on phones) and the content area. Everything works: filter by role, team and status, sort any column, select rows across pages, change roles in bulk, edit someone in a drawer, invite a new member and delete with a confirmation. Changes are kept in local state until you reload the page.

<BlockPreview name="block-admin-table/screen" height={860} />

## Components [#components]

<BlockUses names="AppShell, Sidebar, DataTable, InputGroup, Select, Combobox, Menu, Drawer, AlertDialog, Toast, Badge, Avatar, Switch, EmptyState, Field, Button, Typography" />

## Behavior [#behavior]

- **Search and filters.** The search box matches names and emails as you type. Role and status are `Select`s with an "All" option; team is a `Combobox`, so you can type to find it in a longer list. On a phone, the filters move into a bottom drawer behind a Filters button that counts the active ones. Clear filters appears when any filter is on, and the line above the table says how many members match.
- **Sorting.** Every column with data sorts on click: ascending, descending, then back to unsorted. The table starts sorted by name.
- **Selection and bulk actions.** Rows have checkboxes, and the header one selects every row that matches the filters, on every page. With a selection, a bar offers Change role, Suspend and Delete. Changing a filter clears the selection, so a bulk action never reaches rows you can't see.
- **Pagination.** Ten rows per page. A new filter goes back to page 1.
- **Row menu.** Edit, Suspend or Reactivate, and Delete for one member.
- **Edit and invite in a drawer.** The same form edits a member or invites a new one. It checks the name, the email format and that no one else uses the email.
- **Delete with a confirmation.** An `AlertDialog` names who is being deleted and what happens next. Every change ends with a toast.
- **Narrow screens.** Below 720px the Team and Last active columns are dropped; on a phone, role and status move under the name. If it still doesn't fit, the table scrolls sideways.

## Accessibility [#accessibility]

- The table has a name, and sortable headers are buttons that set `aria-sort`, so screen readers say which column is sorted and in which order.
- Every checkbox and row menu is named after its member ("Select Aline Prado", "Actions for Aline Prado"); the selection count and the "Showing 12 of 18" line are live regions.
- The drawer and the dialog trap focus and return it to the menu that opened them. After a delete, the row is gone, so focus moves to the page heading instead.
- When the drawer form fails, focus moves to the first field with an error, and the error is read with it.

## Use the code [#use-the-code]

The Code tab shows the whole screen as one file, with `@camaleo/react` and `lucide-react` as its only dependencies (`DataTable` brings TanStack Table with it). The members are fixed data: replace them with your API, and move the filtering and paging to the server when the list gets long (`DataTable` takes `pageCount`, `totalRows` and controlled `sorting` for that).


# Sign in (/docs/blocks/auth)

The account screens most products need on day one, in one file. Sign in and Create account are tabs; Forgot password, the one-time code after sign-up, the "check your email" step and the signed-in state are views of the same card. On wide screens a brand panel with a customer quote sits beside the form; on narrower ones the form stands alone. Everything validates, and the test code for the verification step is shown under the field.

<BlockPreview name="block-auth/screen" height={860} />

## Components [#components]

<BlockUses names="Tabs, Field, InputGroup, OtpField, Checkbox, Link, Button, Card, Avatar, Typography" />

## Behavior [#behavior]

- **Sign in.** Email and password are required; the password has a show and hide button. "Keep me signed in" is a plain checkbox you can wire to your session length.
- **Create account.** Name, email, a password with three rules that tick as you type (8 characters, a letter and a number, not your email) and the terms checkbox. Submitting goes to the code step.
- **One-time code.** Six cells that take typing, Backspace and a pasted code. A short code and a wrong code get different errors. "Send a new code" waits 30 seconds between sends and says so on the button.
- **Forgot password.** It asks for the email and then answers the same way whether or not the account exists, so the form can't be used to find out who has an account.
- **Magic link and passkey.** The two buttons under "or" stand in for passwordless sign-in. They use generic icons on purpose: if you add Google or Apple sign-in, follow each provider's own button guidelines.

## Accessibility [#accessibility]

- Every step change moves focus to the card heading, so screen reader users hear "Check your email" or "Reset your password" instead of silence. Switching tabs leaves focus on the tab, as the tabs pattern expects.
- A failed submit moves focus to the first field with an error; the error is linked to the field and read with it.
- The password rules are said once in the field's description. The ticking checklist under it is visual only (`aria-hidden`), so it doesn't repeat itself on every keystroke.
- The show-password button changes its name ("Show password", "Hide password") instead of using `aria-pressed`. Each code cell after the first is named "Digit 2 of 6" and so on.
- The resend button uses `aria-disabled` while it counts down, so it keeps focus and stays in the Tab order.
- `autocomplete` is set on every field (`username`, `current-password`, `new-password`, `one-time-code`), so password managers and SMS code autofill work.

## Use the code [#use-the-code]

The Code tab shows the whole screen as one file, with `@camaleo/react` and `lucide-react` as its only dependencies. The `wait` function stands in for your auth server: replace it with your requests, and replace `DEMO_CODE` with a check on the server. Never decide on the client whether a code or a password is right.


# Checkout (/docs/blocks/checkout)

A one-page checkout that keeps the order summary in view while people move through shipping address, delivery, payment and review. Fill it in, break it on purpose and press Continue: every step checks its own fields before letting you move on. The card field is a demo; nothing is sent anywhere.

<BlockPreview name="block-checkout/screen" height={940} />

## Components [#components]

<BlockUses names="Stepper, Card, Field, Select, RadioGroup, ErrorSummary, DataList, Badge, Button, Typography, Separator" />

## Behavior [#behavior]

- **Validation per step.** Continue checks only the fields of the current step. The errors appear after the first failed attempt and then update as you type, so fixing a field clears its message without another click.
- **Postal code by country.** The format hint and the check follow the country you pick: `01310-100` for Brazil, `94103` for the United States, `1100-148` for Portugal, `M5V 2T6` for Canada.
- **Card fields format as you type.** The number is grouped in fours and checked with the Luhn checksum, the expiry gets its slash and must not have passed, and the security code takes 3 or 4 digits. `autocomplete` tokens (`cc-number`, `cc-exp`, `cc-csc`) let browsers and password managers fill them.
- **Delivery changes the total.** The radio cards are a real `RadioGroup`: the summary and the Pay button update with the shipping price.
- **Promo code.** `CAMALEO10` takes 10% off the items; any other code shows an error under the field.
- **Review and edit.** The review step lists what you entered, with an Edit button that jumps back to that step. Pay shows a loading state, then the confirmation replaces the form.

## Accessibility [#accessibility]

- After a failed Continue, focus moves to the `ErrorSummary` at the top of the step; each link in it moves focus to its field.
- When the step changes, focus moves to the step heading, which reads "Step 2 of 4: Delivery". The `Stepper` marks the current step with `aria-current="step"`, and finished steps say "done" to screen readers.
- Every field has a visible label, and hints and errors are linked to it, so they are read when the field gets focus.
- The confirmation heading takes focus when it replaces the form, so keyboard and screen reader users don't lose their place.

## Use the code [#use-the-code]

The Code tab shows the whole screen as one file. It needs `@camaleo/react` and `lucide-react`, and nothing else: the validation is a plain function you can swap for your schema library. Replace the fixed cart and prices with your data, and send the payment fields to your provider's own components (Stripe Elements, Adyen, Pagar.me) instead of your server: card numbers should never touch it.


# Sales dashboard (/docs/blocks/dashboard)

<BlockPreview name="block-dashboard/screen" height={820} />

## Built with [#built-with]

<BlockUses names="AppShell, Sidebar, Drawer, SearchInput, IconButton, Avatar, ToggleGroup, Stat, Card, Meter, DataTable, Badge, NativeSelect, Heading, Text" />

## Behavior [#behavior]

- **Three layouts by width.** The shell measures itself: a full sidebar from 1000px, a rail of icons from 640px, and below that a menu button that opens the same navigation in a `Drawer`. Try the Tablet and Phone widths above. In your app, a media query on the window does the same job.
- **Period filter.** 7, 30 or 90 days changes the stats, their deltas and the chart; 90 days switches the chart to weekly bars.
- **No chart library.** The bars are plain elements sized in percent and colored with `--cml-accent` and `--cml-brand-300`, so the chart follows the skin and the brand color. Grid lines mix `--cml-fg` at low opacity, so they stay faint even in skins whose border is solid black. Swap in your chart library when you need axes and tooltips.
- **Orders.** The channel filter narrows the `DataTable`; the table sorts by any column, pages by 5 and shows an empty state when a channel has no orders.
- **Good and bad news.** For the refund rate, going down is good: `StatDelta` gets `sentiment="positive"` with `trend="down"`, so the color matches the meaning.

## Accessibility [#accessibility]

- The header, sidebar and content are a `header`, an `aside` with a labelled `nav`, and the page's `main`. On this page the content renders a `div`, because the docs already have a `main`.
- The chart's bars are hidden from screen readers; the card description gives the best day and its revenue in words.
- Period buttons are a `ToggleGroup` with full names ("Last 30 days") as their accessible names, not just "30d".
- Sidebar items in the rail keep their names (and a `title` tooltip), and the current page has `aria-current="page"`.


# Inbox (/docs/blocks/inbox)

A three-pane inbox: folders, the conversation list and the message. It follows its own width, not the window's: at tablet width the folders move into a select above the list, and on a phone the list and the message take turns on screen. Try it at each width with the toggle above the preview.

<BlockPreview name="block-inbox/screen" height={720} />

## Components [#components]

<BlockUses names="Toolbar, Checkbox, InputGroup, Select, EmptyState, Avatar, Badge, Kbd, Tooltip, Toast, Field, Button, Typography" />

## Behavior [#behavior]

- **Unread state.** Unread conversations have a bold sender and subject and a bar in the accent color. Opening one marks it as read; the folder counts update.
- **Selection.** Each row has a checkbox, and the one above the list selects every visible row (it shows a dash when only some are). The toolbar acts on the selection: Archive, Delete and Mark as read or unread. In Archive and Trash, Archive becomes Move to Inbox.
- **Undo.** Moving conversations shows a toast with an Undo button that puts them back where they were.
- **Search.** The search box filters the current folder by sender, subject and preview as you type, ignoring accents ("julia" finds "Júlia"). When nothing matches, an empty state says so and offers to clear the search.
- **Reading pane.** With room for both panes, the first conversation is open from the start, and archiving or deleting it opens the next one. The message shows its sender, date and body, with the same actions in a toolbar and a reply box that checks it isn't empty before sending.
- **Compose.** Compose (in the folder column, or above the list on narrower screens) opens a new message in the reading pane; it checks the recipient's email and that the message isn't empty.
- **Empty folders.** An empty Inbox says you're caught up; Archive and Trash say what ends up there.

## Accessibility [#accessibility]

- The list uses a roving tab stop: Tab enters the list once, on the last row you were on. <kbd>↑</kbd> and <kbd>↓</kbd> move between rows, <kbd>Home</kbd> and <kbd>End</kbd> jump to the ends, <kbd>X</kbd> selects the focused row and <kbd>Enter</kbd> opens it. With a keyboard and room to spare, the keys are listed under the list and linked to it with `aria-describedby`; on touch screens and phones the hint is hidden. The focused row gets the skin's focus ring.
- Unread rows start with a hidden "unread" so screen readers hear the state, not just the bold text. The open conversation has `aria-current`.
- Each checkbox is named after its conversation ("Select Marina Costa: Brand guidelines, version 3"), and the icon buttons in the toolbars have names and tooltips.
- When rows disappear (archived or deleted), focus moves to the folder heading instead of being lost. On a phone, opening a message moves focus to its subject, and Back returns it to the row.
- The selection count and the toasts are announced through live regions.

## Use the code [#use-the-code]

The Code tab shows the whole screen as one file, with `@camaleo/react` and `lucide-react` as its only dependencies. Messages are fixed data and the folder of each one lives in local state; swap both for your API. The `useWidth` hook at the top is what lets the layout follow its own box, so it also works inside a resizable panel.


# Examples (/docs/blocks)

## Marketing [#marketing]

<BlockGallery group="marketing" />

## App [#app]

<BlockGallery group="app" />

## Commerce [#commerce]

<BlockGallery group="commerce" />

## Account [#account]

<BlockGallery group="account" />


# Product landing (/docs/blocks/landing)

<BlockPreview name="block-landing/screen" height={900} />

## Built with [#built-with]

<BlockUses names="Heading, Text, Badge, Button, Link, Menu, IconButton, Card, Stat, Progress, Rating, Avatar, Accordion, Field, Input, Separator" />

## Behavior [#behavior]

- **Header.** From 760px the links sit in the header; below that they move into a `Menu` behind a button, and only the main call to action stays visible.
- **Hero.** The product glimpse on the right is made of the same `Stat`, `Progress` and `Badge` you'd use in the app, so it changes with the skin. It is decorative and hidden from screen readers.
- **Color from tokens.** The washes behind the hero, the icons and the closing band mix `--cml-accent` with transparency, so a new brand color repaints the page.
- **Sizes that follow the width.** Headings and spacing use `clamp()` with `cqi` units, and every grid is `auto-fit`, so the page needs no breakpoints. Outside a size container, `cqi` falls back to the viewport.
- **Sign-up.** The closing form checks the email on submit, shows the error under the field and replaces itself with a confirmation.

## Accessibility [#accessibility]

- One `h1` in the hero, an `h2` per section (the testimonial's is visually hidden) and `h3` for cards, FAQ questions and footer columns.
- The header and footer navigations have distinct names, and in-page links point at the sections by `id`.
- The rating is one image named "Rated 5 of 5", not five separate stars.
- The FAQ uses `Accordion`, so each question is a button inside a heading with `aria-expanded`.


# Pricing (/docs/blocks/pricing)

<BlockPreview name="block-pricing/screen" height={900} />

## Built with [#built-with]

<BlockUses names="Badge, Heading, Text, ToggleGroup, Toggle, Card, Button, Table, Accordion, VisuallyHidden" />

## Behavior [#behavior]

- **Monthly or yearly.** The billing switch is a `ToggleGroup` holding one value. Pressing the active option again keeps it, so the page never shows no price. Yearly prices show the per-month amount and the yearly total under it.
- **One highlighted plan.** The popular plan gets an accent outline, a solid button and a badge; the other two use outline buttons, so there is one obvious next step.
- **Comparison table.** Rows are features and columns are plans. Under 560px a plan switcher shows one plan next to the features, so no column hides off-screen.
- **Layout.** The page measures its own width: three plans side by side from 700px, one per row below. Never two plus an orphan, which reads like a missing plan.

## Accessibility [#accessibility]

- A visually hidden live region says "Showing yearly prices" when the switch changes, because the prices change somewhere else on the page.
- Each plan button reads its plan ("Start a 14-day trial, Team"), so a list of buttons still makes sense.
- Check and dash icons in the table are hidden from screen readers and carry the text "Included" or "Not included"; the feature names are row headers.
- The FAQ triggers are `h3` headings under the "Questions about billing" `h2`, set with `AccordionTrigger level`.


# Account settings (/docs/blocks/settings)

<BlockPreview name="block-settings/screen" height={820} />

## Built with [#built-with]

<BlockUses names="AppShell, Sidebar, Drawer, Tabs, Card, Avatar, Button, Field, Input, Textarea, NativeSelect, Switch, Separator, PasswordInput, OtpField, Badge, AlertDialog, Alert, Heading, Text" />

## Behavior [#behavior]

- **Inside the app.** Settings live in the same `AppShell` as the sales dashboard: a sidebar from 1000px, a rail of icons from 640px, a `Drawer` below. Sections are tabs; under 640px a select picks the section, so no tab hides off-screen. Try the Phone width above.
- **Profile.** Upload photo opens the file picker and shows the image in the `Avatar` at once (an object URL; send the file to your server on Save). The bio counts down its 160 characters. Save validates name and email and confirms in a status line.
- **Notifications.** Each switch is a whole-row label, so the title and hint toggle it too. They save as you switch, which the footer says.
- **Security.** The password form checks the current password, the new password's rules and that the confirmation matches. Turning on two-factor shows the setup key and an `OtpField`; Verify needs all 6 digits, then the badge turns to On.
- **Danger zone.** Delete account opens an `AlertDialog` whose delete button stays disabled until you type `marina`. Confirming swaps the card for a warning with an undo.

## Accessibility [#accessibility]

- Arrow keys move between tabs and Enter opens one. Each section starts with a visually hidden `h2` (the tab or the select already shows its name), and the cards inside use `h3`.
- Saved and error messages are in `role="status"` regions or tied to their fields with `FieldError`, so screen readers hear them.
- The OTP cells are named "Digit 2 of 6", and the first takes the field's label.
- The `AlertDialog` traps focus, starts on its first control and returns focus to the trigger when it closes.


# Multi-step signup (/docs/blocks/signup)

<BlockPreview name="block-signup/screen" height={820} />

## Built with [#built-with]

<BlockUses names="Stepper, Card, Avatar, Field, Input, PasswordInput, InputGroup, RadioGroup, NativeSelect, Checkbox, ErrorSummary, DataList, Button, Heading, Text, Link" />

## Behavior [#behavior]

- **Brand panel.** From 860px a panel in the brand color sits beside the form, with the reasons to sign up and a customer quote; narrower, the form stands alone with the logo above it.
- **Validation per step.** Continue checks only the current step. Errors appear after the first Continue on that step, then update as you type, so a fixed field stops being red at once.
- **Error summary.** A failed Continue shows an `ErrorSummary` with one link per problem; each link moves focus to its field. The step turns red in the Stepper until it is fixed.
- **Address from the name.** The workspace address follows the name ("Café Serra Azul" → `cafe-serra-azul`) until you edit it yourself.
- **Review.** The last step lists everything entered, with an Edit button per section that jumps back to it. Values are kept when you move between steps.
- **Success.** Creating the workspace replaces the form with a confirmation that repeats the email address.

## Accessibility [#accessibility]

- Moving to a new step puts focus on its heading, and a failed Continue puts it on the error summary, so a screen reader starts in the right place.
- The Stepper is an ordered list; the current step has `aria-current="step"` and finished steps say "completed".
- Every error is also in the field's `FieldError`, tied to the input, and the summary title says how many problems there are.
- The form uses `noValidate`, so the browser's own bubbles don't compete with the summary; `autoComplete` values let password managers fill the account step.


# Changelog (/docs/changelog)

## 1.0 — Unreleased [#10--unreleased]

1.0 will be the first version on npm. It is being finished now: the documentation site (this one), a last pass on the library and the release setup. Until then, the packages are at `0.0.0` and the entries below are the history of the repository.

## Skin polish [#skin-polish]

<p className="gb-when">30 Oct 2026 · styles</p>

- `material`: vertical tabs get a side indicator instead of the bottom underline.
- `glass`: the lines between future steps of a `Stepper` stay visible in light mode.
- `neubrutalism`: text placed directly in an `Alert` keeps 4.5:1.
- `progressive`: the highlighted danger item of a dark menu reaches 4.5:1 (it was 4.43:1).
- The `Drawer` × sits on the title line in every skin, also when there is a description.
- The `Slider` fill is centred on its track (it was 1 px off in `editorial`, `y2k`, `neumorphism` and `retro`).
- `retro`: the `AppShell` gets a window bevel. `neumorphism`: a softer light shadow.

## Menus, steppers, tables and more [#menus-steppers-tables-and-more]

<p className="gb-when">30 Oct 2026 · library</p>

- **Overlays.** Radio items and submenus in `Menu` and `ContextMenu`, checkbox items in `ContextMenu`, and Tab closes it. `Toggletip` no longer announces a dialog. A scrolling `DrawerBody` takes focus. A tall `Popover` is capped to the viewport. Toasts map the `loading` and `error` types and respect `limit`. Ctrl+K no longer opens the `CommandPalette` from another text field.
- **Display.** `sentiment` on `StatDelta`, for metrics where down is good. `EmptyStateTitle` takes `as`. `ProgressCircle` announces its value text. New `TableCaption` and `TableFooter`. A card can become one big link. `CodeBlock` scrolls as a named region and highlights comments per language. `Carousel` follows the tabs pattern.
- **Navigation.** `Stepper` gets `activeStep`, an error status and a styled `StepSeparator`. New `ToolbarInput`, and Home/End in toolbars. A tabs list scrolls when the tabs don't fit. `AccordionTrigger` takes a heading level. New `BreadcrumbEllipsis`.
- **App structure.** New `AppShellBody`, `render` on `AppShellContent` and `SidebarItem`, Enter collapses a `Splitter` panel, `ScrollArea` works with only a `max-height`, `VisuallyHidden` can show on focus.
- **Forms.** `RadioGroup` and `Slider` values are typed. `Slider` passes value text to its thumbs and has a vertical layout. `NativeSelect` joins `Field`. `NumberField` shows a decimal keypad for decimal steps. `OtpField` errors reach every cell. `TagsInput` no longer drops a repeated tag without telling `onValueChange`. `Checkbox` and `Rating` put the `id` on the focusable element.

## Missing tokens, stable slots and translated texts [#missing-tokens-stable-slots-and-translated-texts]

<p className="gb-when">30 Oct 2026 · library</p>

- Four tokens that components used but nobody defined are now in `tokens.css`: `--cml-border-subtle`, `--cml-item-hover`, `--cml-surface-subtle` and `--cml-motion-duration`.
- `data-slot` comes after `{...props}` in 183 places, so `render={<Button />}` keeps the button's slot and look.
- New `MessagesProvider`, `useMessages`, `Message` and the `en` and `ptBR` sets. The built-in texts of 23 components come from it; props still win. See [Languages & RTL](/docs/guides/i18n).

## A page for every component [#a-page-for-every-component]

<p className="gb-when">28–30 Oct 2026 · docs</p>

Every component got its own page, in English and Portuguese: a playground, 6 to 9 live examples, real compositions, do/don't pairs, props generated from the types, styling hooks and keyboard notes. They went group by group, from actions and forms to layout and app structure.

Writing them found and fixed bugs on the way, among them: 12-hour times breaking hydration, an indeterminate `Progress` that looked complete, `NavigationMenu` panels opening empty, `CommandPalette` arrows following the wrong order, `Stack` inside `Stack` inheriting the parent's gap, and focus falling to `<body>` on the last page of a `Pagination`.

## The documentation site [#the-documentation-site]

<p className="gb-when">27–28 Oct 2026 · docs</p>

- Bilingual site with English at the root and Portuguese under `/pt-br`.
- The "preview in" bar: one skin, mode and brand for every preview, saved between visits.
- Previews with a Code tab that reads the example's own file, props tables generated from the types, and a page checker that runs axe in 4 skins, both modes, three widths and both languages.
- `Drawer` popup wrapped in its viewport, which removed a Base UI warning.

## Advanced forms, dates, data and app structure [#advanced-forms-dates-data-and-app-structure]

<p className="gb-when">27 Oct 2026 · library</p>

- **Advanced forms:** `PasswordInput`, `SearchInput`, `InputGroup`, `OtpField`, `TagsInput`, `Dropzone` with `FileList`, `Rating`, `Chip` and `ErrorSummary`.
- **Dates**, on React Aria: `Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `DateField` and `TimeField`, joined to `Field`.
- **Data display:** `DataTable` (TanStack Table), `Stat`, `DataList`, `Timeline`, `EmptyState`, `ProgressCircle`, `Meter`, `Image`, `CodeBlock`, `TreeView` and `Carousel`.
- **App structure:** `Sidebar`, `AppShell`, `NavigationMenu`, `Menubar`, `ContextMenu`, `Toolbar`, `Stepper`, `CommandPalette`, `HoverCard`, `Toggletip` and `Splitter`.

## Nine more skins [#nine-more-skins]

<p className="gb-when">26–27 Oct 2026 · styles</p>

- `neubrutalism`, `retro` and `glass`; then `swiss`, `progressive` and `clay`; then `material`, `cupertino` and `y2k`. Thirteen skins in all, each in light and dark.
- The contrast matrix learned to measure text over gradients and glass on real pixels. It caught the dark glass tab at 4.36:1 with a cyan brand on its first run.

## The first 50 components [#the-first-50-components]

<p className="gb-when">26 Oct 2026 · library</p>

About 50 components, in four groups: actions and forms, display and feedback (with tones checked at 4.5:1), navigation and overlays, and the layout primitives (`Box`, `Stack`, `Grid`, `Container`, `AspectRatio`, `ScrollArea`, `Portal`, `DirectionProvider`). Each one in the four first skins: `minimal`, `neumorphism`, `retro-pixel` and `editorial`.

## The style contract [#the-style-contract]

<p className="gb-when">26 Oct 2026 · library</p>

The idea the whole library rests on, proven with four skins as far apart as possible: fixed DOM with `data-slot` names, tokens in cascade layers (`cml.tokens`, `cml.components`, `cml.style`, `cml.preferences`), `StyleProvider` with nested islands, and `Button`, `Dialog` and `Tabs` as the first components.

## Foundation [#foundation]

<p className="gb-when">26 Oct 2026 · tooling</p>

The pnpm and Turborepo monorepo: `@camaleo/react`, `@camaleo/styles`, Storybook, this docs app and a Next.js app that checks server rendering.


# Accordion (/docs/components/accordion)

<ComponentMeta file="accordion" primitive="Base UI" pattern="WAI-ARIA Accordion" />

<Playground
	name="accordion/playground"
	component="Accordion"
	controls={[{ prop: "multiple", default: false }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Accordion, AccordionItem, AccordionTrigger, AccordionPanel, Collapsible, CollapsibleTrigger, CollapsiblePanel" />

## Anatomy [#anatomy]

`AccordionTrigger` puts its button inside a heading, so the sections show up in a screen reader's list of headings. It is an `h3`; set `level` to fit the page's outline, such as `level={4}` under a card title. The panel animates its height; the padding sits on an inner element so nothing jumps. `Collapsible` has the same trigger and panel without the heading.

<Anatomy
	tree={{
		slot: "accordion",
		tag: "div",
		children: [
			{
				slot: "accordion-item",
				tag: "div",
				children: [
					{
						slot: "accordion-header",
						tag: "h3",
						note: "level sets h1–h6",
						children: [
							{
								slot: "accordion-trigger",
								tag: "button",
								row: true,
								note: "aria-expanded",
								children: [{ slot: "disclosure-chevron", tag: "span", note: "or disclosure-plus" }],
							},
						],
					},
					{ slot: "accordion-panel", tag: "div", note: "animates its height", children: [{ slot: "accordion-panel-content", tag: "div" }] },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Open a section, then try Tab and Enter.

<Preview name="accordion/basic" compact />

<ExampleGrid>
	<Example name="accordion/multiple" title="Several open">
		With `multiple`, opening a section leaves the others open. Use it when people read sections side by side; `defaultValue` opens the ones most people need.
	</Example>
	<Example name="accordion/settings-forms" title="Sections of a form">
		Split long settings into sections people fill one at a time. `keepMounted` keeps the fields of closed sections in the form, so what people typed is still sent.
	</Example>
	<Example name="accordion/expand-all" title="Expand all">
		Click the button. With `value` and `onValueChange` you control which sections are open, so one button can open or close them all.
	</Example>
	<Example name="accordion/find-in-page" title="Found by page search">
		Press Ctrl+F and search for "invoice". With `hiddenUntilFound`, closed panels stay in the page and open when the browser finds a match in them.
	</Example>
	<Example name="accordion/disabled-reason" title="Disabled, with a reason">
		A disabled header is skipped by Tab, so keep the reason in visible text next to it: say why it's closed and when it opens.
	</Example>
	<Example name="accordion/collapsible-advanced" title="Advanced options">
		`Collapsible` hides options most people never need, so the form stays short and the defaults do the work.
	</Example>
	<Example name="accordion/collapsible-show-more" title="Show more">
		Click it. The extra items appear right above the button, where the reader stopped, and the label says what it will do next.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="accordion/context-help" title="Help center" uses="Card · SearchInput · Accordion · Button" />
	<Context name="accordion/context-filters" title="Product filters" uses="Accordion · Checkbox · RadioGroup · Badge" />
	<Context name="accordion/context-summary" title="Order summary" uses="Card · Collapsible · Separator · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="accordion/do-headers" title="Headers that say what's inside.">
		A question or a topic tells people whether to open it, and reads well in a list of headings.
	</Guideline>
	<Guideline kind="dont" name="accordion/dont-vague" title="Vague headers.">
		"More information" and "Other" make people open every section to find anything.
	</Guideline>
	<Guideline kind="do" name="accordion/do-compare" title="Things to compare, side by side.">
		Prices and limits in one table can be read at a glance.
	</Guideline>
	<Guideline kind="dont" name="accordion/dont-compare" title="Hiding what people compare.">
		With one plan open at a time, people have to remember the other one's price.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="accordion"
	type="AccordionProps"
	include={["multiple", "value", "defaultValue", "onValueChange", "disabled", "keepMounted", "hiddenUntilFound"]}
	types={{ onValueChange: "(value, eventDetails) => void", value: "Value[]", defaultValue: "Value[]" }}
>
	`AccordionItem` takes a `value` and `disabled`. `AccordionTrigger` takes `level` (1 to 6, default 3) for the heading around it. `AccordionTrigger` and `AccordionPanel` take the props of their element.
</Props>

`Collapsible` opens and closes one panel:

<Props
	file="accordion"
	type="CollapsibleProps"
	include={["open", "defaultOpen", "onOpenChange", "disabled"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
/>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the accordion itself.

<StylingHooks
	slots={["accordion", "accordion-item", "accordion-header", "accordion-trigger", "accordion-panel", "accordion-panel-content", "collapsible-trigger", "collapsible-panel", "disclosure-chevron", "disclosure-plus"]}
	prefix="accordion"
	attributes={[
		{ attr: "data-open", value: "on an open item and its panel" },
		{ attr: "data-panel-open", value: "on the trigger while its panel is open" },
		{ attr: "data-disabled", value: "on a disabled item, trigger and panel" },
		{ attr: "data-starting-style · data-ending-style", value: "while the panel opens and closes" },
	]}
>

```css
/* a plus that turns into a minus, only on the help page */
.help [data-slot="accordion"] {
  --cml-accordion-chevron: none;
  --cml-accordion-plus: inline-block;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to the next header, or into an open panel's links and fields." },
		{ key: "Shift + Tab", description: "Moves to the previous header or control." },
		{ key: "Enter / Space", description: "Opens or closes the focused section." },
	]}
	notes={[
		"Each header is a button inside a heading (h3, or the level you set), with aria-expanded. While open, aria-controls points at the panel, a region named by its header.",
		"There are no arrow keys between headers: the WAI-ARIA pattern dropped them, and Tab already moves from one header to the next.",
		"Content in closed panels leaves the page, so Tab and page search skip it, unless you set keepMounted or hiddenUntilFound.",
		"A disabled header is a disabled button: Tab skips it, so its reason must be visible text.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Tabs", description: "Views of the same thing, one at a time.", href: "/docs/components/tabs" },
		{ title: "Card", description: "A container for a summary with its actions.", href: "/docs/components/card" },
		{ title: "Tree view", description: "Nested items that expand, like folders.", href: "/docs/components/tree-view" },
	]}
/>


# AlertDialog (/docs/components/alert-dialog)

<ComponentMeta file="alert-dialog" primitive="Base UI" pattern="WAI-ARIA Alert Dialog" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogTitle, AlertDialogDescription, AlertDialogClose, DialogActions" />

## Anatomy [#anatomy]

The same parts as [Dialog](/docs/components/dialog), so every skin styles both alike. The popup adds `data-kind="alert"` and `role="alertdialog"`.

<Anatomy
	tree={{
		slot: "dialog-popup",
		tag: "div",
		note: "role=alertdialog · data-kind=alert",
		children: [
			{ slot: "dialog-title", tag: "h2", note: "the question" },
			{ slot: "dialog-description", tag: "p", note: "what will happen" },
			{
				slot: "dialog-actions",
				tag: "div",
				row: true,
				children: [
					{ slot: "dialog-close", tag: "button", note: "Cancel, gets focus" },
					{ slot: "dialog-close", tag: "button", note: "the action" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. Open them: the dialog wears the skin, mode and brand from the bar above.

<Preview name="alert-dialog/basic" compact />

<ExampleGrid>
	<Example name="alert-dialog/delete-row" title="Delete a row, keep focus">
		Click Delete. The row and its button go away, so `finalFocus` moves focus to the list heading and a status message confirms it.
	</Example>
	<Example name="alert-dialog/type-to-confirm" title="Type the name to confirm">
		For the worst mistakes, like deleting a repository, make people type the name. The button stays disabled until it matches.
	</Example>
	<Example name="alert-dialog/blocking" title="Waits for the request">
		Click Sign out devices. While the request runs, Esc and Cancel do nothing, so people see whether it worked before the dialog closes.
	</Example>
	<Example name="alert-dialog/initial-focus" title="Focus on Cancel">
		Focus goes to the first focusable element. When that is a checkbox, point `initialFocus` at Cancel, so a quick Enter can't confirm.
	</Example>
	<Example name="alert-dialog/from-menu" title="Opened from a menu">
		Keep the dialog outside the menu and control it with `open`: the menu closes, the dialog stays, and `finalFocus` returns to the menu button.
	</Example>
	<Example name="alert-dialog/irreversible-send" title="Not only for deletes">
		Anything that can't be taken back deserves a confirm, like sending a newsletter. Use a `solid` button when it isn't destructive.
	</Example>
</ExampleGrid>

## In context [#in-context]

Confirms guard the actions that would hurt to get wrong. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="alert-dialog/context-delete-project" title="Danger zone" uses="Card · Separator · AlertDialog" />
	<Context name="alert-dialog/context-discard-changes" title="Discard unsaved changes" uses="Card · Field · Textarea · AlertDialog" />
	<Context name="alert-dialog/context-cancel-plan" title="Cancel a subscription" uses="Card · Badge · AlertDialog" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="alert-dialog/do-action-label" title="Name the action on the button.">
		"Delete 3 files" says what happens. People can answer without rereading the question.
	</Guideline>
	<Guideline kind="dont" name="alert-dialog/dont-ok-label" title="&quot;Are you sure?&quot; and &quot;OK&quot;.">
		Neither says what will happen, so people click through without reading.
	</Guideline>
	<Guideline kind="do" name="alert-dialog/do-interrupt" title="Only for decisions that interrupt.">
		Deleting a workspace that 12 people use is worth stopping for.
	</Guideline>
	<Guideline kind="dont" name="alert-dialog/dont-info" title="An alert to say it worked.">
		"Saved" doesn't need an answer. Interrupting for it teaches people to dismiss alerts. Use a toast.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="alert-dialog" type="AlertDialogProps" include={["open", "defaultOpen", "onOpenChange"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ open: "Whether the dialog is open. Use it with `onOpenChange` to control the state.", defaultOpen: "Whether the dialog starts open, without controlling the state.", onOpenChange: "Called when the dialog opens or closes. `eventDetails.reason` says why, for example `escape-key`. Ignore it to keep the dialog open while a request runs." }}
>
	It is always modal and never closes on an outside click. The other parts take the props of their element, plus `render`.
</Props>

`AlertDialogContent` decides where focus goes:

<Props file="alert-dialog" type="AlertDialogContentProps" include={["initialFocus", "finalFocus"]}
	types={{ initialFocus: "boolean | RefObject | (openType) => HTMLElement | boolean", finalFocus: "boolean | RefObject | (closeType) => HTMLElement | boolean" }}
	describe={{ initialFocus: "The element that gets focus on open. By default, the first focusable element: put Cancel first.", finalFocus: "The element that gets focus on close. By default, the trigger. Set it when the trigger is gone after the action." }}
/>

## Styling hooks [#styling-hooks]

It shares the dialog's slots. Target `data-kind="alert"` to style only the confirms.

<StylingHooks
	slots={["dialog-backdrop", "dialog-popup", "dialog-title", "dialog-description", "dialog-actions", "dialog-close"]}
	prefix="dialog"
	attributes={[
		{ attr: "data-kind", value: '"alert" on the popup' },
		{ attr: "data-open", value: "present while open" },
		{ attr: "data-starting-style", value: "present while opening" },
		{ attr: "data-ending-style", value: "present while closing" },
	]}
>

```css
/* narrower and centered, only in confirms */
[data-slot="dialog-popup"][data-kind="alert"] {
  text-align: center;
  inline-size: min(24rem, calc(100vw - 2rem));
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter / Space", description: "On the trigger, opens the dialog with focus on the first button, Cancel." },
		{ key: "Tab", description: "Moves between the buttons. Focus stays inside the dialog and wraps around." },
		{ key: "Shift + Tab", description: "Moves back, wrapping to the last button." },
		{ key: "Escape", description: "Closes the dialog, like Cancel. Focus goes back to the trigger." },
	]}
	notes={[
		"The popup has role=\"alertdialog\", named by AlertDialogTitle and described by AlertDialogDescription, so screen readers read the question and its consequence together.",
		"A click outside does nothing: the dialog asks for an answer. Esc still closes it, as a Cancel.",
		"Put Cancel first. Focus starts there, so pressing Enter by habit never deletes anything.",
		"After the action, the trigger may be gone: set finalFocus and announce the result with role=\"status\".",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Dialog", description: "A window for a task, like a form.", href: "/docs/components/dialog" },
		{ title: "Toast", description: "Tells people something worked, without interrupting.", href: "/docs/components/toast" },
		{ title: "Button", description: "The danger variant for destructive actions.", href: "/docs/components/button" },
	]}
/>


# Alert (/docs/components/alert)

<ComponentMeta file="alert" pattern="WAI-ARIA alert / status" />

<Playground
	name="alert/playground"
	component="Alert"
	controls={[
		{ prop: "tone", options: ["info", "success", "warning", "danger"], default: "info" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Alert, AlertTitle, AlertDescription" />

## Anatomy [#anatomy]

A box with an icon picked by the tone, an optional label and the content. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="alert"]', color: "#8be36f" },
		{ label: '[data-slot="alert-icon"] · [data-slot="alert-title"]', color: "#ffcf7a" },
		{ label: "description (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">icon</span>
	<span className="a-part">title</span>
	<span className="a-label">Sign-in is down from 2:00 to 2:15 AM</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="alert/basic" compact />

<ExampleGrid>
	<Example name="alert/tones" title="Tones" wide>
		Pick the tone by what people must do: nothing (info), nothing more (success), act soon (warning), act now to continue (danger).
	</Example>
	<Example name="alert/title-only" title="Title only">
		When one sentence says it all, skip the description. A short alert is read faster and gets in the way less.
	</Example>
	<Example name="alert/with-action" title="With an action">
		If people can fix it, put the button inside the alert. They don't have to look for the right settings page.
	</Example>
	<Example name="alert/in-form" title="Inside a form">
		Put the alert right above the field it is about, so people read the risk before they change the value.
	</Example>
	<Example name="alert/dismissible" title="Dismissible">
		Click Dismiss. Only notices people can live without should close. Focus moves to the button that replaces the alert, so keyboard users don't lose their place.
	</Example>
	<Example name="alert/role-alert" title="Urgent or polite">
		`warning` and `danger` get `role="alert"` and interrupt the screen reader; `info` and `success` get `role="status"` and wait their turn.
	</Example>
	<Example name="alert/custom-icon" title="Custom icon">
		Swap the icon when your product has a clearer one, like a sparkle for AI features. The tone still sets the color and the role.
	</Example>
</ExampleGrid>

## In context [#in-context]

Alerts sit next to what they are about. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="alert/context-billing" title="Payment declined" uses="Card · Alert · Button" />
	<Context name="alert/context-maintenance" title="Service status" uses="Card · Alert · Badge · Button" />
	<Context name="alert/context-sync-error" title="Offline documents" uses="Card · Alert · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="alert/do-succinct" title="Use warning when people can keep working.">
		Save danger for what really blocks them, so red keeps its meaning.
	</Guideline>
	<Guideline kind="dont" name="alert/dont-overuse-danger" title="Danger for a routine notice.">
		When everything is red, people stop reading, and miss the real errors.
	</Guideline>
	<Guideline kind="do" name="alert/do-actionable" title="Say how to fix it.">
		Name the problem and give the next step, ideally as a button.
	</Guideline>
	<Guideline kind="dont" name="alert/dont-missing-action" title="An error with no way out.">
		"Something went wrong" leaves people stuck and sends them to support.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="alert" type="AlertProps">
	`AlertTitle` and `AlertDescription` render a `<p>` and take its attributes, like `className` and `style`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the alert itself.

<StylingHooks
	slots={["alert", "alert-icon", "alert-label", "alert-content", "alert-title", "alert-description"]}
	attributes={[
		{ attr: "data-tone", value: "info · success · warning · danger" },
		{ attr: "role", value: "alert (warning, danger) · status (info, success)" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to the buttons and links inside the alert, in reading order. The alert itself never takes focus." },
	]}
	notes={[
		"An alert added after the page loads is read out: right away for warning and danger (role=\"alert\"), after the current speech for info and success (role=\"status\").",
		"An alert already on the page when it loads is not announced. Put it near the top of the content it is about, so people find it while reading.",
		"When people close an alert, move focus to what takes its place, never to the top of the page.",
		"Color is never the only signal: each tone has its own icon, and the title says what happened.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Toast", description: "Short feedback after an action, that goes away on its own.", href: "/docs/components/toast" },
		{ title: "ErrorSummary", description: "Lists every error in a form after people submit it.", href: "/docs/components/error-summary" },
		{ title: "Badge", description: "A status in one or two words, next to a title or in a table.", href: "/docs/components/badge" },
	]}
/>


# AppShell (/docs/components/app-shell)

<ComponentMeta file="app-shell" pattern="HTML landmarks: header, main, footer" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It has no state, so it also renders on the server.

<Import names="AppShell, AppShellHeader, AppShellBody, AppShellContent, AppShellFooter, SkipLink" />

## Anatomy [#anatomy]

A column the height of the screen, with the safe areas of notched phones as padding. The parts are plain landmarks: the header is the page's banner, the content is its `main`. For a sidebar, put `AppShellBody` under the header: a row with the `Sidebar` and `AppShellContent`, where the content takes the rest of the width, also beside a rail.

<Anatomy
	tree={{
		slot: "app-shell",
		tag: "div",
		note: "min-height: 100dvh",
		children: [
			{ slot: "skip-link", tag: "a", note: "shown on focus" },
			{ slot: "app-shell-header", tag: "header", note: "banner" },
			{
				slot: "app-shell-body",
				tag: "div",
				note: "optional row, grows",
				children: [
					{ slot: "sidebar", tag: "aside", note: "fixed width" },
					{ slot: "app-shell-content", tag: "main", note: "id=main-content, grows" },
				],
			},
			{ slot: "app-shell-footer", tag: "footer", note: "optional" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy, shrunk to fit a tile. The docs page around them already has a `main`, so each tile's `AppShellContent` takes `render={<div />}` and an id from `useId`; in your app, drop both.

<Preview name="app-shell/basic" compact />

<ExampleGrid>
	<Example name="app-shell/dashboard" title="Dashboard with a rail" wide>
		`AppShellBody` puts the sidebar in a row under the header. Press the toggle at the bottom of the rail to show the labels; the content takes the rest of the width.
	</Example>
	<Example name="app-shell/admin-table" title="Breadcrumb and search in the header" wide>
		The header says where you are and gives a way to jump anywhere. Press Search: the command palette opens and goes to a page.
	</Example>
	<Example name="app-shell/mail" title="Only the list scrolls" wide>
		Give the content area `overflow-y: auto` and the shell a fixed height. The search and the mailboxes stay in view while the messages scroll.
	</Example>
	<Example name="app-shell/settings" title="Section links beside the form" wide>
		A `SidebarNav` inside the content lists the sections of one page. When the frame is narrow it moves above the form instead of squeezing it.
	</Example>
	<Example name="app-shell/skip-link" title="Skip link first" wide>
		Click above the frame and press Tab. `SkipLink` appears, and Enter moves focus past the header to the content, so keyboard users don't tab through every link on every page.
	</Example>
	<Example name="app-shell/responsive" title="Sidebar, rail or drawer by width" wide>
		The shell doesn't change by itself: you pick a layout per width. Narrow this window to see the full sidebar become a rail, then a menu button with a drawer.
	</Example>
</ExampleGrid>

## In context [#in-context]

Phone-sized screens you can copy, in the skin you picked. Header and footer stay put; the middle scrolls.

<ContextGrid>
	<Context name="app-shell/context-chat" title="Support chat" uses="AppShell · Input · IconButton · Avatar" />
	<Context name="app-shell/context-checkout" title="Checkout" uses="AppShell · Button · Separator" />
	<Context name="app-shell/context-bank" title="Banking app with a tab bar" uses="AppShell · Card · Avatar" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="app-shell/do-one-scroll" title="Only the content scrolls.">
		Scroll the list: the header, with search and the account, is always one click away.
	</Guideline>
	<Guideline kind="dont" name="app-shell/dont-header-scrolls" title="The header scrolls away.">
		Scroll this one. When the whole frame scrolls, people have to go back to the top to reach the menu.
	</Guideline>
	<Guideline kind="do" name="app-shell/do-header-essentials" title="What every page needs.">
		The app's name, search, notifications and the account. Page actions belong in the page.
	</Guideline>
	<Guideline kind="dont" name="app-shell/dont-crowded-header" title="Every action in the header.">
		Buttons that only work on one page are noise on all the others, and they wrap on small screens.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="app-shell" type="SkipLinkProps">
	`AppShell`, `AppShellHeader` and `AppShellFooter` take the props of a `div`, `header` and `footer`. `AppShellBody` takes the props of a `div`. `AppShellContent` takes the props of `main`, and its `id` defaults to `"main-content"`, the target `SkipLink` uses when you don't pass `targetId`. Change both together, and keep the id unique. `render` swaps the `main` for another element, such as `render={<div />}` when the page already has a `main`; the id stays, so the skip link still works.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slots, or set the tokens on a parent, a skin or the shell itself.

<StylingHooks
	slots={["app-shell", "skip-link", "app-shell-header", "app-shell-body", "app-shell-content", "app-shell-footer"]}
	prefix="app-shell"
>

```css
/* a taller header, and a content area that scrolls on its own */
.app [data-slot="app-shell"] {
  --cml-app-shell-header-height: 4rem;
  height: 100dvh;
}
.app [data-slot="app-shell-content"] {
  overflow-y: auto;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "From the top of the page, the first stop is the skip link, which appears where it is." },
		{ key: "Enter", description: "On the skip link, moves focus to the content, past the header and the sidebar." },
		{ key: "Shift + Tab", description: "Goes back through the header's controls." },
	]}
	notes={[
		"Keep one of each landmark per page: one header as the banner, one AppShellContent as main, one footer. Nested in other landmarks they become plain boxes, so don't put the shell inside a main.",
		"Name the navigation regions (\"Main\", \"Settings sections\") when there is more than one, so they can be told apart in a screen reader's list of landmarks.",
		"Translate the skip link's text. Give the target tabIndex={-1} if it isn't a main, so focus can land on it.",
		"When only the content scrolls, it must hold a focusable element or take tabIndex={0}, so keyboard users can scroll it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Sidebar", description: "The app's main navigation, down the left edge.", href: "/docs/components/sidebar" },
		{ title: "Command palette", description: "Search and run anything from a button in the header.", href: "/docs/components/command-palette" },
		{ title: "Breadcrumb", description: "Shows where the current page sits, in the header or above the title.", href: "/docs/components/breadcrumb" },
	]}
/>


# AspectRatio (/docs/components/aspect-ratio)

<ComponentMeta file="layout" pattern="CSS aspect-ratio + object-fit" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It has no state, so it renders on the server.

<Import names="AspectRatio" />

## Anatomy [#anatomy]

One box with `position: relative` and hidden overflow. A direct `img`, `video` or `iframe` fills it; anything else you lay on top with `position: absolute`.

<Anatomy
	tree={{
		slot: "aspect-ratio",
		tag: "div",
		note: "aspect-ratio from ratio",
		row: true,
		children: [
			{ slot: "img · video · iframe", note: "fills it, object-fit: cover" },
			{ slot: "your overlay", note: "optional, position: absolute" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="aspect-ratio/basic" compact />

<ExampleGrid>
	<Example name="aspect-ratio/ratios" title="Pick a ratio">
		Switch the ratio. `ratio` is width divided by height, so write it as a fraction: `16 / 9` for video, `4 / 3` for photos, `1` for squares, `3 / 4` for portraits.
	</Example>
	<Example name="aspect-ratio/cover-contain" title="cover or contain">
		`cover`, the default, fills the box and crops what doesn't fit. Set `objectFit: "contain"` on the image when every edge matters, like a product or a logo.
	</Example>
	<Example name="aspect-ratio/card-grid" title="Cards with photos of any shape" wide>
		The three photos are 16:9, 4:3 and 3:4. Cut to the same ratio, the cards are the same height and the titles line up.
	</Example>
	<Example name="aspect-ratio/thumbnails" title="Thumbnail grid">
		Square thumbnails make a tidy grid whatever was uploaded. `object-position` chooses which part of the photo survives the crop.
	</Example>
	<Example name="aspect-ratio/map-embed" title="Embeds need a title">
		An `iframe` fills the box like an image does. Give it a `title` that says what's inside: it is the frame's name for screen readers.
	</Example>
	<Example name="aspect-ratio/reserve-space" title="Space kept while loading">
		Reload the photo. The box has its height before the file arrives, so the text below never jumps, and a status message says when it's ready.
	</Example>
</ExampleGrid>

## In context [#in-context]

Media rarely stands alone. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="aspect-ratio/context-lesson" title="Course lesson" uses="AspectRatio · IconButton · Progress · Button" />
	<Context name="aspect-ratio/context-listing" title="Rental listing" uses="Card · AspectRatio · Badge · Button" />
	<Context name="aspect-ratio/context-store" title="Store location" uses="Card · AspectRatio · DataList · Link" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="aspect-ratio/do-same-ratio" title="One ratio per row.">
		Photos of any shape end up the same size, and the titles line up.
	</Guideline>
	<Guideline kind="dont" name="aspect-ratio/dont-natural-ratio" title="Every photo in its own shape.">
		The row goes ragged and the eye follows the gaps instead of the content.
	</Guideline>
	<Guideline kind="do" name="aspect-ratio/do-contain-logo" title="contain for logos and products.">
		Their edges carry meaning; show all of it, with some padding.
	</Guideline>
	<Guideline kind="dont" name="aspect-ratio/dont-cover-logo" title="cover on a wide logo.">
		The crop cuts off the brand name, which is the whole point.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="layout" type="AspectRatioProps">
	Every attribute of a `<div>` passes through, like `style` and `className`. Set a width (or let the parent's grid set it); the height always follows the ratio.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slot, or set the custom property in your own CSS.

<StylingHooks
	slots={["aspect-ratio"]}
	prefix="aspect-ratio"
	attributes={[
		{ attr: "data-slot", value: '"aspect-ratio"' },
		{ attr: "--cml-aspect-ratio", value: "the ratio, as a number" },
	]}
>

```css
/* wider video on large screens, taller on phones */
.lesson [data-slot="aspect-ratio"] {
  --cml-aspect-ratio: 4 / 3;
}
@media (min-width: 48rem) {
  .lesson [data-slot="aspect-ratio"] {
    --cml-aspect-ratio: 16 / 9;
  }
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "The box isn't interactive and takes no focus. Tab reaches the controls you put inside it, like a play button." }]}
	notes={[
		"The box adds no role and no name. What's inside still needs one: alt on every image that means something, alt=\"\" on decoration.",
		"Every iframe needs a title that says what it holds (\"Map: Rua Augusta 1200\"), or screen readers only announce \"frame\".",
		"A play button laid over a poster is an icon-only button: give it a name that includes the video's title.",
		"Cropping with cover can cut off text or faces. Don't put information in the edges of an image that might be cropped.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Image", description: "A photo with a caption, a loading skeleton and a fallback.", href: "/docs/components/image" },
		{ title: "Avatar", description: "A round photo of a person, with initials when it fails.", href: "/docs/components/avatar" },
		{ title: "Carousel", description: "Several slides in one place, one at a time.", href: "/docs/components/carousel" },
	]}
/>


# Avatar (/docs/components/avatar)

<ComponentMeta file="avatar" primitive="Base UI" pattern="WAI-ARIA img / group" />

<Playground
	name="avatar/playground"
	component="Avatar"
	controls={[
		{ prop: "size", options: ["sm", "md", "lg"], default: "md" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client, because it waits for the photo to load.

<Import names="Avatar, AvatarGroup" />

## Anatomy [#anatomy]

A round box that holds the photo, or the fallback while the photo loads or when it fails. `AvatarGroup` overlaps several of them.

<Anatomy tree={{ slot: "avatar-group", tag: "div", note: "optional", row: true, children: [{ slot: "avatar", tag: "span", note: "photo or fallback" }, { slot: "avatar", tag: "span", note: "photo or fallback" }] }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="avatar/basic" compact />

<ExampleGrid>
	<Example name="avatar/with-image" title="With a photo">
		On its own, the avatar must say who it is. Put the person's name in `alt`, never "photo" or "avatar".
	</Example>
	<Example name="avatar/beside-name" title="Next to the name">
		When the name is right beside it, hide the avatar with `aria-hidden`. Otherwise screen readers say the name twice.
	</Example>
	<Example name="avatar/sizes" title="Sizes">
		Small for comments and dense lists, medium for menus and cards, large for the top of a profile. Keep one size per list.
	</Example>
	<Example name="avatar/fallback" title="Initials and icon">
		Without a photo, two initials still tell people apart. Use the icon for guests and accounts without a name. `alt` names the avatar whether the photo or the fallback is showing, so screen readers hear the name, not the initials.
	</Example>
	<Example name="avatar/broken-image" title="Photo that fails">
		If the photo doesn't load, the initials stay in place. Always pass a `fallback`, so a broken link never leaves an empty circle.
	</Example>
	<Example name="avatar/group" title="Group with a count">
		Show a few faces and a "+3" for the rest. Name the group with the total, like "7 people on…", and give "+3" its own name.
	</Example>
	<Example name="avatar/interactive-status" title="Presence">
		Click the button. The status is a word in a badge, not just a green dot, and a status region reads the change aloud.
	</Example>
</ExampleGrid>

## In context [#in-context]

Avatars put a face next to what people did. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="avatar/context-comment" title="Comment" uses="Card · Avatar" />
	<Context name="avatar/context-team-card" title="Team member card" uses="Card · Avatar · Button" />
	<Context name="avatar/context-activity" title="Activity feed" uses="Card · Avatar" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="avatar/do-accessible-label" title="Say the name once.">
		With the name next to it, the avatar is decoration: hide it from screen readers.
	</Guideline>
	<Guideline kind="dont" name="avatar/dont-decorative-alt" title='"Photo of…" next to the name.'>
		Screen readers hear "Photo of Mariana Lima, Mariana Lima". The repeat adds nothing.
	</Guideline>
	<Guideline kind="do" name="avatar/do-contrast-fallback" title="Two initials.">
		First and last name initials tell people apart, even without a photo.
	</Guideline>
	<Guideline kind="dont" name="avatar/dont-missing-fallback" title="A question mark.">
		"?" looks like an error and says nothing about who it is.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="avatar" type="AvatarProps">
	Other attributes, like `role`, `aria-label` and `aria-hidden`, go to the outer `<span>`. `AvatarGroup` renders a `<div role="group">` and needs an `aria-label`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the avatar itself.

<StylingHooks
	slots={["avatar", "avatar-group"]}
	attributes={[
		{ attr: "data-size", value: "sm · md · lg" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "An avatar never takes focus. To open a profile, wrap it with the name in a link." }]}
	notes={[
		"With alt, the avatar is one image named after the person (role=\"img\"), with the photo or the initials. Next to a visible name, leave alt empty so the name isn't read twice.",
		"Next to a visible name, hide the avatar with aria-hidden=\"true\", so the name isn't read twice.",
		"Name an AvatarGroup with the total (\"7 people on the project\"), and give the \"+3\" avatar a name too (\"and 3 more\").",
		"Presence needs a word, not only a colored dot. People who don't see the color still need to know who is online.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Image", href: "/docs/components/image", description: "For photos that are content, not a person's face." },
		{ title: "Badge", href: "/docs/components/badge", description: "A status like Online or Away, next to the name." },
		{ title: "Card", href: "/docs/components/card", description: "Holds a profile, a comment or a team member." },
	]}
/>


# Badge (/docs/components/badge)

<ComponentMeta file="display" pattern="Static text" />

<Playground
	name="badge/playground"
	component="Badge"
	label="Active"
	controls={[
		{ prop: "variant", options: ["soft", "solid", "outline"], default: "soft" },
		{ prop: "tone", options: ["neutral", "info", "success", "warning", "danger"], default: "neutral" },
		{ prop: "dot", type: "boolean", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Badge" />

## Anatomy [#anatomy]

A `<span>` with the label and, if you ask for it, a small dot before it. Every part has a `data-slot` you can target from CSS.

<Anatomy tree={{ slot: "badge", tag: "span", note: "label as children", children: [{ slot: "badge-dot", tag: "span", note: "with dot" }] }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="badge/basic" compact />

<ExampleGrid>
	<Example name="badge/variants" title="Variants" wide>
		The soft fill is the everyday choice. Save the solid one for the badge that must stand out on the screen, and use the outline when many badges sit together.
	</Example>
	<Example name="badge/tones" title="Tones" wide>
		Pick the tone by meaning: grey for neutral, blue for information, green when it went well, yellow when it needs attention soon, red when something failed.
	</Example>
	<Example name="badge/dot-status" title="Status dot">
		The dot makes a live state, like online or in a meeting, easy to spot in a list. The word next to it is what carries the meaning.
	</Example>
	<Example name="badge/with-icon" title="With an icon">
		An icon helps people scan, but the word must say it all. Mark the icon `aria-hidden` so it isn't read twice.
	</Example>
	<Example name="badge/count" title="Count with context">
		A screen reader that hears "Inbox 3" doesn't know three of what. Add "unread" as hidden text inside the badge.
	</Example>
	<Example name="badge/truncate" title="Long labels">
		Labels typed by users can get long. Cap the width and cut the text with an ellipsis; the full name stays in the page for screen readers and in `title` for the mouse.
	</Example>
	<Example name="badge/in-table" title="In a table" wide>
		One badge per row, in its own column, lets people compare statuses down the table at a glance.
	</Example>
	<Example name="badge/interactive-filter" title="Counts on filters">
		Click a filter. The badge only shows the count; the `Toggle` around it is what people press, and it announces whether it is on.
	</Example>
</ExampleGrid>

## In context [#in-context]

Badges sit next to what they describe. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="badge/context-profile" title="Team member profile" uses="Card · Avatar · Badge" />
	<Context name="badge/context-order" title="Order status" uses="Card · Badge" />
	<Context name="badge/context-issue" title="Issue labels" uses="Card · Badge" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="badge/do-label" title="Say the status in plain words.">
		"Payment settled" is clear to everyone, with or without the color.
	</Guideline>
	<Guideline kind="dont" name="badge/dont-color-only" title="Internal codes.">
		"Status 200" means something to the developer, not to the customer reading it.
	</Guideline>
	<Guideline kind="do" name="badge/do-succinct" title="One or two words.">
		A short badge reads in a glance and fits on a phone.
	</Guideline>
	<Guideline kind="dont" name="badge/dont-sentence" title="A sentence in a badge.">
		Long text gets cut off or breaks the layout. Put explanations in the text, or in an Alert.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="BadgeProps">
	`Badge` renders a `<span>` and takes its attributes, like `className`, `style` and `title`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the badge itself.

<StylingHooks
	slots={["badge", "badge-dot"]}
	attributes={[
		{ attr: "data-variant", value: "soft · solid · outline" },
		{ attr: "data-tone", value: "neutral · info · success · warning · danger" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "A badge is text and never takes focus. To make it clickable, use a Chip or put it inside a button or link." }]}
	notes={[
		"Color is never the only signal: the label says the status, so people who don't see the color still get it.",
		"A bare number needs context. Add what it counts as hidden text (\"3 unread\"), or say it in the label of the control around it.",
		"A badge that changes while people look at the page is not announced. When the change matters, say it in a status message (role=\"status\").",
		"For tags people select or remove, use Chip: it is a real button, with focus and a name.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Chip", href: "/docs/components/chip", description: "A pill people select, filter with or remove." },
		{ title: "Alert", href: "/docs/components/alert", description: "When the status needs a sentence and maybe an action." },
		{ title: "Avatar", href: "/docs/components/avatar", description: "A person's photo or initials, often shown with a status badge." },
	]}
/>


# Box (/docs/components/box)

<ComponentMeta file="layout" pattern="HTML landmarks and lists" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It has no state, so it renders on the server.

<Import names="Box" />

## Anatomy [#anatomy]

Box is one element with `data-slot="box"` and no styles of its own. Its value is the tag: here a section holds a header and a list, each one a Box with a different `as`.

<Anatomy
	tree={{
		slot: "box",
		tag: "section",
		note: 'as="section", named by its heading',
		children: [
			{ slot: "box", tag: "header", note: 'as="header"' },
			{ slot: "box", tag: "ul", note: 'as="ul"', children: [{ slot: "box", tag: "li", note: 'as="li", one per item' }] },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="box/basic" compact />

<ExampleGrid>
	<Example name="box/as-list" title="A list of things">
		Three files are a list, so render `ul` and `li`. Screen readers announce "list, 3 items" and people know how much is coming.
	</Example>
	<Example name="box/as-article" title="A self-contained post">
		`as="article"` for content that still makes sense on its own, like a post or a comment. Its `header` and `footer` stay inside it and are not page landmarks.
	</Example>
	<Example name="box/as-nav" title="Navigation landmark">
		`as="nav"` with an `aria-label` lets screen reader users jump straight to these links. Mark the current page with `aria-current="page"`.
	</Example>
	<Example name="box/as-search" title="Search landmark">
		A form with `role="search"` becomes a landmark people can reach from anywhere. Name it when the page has more than one search.
	</Example>
	<Example name="box/ordered" title="Ordered or not">
		Switch it off and on. Steps that must happen in sequence are an `ol`; the numbers come from the browser and screen readers say "1 of 4".
	</Example>
	<Example name="box/tokens" title="Spacing and color from tokens">
		Box has no padding or background props. Style it with `var(--cml-…)` tokens and it changes with the skin, like the components around it.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="box/context-settings" title="Settings form" uses="Box · Heading · Switch · Button" />
	<Context name="box/context-feed" title="Team updates feed" uses="Box · Badge · Avatar · Separator" />
	<Context name="box/context-footer" title="Site footer" uses="Box · Grid · Link · Separator" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="box/do-list" title="A list rendered as a list.">
		Screen readers count the items and let people skip the whole group.
	</Guideline>
	<Guideline kind="dont" name="box/dont-divs" title="Items in a row of divs.">
		It looks the same, but a screen reader hears three loose words with no hint that they belong together.
	</Guideline>
	<Guideline kind="do" name="box/do-nav" title="nav for links to other pages.">
		People who jump between landmarks expect to find the site's or the section's navigation there.
	</Guideline>
	<Guideline kind="dont" name="box/dont-nav" title="nav around filter buttons.">
		Filters change the list on this page; they are not navigation. A plain group (or a Toolbar) keeps the landmark list short and honest.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="BoxProps"
	types={{ as: '"div" | "section" | "article" | "nav" | "ul" | "li" | …' }}
>
	`as` takes `div`, `section`, `article`, `main`, `aside`, `header`, `footer`, `nav`, `ul`, `ol`, `li`, `span`, `form` and `figure`. Every other prop goes to that element, so `aria-*`, `role`, `id` and event handlers work as usual.
</Props>

## Styling hooks [#styling-hooks]

Box draws nothing, so the hook is the attribute: style it from a parent or a class.

<StylingHooks slots={["box"]} attributes={[{ attr: "data-slot", value: '"box"' }]}>

```css
/* a quiet panel for every Box section in the settings page */
.settings [data-slot="box"]:where(section) {
  padding: var(--cml-surface-padding);
  border-radius: var(--cml-radius-surface);
  background: var(--cml-surface);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Box renders no interactive element. Focus moves through its children in DOM order." }]}
	notes={[
		"Pick the tag from the content: a section with a heading, an article, a list. The tag is what screen readers announce; the look comes from CSS.",
		"A section becomes a region landmark only when it has a name, so pass aria-labelledby with the id of its heading.",
		"main, header and footer are page landmarks only at the top level. Use main once per page, and don't put it inside the docs or app shell that already has one.",
		"Layout never carries meaning by itself: if two items are related, say so in the markup (a list, a heading), not only with space or position.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Stack", description: "A column or row with a gap from the spacing scale.", href: "/docs/components/stack" },
		{ title: "Grid", description: "Columns that line up, or as many as fit.", href: "/docs/components/grid" },
		{ title: "Card", description: "A surface with a header, content and footer.", href: "/docs/components/card" },
	]}
/>


# Breadcrumb (/docs/components/breadcrumb)

<ComponentMeta file="breadcrumb" pattern="WAI-ARIA Breadcrumb" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It has no state and no effects, so it renders on the server too; `BreadcrumbLink` takes a `render` prop for your router's link.

<Import names="Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis" />

## Anatomy [#anatomy]

A `nav` landmark around an ordered list. Each level is an item; separators are items of their own, hidden from screen readers, and the last item is the current page.

<Anatomy
	tree={{
		slot: "breadcrumb",
		tag: "nav",
		note: "aria-label",
		children: [
			{
				slot: "breadcrumb-list",
				tag: "ol",
				row: true,
				children: [
					{ slot: "breadcrumb-item", tag: "li", children: [{ slot: "breadcrumb-link", tag: "a" }] },
					{ slot: "breadcrumb-separator", tag: "li", note: "aria-hidden", children: [{ slot: "icon", tag: "svg" }, { slot: "breadcrumb-slash", tag: "span" }] },
					{ slot: "breadcrumb-item", tag: "li", children: [{ slot: "breadcrumb-ellipsis", tag: "span", note: "optional, role=img or a button" }] },
					{ slot: "breadcrumb-item", tag: "li", children: [{ slot: "breadcrumb-page", tag: "span", note: "aria-current=page" }] },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="breadcrumb/basic" compact />

<ExampleGrid>
	<Example name="breadcrumb/ecommerce" title="Category path">
		Mirror the catalog tree, so someone who landed on a category from a search can go up a level and browse its neighbors.
	</Example>
	<Example name="breadcrumb/settings" title="Settings path">
		Deep settings screens are easy to get lost in. The trail ends with the page's own heading, which repeats it as the title.
	</Example>
	<Example name="breadcrumb/collapsed" title="Collapsed middle levels">
		Press the … button. Keep the first level and the last two in view and put the rest in a `Menu` opened by a `BreadcrumbEllipsis`; its name says how many levels it hides.
	</Example>
	<Example name="breadcrumb/with-icons" title="With icons">
		A house alone means nothing to a screen reader. Give an icon-only link a name with `VisuallyHidden`, and mark every icon `aria-hidden`.
	</Example>
	<Example name="breadcrumb/truncate" title="Long labels">
		Clip a long name on screen with an ellipsis, never in the text: screen readers still read the whole name, and the heading below shows it in full.
	</Example>
	<Example name="breadcrumb/slash" title="Slash separators">
		Every separator holds a chevron and a slash. Set `--cml-crumb-chevron: none` and `--cml-crumb-slash: inline` for file paths, where the slash is the convention.
	</Example>
	<Example name="breadcrumb/next-link" title="With the Next.js link">
		`render={<NextLink href="…" />}` keeps client-side navigation and prefetching, and the link keeps its slot, its style and its focus ring.
	</Example>
	<Example name="breadcrumb/phone" title="On a phone">
		The list wraps to a second line instead of scrolling sideways. When it would take three lines, collapse the middle levels.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="breadcrumb/context-product" title="Product page" uses="Breadcrumb · Badge · Button · Card" />
	<Context name="breadcrumb/context-files" title="File browser" uses="Breadcrumb · Table · Link · Badge" />
	<Context name="breadcrumb/context-settings" title="Settings form" uses="Breadcrumb · Field · Input · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="breadcrumb/do-hierarchy" title="Show where the page lives.">
		The same order is always under Orders, however people got to it.
	</Guideline>
	<Guideline kind="dont" name="breadcrumb/dont-history" title="Show the pages people visited.">
		That is what the Back button is for. A trail that changes with every visit can't teach the structure.
	</Guideline>
	<Guideline kind="do" name="breadcrumb/do-current-last" title="End with the current page, as text.">
		`BreadcrumbPage` says "you are here" with `aria-current="page"` and isn't a link to itself.
	</Guideline>
	<Guideline kind="dont" name="breadcrumb/dont-current-link" title="Make the current page a link.">
		It looks like somewhere else to go, and following it only reloads the same page.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="breadcrumb" type="BreadcrumbProps">
	`BreadcrumbItem`, `BreadcrumbPage` and `BreadcrumbSeparator` take the props of their `li`, `span` and `li`. `BreadcrumbLink` takes the props of an `a`, plus `render` to use your router's link instead. `BreadcrumbEllipsis` stands for collapsed levels: alone it is an image named "More pages"; with `render={<button type="button" />}`, as a menu's trigger, it is a button. Pass `aria-label` to say how many levels it hides.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slots, or set the tokens on a parent, a skin or the breadcrumb itself.

<StylingHooks
	slots={["breadcrumb", "breadcrumb-list", "breadcrumb-item", "breadcrumb-link", "breadcrumb-page", "breadcrumb-separator", "breadcrumb-slash", "breadcrumb-ellipsis"]}
	attributes={[
		{ attr: "aria-current", value: '"page" on breadcrumb-page' },
		{ attr: "--cml-crumb-chevron", value: "block · none" },
		{ attr: "--cml-crumb-slash", value: "none · inline" },
	]}
>

```css
/* slashes instead of chevrons in the file browser */
.files [data-slot="breadcrumb"] {
  --cml-crumb-chevron: none;
  --cml-crumb-slash: inline;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to the next link in the trail. The current page and the separators are skipped." },
		{ key: "Enter", description: "Follows the focused link." },
		{ key: "Enter / Space / Arrow Down", description: "On a collapsed … button, opens the menu of hidden levels with the first one focused." },
		{ key: "Arrow Down", description: "In that menu, moves to the next level." },
		{ key: "Escape", description: "Closes that menu and returns focus to the … button." },
	]}
	notes={[
		"It is a nav landmark named \"Breadcrumb\". Translate the name with aria-label; screen readers list it among the page's landmarks.",
		"The levels are an ordered list, so screen readers say how many there are. The current page has aria-current=\"page\" and is plain text.",
		"Separators are aria-hidden: screen readers read the names one after the other, without \"slash\" or \"greater than\" in between.",
		"A plain BreadcrumbEllipsis is an image named \"More pages\" (from the messages); as a menu trigger it is a button with the same name, which aria-label can replace.",
		"Links are at least 24px tall (WCAG 2.5.8). An icon-only link needs a text name, for example with VisuallyHidden.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Link", description: "Inline and standalone links, with your router.", href: "/docs/components/link" },
		{ title: "Menu", description: "Holds the levels a long trail collapses.", href: "/docs/components/menu" },
		{ title: "Pagination", description: "Moves through the pages of one long list.", href: "/docs/components/pagination" },
	]}
/>


# Button (/docs/components/button)

<ComponentMeta file="button" primitive="Base UI" pattern="WAI-ARIA Button" />

<Playground
	name="button/playground"
	component="Button"
	label="Publish"
	controls={[
		{ prop: "variant", options: ["solid", "outline", "ghost", "danger"], default: "solid" },
		{ prop: "size", options: ["sm", "md", "lg"], default: "md" },
		{ prop: "loading", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The skin you load styles it.

<Import names="Button, IconButton, ButtonGroup" />

## Anatomy [#anatomy]

One element with up to three parts. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="button"]', color: "#8be36f" },
		{ label: '[data-slot="spinner"] · [data-slot="icon"]', color: "#ffcf7a" },
		{ label: "label (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">spinner</span>
	<span className="a-part">icon</span>
	<span className="a-label">Publish</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="button/variants" compact />

<ExampleGrid>
	<Example name="button/sizes" title="Sizes">
		`sm`, `md` and `lg` follow the skin's control heights, so a form and its buttons always line up.
	</Example>
	<Example name="button/with-icon" title="With an icon">
		Put the icon before the label for something new, after it for direction or download. Mark it `data-slot="icon"` and `aria-hidden`.
	</Example>
	<Example name="button/icon-only" title="Icon only">
		`IconButton` requires `aria-label`. Pair it with a `Tooltip` so sighted users get the name too.
	</Example>
	<Example name="button/as-link" title="As a link">
		Navigation is a link, not a button. `render={<a href="…" />}` with `nativeButton={false}` keeps the look and gives you a real anchor.
	</Example>
	<Example name="button/saving" title="Saving, then saved">
		Click it. `loading` keeps the width and the focus while the request runs; a status message announces the result.
	</Example>
	<Example name="button/confirm" title="Destructive, with a confirm">
		Click it. A `danger` action opens an `AlertDialog`. The safe choice comes first and gets focus.
	</Example>
	<Example name="button/group" title="Grouped">
		`ButtonGroup` joins related actions under `role="group"`. For arrow-key navigation between them, use `Toolbar`.
	</Example>
	<Example name="button/disabled-reason" title="Disabled, with a reason">
		Never leave people guessing. Say what is missing and link it with `aria-describedby`, or keep the button enabled and validate on submit.
	</Example>
</ExampleGrid>

## In context [#in-context]

Buttons are never alone. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="button/context-pricing" title="Pricing card" uses="Card · Badge · Button" />
	<Context name="button/context-empty" title="Empty state" uses="EmptyState · Button" />
	<Context name="button/context-consent" title="Consent banner" uses="Card · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="button/do-one-solid" title="One solid button per area.">
		It tells people what the main action is.
	</Guideline>
	<Guideline kind="dont" name="button/dont-many-solid" title="Three solid buttons side by side.">
		Nothing stands out, so nothing is clear.
	</Guideline>
	<Guideline kind="do" name="button/do-verb" title="Start with a verb.">
		Say what happens: "Create invoice", "Save changes".
	</Guideline>
	<Guideline kind="dont" name="button/dont-vague" title="Vague labels.">
		"OK" and "Click here" mean nothing out of context, or to a screen reader listing the buttons.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="button" type="ButtonProps" include={["disabled", "render", "nativeButton", "focusableWhenDisabled"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ disabled: "Disables the button and removes it from the tab order." }}
>
	`IconButton` takes the same props without `size`, plus a required `aria-label`. Native button attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the button itself.

<StylingHooks
	slots={["button"]}
	attributes={[
		{ attr: "data-slot", value: '"button"' },
		{ attr: "data-variant", value: "solid · outline · ghost · danger" },
		{ attr: "data-size", value: "sm · md · lg · icon" },
		{ attr: "data-loading", value: "present while loading" },
		{ attr: "data-disabled", value: "present when disabled" },
	]}
>

```css
/* a pill-shaped primary, only in this section */
.checkout [data-slot="button"][data-variant="solid"] {
  --cml-radius-control: 999px;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "Activates the button." },
		{ key: "Space", description: "Activates the button on release." },
		{ key: "Tab", description: "Moves focus to it — also while loading." },
	]}
	notes={[
		"Text and focus ring pass WCAG 2.2 AA in all 13 skins, light and dark, with any brand color.",
		"While loading it sets aria-busy and stays focusable, so keyboard and screen reader users keep their place.",
		"Rendered as another element through render, it keeps the button role and keyboard behavior.",
		"Respects reduced motion: the press effect and the spinner calm down.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Toggle", description: "A button that stays pressed.", href: "/docs/components/toggle" },
		{ title: "Spinner", description: "Loading feedback on its own.", href: "/docs/components/spinner" },
		{ title: "Dialog", description: "Confirm or collect input before acting.", href: "/docs/components/dialog" },
	]}
/>


# Calendar (/docs/components/calendar)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Grid" />

<Playground
	name="calendar/playground"
	component="Calendar"
	controls={[
		{ prop: "weekdayStyle", options: ["narrow", "short", "long"], default: "short" },
		{ prop: "firstDayOfWeek", options: ["sun", "mon"], default: "sun" },
		{ prop: "readOnly", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Dates are `@internationalized/date` objects, re-exported from Camaleo.

<Import names="Calendar, CalendarDate, isWeekend" />

## Anatomy [#anatomy]

A header with the month and two arrows, the grid of days and an optional footer. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="calendar"]', color: "#8be36f" },
		{ label: '[data-slot="calendar-title"] · [data-slot="calendar-nav-button"] · [data-slot="calendar-footer"]', color: "#ffcf7a" },
		{ label: '[data-slot="calendar-grid"] · [data-slot="calendar-cell"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">title</span>
	<span className="a-part">‹ ›</span>
	<span className="a-label">grid</span>
	<span className="a-part">footer</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="calendar/basic" compact />

<ExampleGrid>
	<Example name="calendar/controlled" title="Controlled, with a summary">
		Pick a day. `value` and `onChange` keep the date in your state, and the sentence below spells it out with the weekday.
	</Example>
	<Example name="calendar/min-max" title="Min and max">
		`minValue` and `maxValue` disable the days outside the window, and the arrows stop at its first and last month.
	</Example>
	<Example name="calendar/weekends" title="Weekends unavailable">
		`isDateUnavailable` with `isWeekend` follows the locale. Unavailable days stay focusable and are announced as unavailable, so say why in the footer.
	</Example>
	<Example name="calendar/booked" title="Booked days">
		Return `true` for the days your API says are full. The strike-through is not the only signal: the footer explains it in words.
	</Example>
	<Example name="calendar/first-day" title="Week starts on Monday">
		The locale sets the first day: Sunday in the US and Brazil. `firstDayOfWeek="mon"` matches a team that plans in ISO weeks.
	</Example>
	<Example name="calendar/read-only" title="Read-only">
		`readOnly` shows a confirmed date that people can still browse and read, unlike `disabled`, which drops it from the tab order.
	</Example>
	<Example name="calendar/focused-month" title="Open on another month">
		With no value the calendar opens on today. `defaultFocusedValue` opens it on the month people need, and renders the same on server and client.
	</Example>
</ExampleGrid>

## In context [#in-context]

Calendars sit inside bookings and checkouts. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="calendar/context-appointment" title="Book a consultation" uses="Card · Calendar · ToggleGroup · Button" />
	<Context name="calendar/context-delivery" title="Delivery day" uses="Card · Calendar · Button" />
	<Context name="calendar/context-payment" title="Schedule a payment" uses="Card · Calendar · Badge · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="calendar/do-explain-unavailable" title="Say why days are unavailable.">
		A short line in the footer answers the question before people click around.
	</Guideline>
	<Guideline kind="dont" name="calendar/dont-unexplained" title="Unavailable days with no reason.">
		People try them one by one, and a screen reader only hears "unavailable".
	</Guideline>
	<Guideline kind="do" name="calendar/do-near-date" title="A calendar for dates in the next weeks.">
		The month on screen is the one people pick from.
	</Guideline>
	<Guideline kind="dont" name="calendar/dont-birth-date" title="A calendar for a date of birth.">
		Reaching 1994 takes hundreds of clicks. Use a [Date field](/docs/components/date-field) and let people type it.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="CalendarProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "firstDayOfWeek", "focusedValue", "defaultFocusedValue", "onFocusChange", "autoFocus"]}
	types={{ value: "DateValue | null", defaultValue: "DateValue | null", onChange: "(value: DateValue) => void", minValue: "DateValue | null", maxValue: "DateValue | null", isDateUnavailable: "(date: DateValue) => boolean", firstDayOfWeek: "\"sun\" | \"mon\" | \"tue\" | \"wed\" | \"thu\" | \"fri\" | \"sat\"", focusedValue: "DateValue | null", defaultFocusedValue: "DateValue | null", onFocusChange: "(date: CalendarDate) => void" }}
	describe={{ className: "Class names for the root element.", style: "Inline styles for the root element.", disabled: "Disables every day and the arrows, and removes the grid from the tab order.", readOnly: "Shows the value without letting people change it. Days stay focusable.", invalid: "Marks the selection as invalid, for errors that come from your app.", locale: "BCP 47 locale for month names, weekdays and the first day of the week, e.g. `\"pt-BR\"`. Defaults to the nearest `I18nProvider` or the browser.", weekdayStyle: "How the weekday headers are written: `\"narrow\"`, `\"short\"` (default) or `\"long\"`.", previousLabel: "Accessible name of the previous-month arrow. React Aria's localized \"Previous\" by default.", nextLabel: "Accessible name of the next-month arrow. React Aria's localized \"Next\" by default.", footer: "Content under the grid: the chosen date, a legend or a price." }}
>
	Dates are `CalendarDate` objects from `@internationalized/date`, re-exported by Camaleo with `parseDate`, `today` and `isWeekend`. React Aria's other calendar props pass through, such as `pageBehavior` and `createCalendar`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the calendar itself.

<StylingHooks
	slots={["calendar", "calendar-header", "calendar-title", "calendar-nav", "calendar-nav-button", "calendar-grid", "calendar-header-cell", "calendar-cell", "calendar-footer"]}
	prefix="calendar"
	attributes={[
		{ attr: "data-slot", value: '"calendar" · "calendar-header" · "calendar-grid" · "calendar-cell" · "calendar-footer"' },
		{ attr: "data-selected", value: "present on the chosen day" },
		{ attr: "data-today", value: "present on today's date" },
		{ attr: "data-unavailable", value: "present on days isDateUnavailable rejects" },
		{ attr: "data-disabled", value: "present on days outside min/max, and on the root when disabled" },
		{ attr: "data-outside-month · data-focus-visible", value: "present on days of the next or previous month · on keyboard focus" },
	]}
>

```css
/* round day cells, only in the booking flow */
.booking [data-slot="calendar"] {
  --cml-calendar-cell-radius: 999px;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Arrow keys", description: "Move focus one day, or one week up and down." },
		{ key: "Home / End", description: "Move focus to the first or last day of the month." },
		{ key: "Page Up / Page Down", description: "Move to the previous or next month. With Shift, by a year." },
		{ key: "Enter / Space", description: "Selects the focused day." },
		{ key: "Tab", description: "Moves between the arrows and the grid." },
	]}
	notes={[
		"The grid is a role=\"grid\" labelled by aria-label plus the visible month, so people hear \"Appointment date, October 2026\".",
		"Each day is announced with its full date and its state: selected, today or unavailable.",
		"Unavailable days are struck out and stay focusable, so keyboard users can reach them and hear why they can't pick them.",
		"Changing month announces the new month to screen readers.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Range calendar", description: "Pick a start and an end date.", href: "/docs/components/range-calendar" },
		{ title: "Date picker", description: "A date field with this calendar in a popover.", href: "/docs/components/date-picker" },
		{ title: "Date field", description: "Type a date, segment by segment.", href: "/docs/components/date-field" },
	]}
/>


# Card (/docs/components/card)

<ComponentMeta file="display" pattern="Static container" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter" />

## Anatomy [#anatomy]

A header with the title and a short description, the content, and a footer for actions. Use only the parts you need; every part has a `data-slot` you can target from CSS.

<Anatomy tree={{ slot: "card", tag: "div", children: [{ slot: "card-header", tag: "div", children: [{ slot: "card-title", tag: "h3" }, { slot: "card-description", tag: "p" }] }, { slot: "card-content", tag: "div" }, { slot: "card-footer", tag: "div", note: "actions" }] }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="card/basic" compact />

<ExampleGrid>
	<Example name="card/with-footer" title="With actions">
		Put the buttons in `CardFooter`, the main one last. People find them in the same place on every card.
	</Example>
	<Example name="card/stretched-link" title="Whole card as a link">
		Click anywhere on the card. The link stays in the title, so screen readers hear a short name, and `data-card-link` on it stretches it over the card. Don't turn the card itself into a button.
	</Example>
	<Example name="card/interactive-selection" title="Selectable cards" wide>
		Click a card or use the arrow keys. Each card is a radio's label, so the whole card selects it, and the legend names the group.
	</Example>
	<Example name="card/media-card" title="With a picture">
		A picture on top helps people recognize a guide or a product. If it only decorates, hide it with `aria-hidden`.
	</Example>
	<Example name="card/variants" title="Compact">
		Less padding for dashboard numbers. Keep the title: it is what names the number for everyone.
	</Example>
	<Example name="card/empty" title="Nothing here yet">
		An empty card still shows its title, says why it is empty and offers the next step, instead of disappearing.
	</Example>
	<Example name="card/grid" title="Cards in a grid" wide>
		A list of cards is a list: use `ul` and `li`, so screen readers say how many there are. The grid wraps on its own on phones.
	</Example>
</ExampleGrid>

## In context [#in-context]

Cards hold one subject each. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="card/context-pricing" title="Pricing plan" uses="Card · Button" />
	<Context name="card/context-analytics" title="Dashboard number" uses="Card · Badge · Link" />
	<Context name="card/context-account" title="Security setting" uses="Card · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="card/do-structured-parts" title="Use the header and content parts.">
		They set the spacing and the title style, so the card looks right in every skin.
	</Guideline>
	<Guideline kind="dont" name="card/dont-unstructured-divs" title="Plain divs inside the card.">
		The title is no longer a heading, and the spacing breaks when people switch skins.
	</Guideline>
	<Guideline kind="do" name="card/do-sections" title="Split a card with a line.">
		A separator divides the content and keeps one box around one subject.
	</Guideline>
	<Guideline kind="dont" name="card/dont-nested-cards" title="A card inside a card.">
		Boxes inside boxes waste space on phones and make it unclear what belongs together.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="CardProps">
	`Card` and each part render plain HTML and take its attributes: `Card`, `CardHeader`, `CardContent` and `CardFooter` a `<div>`, `CardTitle` an `<h3>`, `CardDescription` a `<p>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slots, or set the tokens on a parent, a skin or the card itself.

<StylingHooks
	slots={["card", "card-header", "card-title", "card-description", "card-content", "card-footer"]}
	attributes={[{ attr: "data-card-link", value: "on the title link: stretches it over the card, which shows its focus ring" }]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "Moves through the links, buttons and fields inside the card. The card itself never takes focus." }]}
	notes={[
		"CardTitle is an <h3>. If the page structure needs another level, render a different heading inside it or set aria-level.",
		"For a clickable card, put one link in the title and add data-card-link to it. Wrapping the whole card in a link or button makes screen readers read everything as one long name.",
		"Other links, buttons and fields on a data-card-link card stay above the stretched link and keep working. Keep them few: the rest of the card can't be selected as text.",
		"Selectable cards are radios or checkboxes with a label that fills the card, inside a fieldset with a legend.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Link", href: "/docs/components/link", description: "The link in the title of a clickable card." },
		{ title: "Empty state", href: "/docs/components/empty-state", description: "What a card shows when there is nothing in it yet." },
		{ title: "Stat", href: "/docs/components/stat", description: "One number with its label and trend, for dashboard cards." },
	]}
/>


# Carousel (/docs/components/carousel)

<ComponentMeta file="carousel" pattern="WAI-ARIA Carousel" />

<Playground
	name="carousel/playground"
	component="Carousel"
	controls={[
		{ prop: "autoPlay", default: false },
		{ prop: "showAutoPlayToggle", default: true },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It runs on the client, because it keeps the current slide.

<Import names="Carousel, CarouselSlide" />

## Anatomy [#anatomy]

A `<section>` with the slides, then a row of controls. `CarouselSlide` is an optional layout for each slide; any element works. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "carousel",
		tag: "section",
		children: [
			{
				slot: "carousel-viewport",
				tag: "div",
				children: [
					{
						slot: "carousel-slide",
						tag: "div",
						note: "tabpanel, one per child",
						children: [
							{
								slot: "carousel-slide-body",
								tag: "div",
								note: "CarouselSlide",
								row: true,
								children: [
									{
										slot: "carousel-slide-content",
										tag: "div",
										children: [
											{ slot: "carousel-slide-kicker", tag: "p" },
											{ slot: "carousel-slide-title", tag: "h3" },
											{ slot: "carousel-slide-description", tag: "p" },
										],
									},
									{ slot: "carousel-slide-aside", tag: "div", note: "badge" },
								],
							},
						],
					},
				],
			},
			{
				slot: "carousel-controls",
				tag: "div",
				row: true,
				children: [
					{
						slot: "carousel-actions",
						tag: "div",
						row: true,
						children: [
							{ slot: "carousel-button", tag: "button", note: "previous" },
							{ slot: "carousel-button", tag: "button", note: "next" },
							{ slot: "carousel-autoplay", tag: "button", note: "play / pause" },
						],
					},
					{ slot: "carousel-indicators", tag: "div", children: [{ slot: "carousel-indicator", tag: "button", note: "one per slide" }] },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="carousel/basic" compact />

<ExampleGrid>
	<Example name="carousel/indicators" title="Steps people jump between">
		Each dot is a tab: Tab reaches the row once, and the arrow keys move between slides. Hide the Play button with `showAutoPlayToggle={false}` when people read at their own pace.
	</Example>
	<Example name="carousel/play-button" title="Rotation people start">
		Keep `autoPlay` off and leave the Play button: people who want the slides to move press it, and Pause stops them. Rotation never runs when the system asks for reduced motion.
	</Example>
	<Example name="carousel/with-kicker" title="Every part of a slide">
		`CarouselSlide` lays out `kicker`, `title`, `description` and `badge`. Put the date or category in the kicker, so the title stays short enough for a phone.
	</Example>
	<Example name="carousel/custom-slides" title="Your own slide content">
		Any element can be a slide. Start it with a heading, because the slide's own name is only its position, like "2 of 3".
	</Example>
	<Example name="carousel/interactive-tour" title="React to the slide">
		Move through the steps, then press Start over. Control `activeIndex` when the page must know the slide, like for a step counter or a finish button.
	</Example>
	<Example name="carousel/slide-labels" title="Names in your language">
		Screen readers hear each slide as "2 of 3, slide". Pass `slideLabel`, `slideRoleDescription` and the button labels to say "Plan 2 of 3" in the page's language.
	</Example>
</ExampleGrid>

## In context [#in-context]

Carousels usually sit in a card or a page section, next to content that is always visible. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="carousel/context-onboarding" title="Getting started tour" uses="Card · Carousel · Button" wide />
	<Context name="carousel/context-testimonials" title="Customer reviews" uses="Card · Carousel · Avatar" wide />
	<Context name="carousel/context-promotions" title="Store deals" uses="Card · Carousel · Badge · Button" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="carousel/do-few-slides" title="Three to five slides.">
		People rarely go past the third slide, so a short set gets seen and the dots stay easy to tell apart.
	</Guideline>
	<Guideline kind="dont" name="carousel/dont-many-slides" title="A slide for every message.">
		Eight dots look the same, and the last slides are only seen by people who click through all of them.
	</Guideline>
	<Guideline kind="do" name="carousel/do-slide-titles" title="A title on every slide.">
		People scanning, and screen reader users jumping by heading, know what a slide is about before reading it.
	</Guideline>
	<Guideline kind="dont" name="carousel/dont-no-titles" title="Slides that are only a paragraph.">
		Without a title, people have to read the whole slide to decide if it matters to them.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="carousel" type="CarouselProps" types={{ slideLabel: "(index, total) => string", goToSlideLabel: "(index) => string" }} />

<Props file="carousel" type="CarouselSlideProps">
	Both take the attributes of their element: `Carousel` those of `<section>` (its `aria-label` defaults to "Carousel", so always pass one), `CarouselSlide` those of `<div>`, with `children` after the description.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the carousel itself.

<StylingHooks
	slots={["carousel", "carousel-viewport", "carousel-slide", "carousel-slide-body", "carousel-slide-content", "carousel-slide-kicker", "carousel-slide-title", "carousel-slide-description", "carousel-slide-aside", "carousel-controls", "carousel-actions", "carousel-button", "carousel-autoplay", "carousel-indicators", "carousel-indicator"]}
	prefix="carousel"
	attributes={[
		{ attr: "data-active", value: "on the slide on show and its dot" },
		{ attr: "aria-selected", value: "true on the dot of the slide on show" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves through previous, next, Play/Pause, then the row of dots, which is one stop." },
		{ key: "Enter / Space", description: "Presses previous, next or Play/Pause." },
		{ key: "← / →", description: "In the row of dots, shows the previous or next slide and moves focus to its dot. Also ↑ / ↓." },
		{ key: "Home / End", description: "In the row of dots, shows the first or last slide." },
	]}
	notes={[
		"The carousel is a section with aria-roledescription=\"carousel\". It follows the tabbed carousel pattern: the dots are tabs, each with aria-controls pointing to its slide, and each slide is a role=\"tabpanel\" named by its position, like \"2 of 3\". Hidden slides are removed from the page with hidden.",
		"Rotation is off by default and never runs with reduced motion. It holds while the pointer or keyboard focus is inside the carousel, and the Play/Pause button stops it for good.",
		"A slide the person picks is announced (the viewport is aria-live=\"polite\"); automatic rotation is not. Start each slide with a heading, so the announcement is short and clear.",
		"The default names are in English. On other languages, pass roleDescription, slideLabel, goToSlideLabel and the button labels.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Card", description: "The surface that usually holds a carousel in a page section.", href: "/docs/components/card" },
		{ title: "Image", description: "Responsive pictures with a fixed shape, for photo slides.", href: "/docs/components/image" },
		{ title: "Accordion", description: "Sections that all stay on the page, when people need every message.", href: "/docs/components/accordion" },
	]}
/>


# Checkbox (/docs/components/checkbox)

<ComponentMeta file="checkbox" primitive="Base UI" pattern="WAI-ARIA Checkbox" />

<Playground
	name="checkbox/playground"
	component="Checkbox"
	controls={[
		{ prop: "defaultChecked", default: false },
		{ prop: "indeterminate", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Wrap each checkbox in a `Label` so the text is clickable and names it.

<Import names="Checkbox, CheckboxGroup, Label" />

## Anatomy [#anatomy]

A `Checkbox` is a box with an indicator inside. A `CheckboxGroup` wraps several labeled checkboxes and keeps their values together.

<Anatomy
	keys={[
		{ label: '[data-slot="checkbox-group"]', color: "#8be36f" },
		{ label: '[data-slot="checkbox"] · [data-slot="checkbox-indicator"]', color: "#ffcf7a" },
		{ label: '[data-slot="label"] text', color: "#7cc7ff" },
	]}
>
	<span className="a-part">checkbox</span>
	<span className="a-label">Product updates</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="checkbox/basic" compact />

<ExampleGrid>
	<Example name="checkbox/group" title="A group with a legend">
		`Fieldset render={<CheckboxGroup />}` gives the options one name, so a screen reader announces "Email me about" before each of them.
	</Example>
	<Example name="checkbox/select-all" title="Select all">
		Click the children. With `allValues` on the group and `parent` on one box, it shows the mixed state when only some are ticked.
	</Example>
	<Example name="checkbox/with-description" title="With a description">
		Keep the label short and put the consequence below it, linked with `aria-describedby` so it is read after the name.
	</Example>
	<Example name="checkbox/required" title="Required, with an error">
		Submit it unticked. Say what to do in the error, not just "Required"; `Field` links it to the checkbox.
	</Example>
	<Example name="checkbox/disabled" title="Disabled, with a reason">
		A disabled box still shows what is included. When it is off, say why, so people know how to get it.
	</Example>
	<Example name="checkbox/table" title="Row selection" wide>
		In a table the row is the label, so give each checkbox an `aria-label` that names its row.
	</Example>
</ExampleGrid>

## In context [#in-context]

Checkboxes live in forms and lists. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="checkbox/context-signup" title="Signup with terms" uses="Card · Field · Input · Checkbox · Button" />
	<Context name="checkbox/context-filters" title="Filter panel" uses="Card · Fieldset · CheckboxGroup · Separator" />
	<Context name="checkbox/context-tasks" title="Checklist" uses="Card · CheckboxGroup · Checkbox" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="checkbox/do-many" title="Checkboxes for any number of options.">
		Each one stands alone: people can pick none, one or all of them.
	</Guideline>
	<Guideline kind="dont" name="checkbox/dont-exclusive" title="Checkboxes for options that exclude each other.">
		Monthly and yearly at once makes no sense. Use a `RadioGroup`.
	</Guideline>
	<Guideline kind="do" name="checkbox/do-positive" title="Say what a tick turns on.">
		A ticked box should mean yes: "Send me the weekly digest".
	</Guideline>
	<Guideline kind="dont" name="checkbox/dont-negative" title="Negative labels.">
		A tick that means "don't stop" makes people stop and reread.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="checkbox" type="CheckboxProps" include={["checked", "defaultChecked", "onCheckedChange", "indeterminate", "value", "parent", "name", "required", "disabled", "readOnly"]}
	types={{ onCheckedChange: "(checked: boolean, details) => void" }}
	describe={{ value: "Identifies the checkbox inside a `CheckboxGroup` and is the value submitted with the form.", parent: "Whether the checkbox controls the children of a `CheckboxGroup` (the \"select all\" box)." }}
>
	`CheckboxGroup` takes `value`, `defaultValue` and `onValueChange` (arrays of the checkboxes' `value`), `allValues` for a parent checkbox, and `disabled`. Native attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the checkbox itself.

<StylingHooks
	slots={["checkbox", "checkbox-indicator", "checkbox-group"]}
	prefix="check"
	attributes={[
		{ attr: "data-slot", value: '"checkbox" · "checkbox-indicator" · "checkbox-group"' },
		{ attr: "data-checked", value: "present when ticked" },
		{ attr: "data-unchecked", value: "present when not ticked" },
		{ attr: "data-indeterminate", value: "present in the mixed state" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-invalid", value: "present when its Field is invalid" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Space", description: "Ticks or unticks the focused checkbox." },
		{ key: "Tab", description: "Moves to the next checkbox; each one is its own tab stop." },
	]}
	notes={[
		"The hit area is at least 24 × 24 px (WCAG 2.5.8) in every skin, even when the visible box is smaller.",
		"Clicking the label text toggles the box, so wrap it in Label or link it with htmlFor; the id lands on the box itself, which an ErrorSummary link can focus too.",
		"The mixed state is announced as \"mixed\" through aria-checked, not just drawn as a dash.",
		"Inside a Field, the description and the error are linked to the box with aria-describedby.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Switch", description: "On and off for settings that apply right away.", href: "/docs/components/switch" },
		{ title: "Radio group", description: "One choice out of a few.", href: "/docs/components/radio-group" },
		{ title: "Field", description: "Label, description and error for any control.", href: "/docs/components/field" },
	]}
/>


# Chip (/docs/components/chip)

<ComponentMeta file="chip" primitive="Base UI" pattern="WAI-ARIA Button (toggle)" />

<Playground
	name="chip/playground"
	component="Chip"
	label="Only unread"
	controls={[
		{ prop: "defaultPressed", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The skin you load styles it.

<Import names="Chip, ChipGroup" />

## Anatomy [#anatomy]

A filter chip is a toggle button with a check that shows while pressed. An input chip (with `onRemove`) is a span with a remove button at the end.

<Anatomy
	keys={[
		{ label: '[data-slot="chip"]', color: "#8be36f" },
		{ label: '[data-slot="chip-check"] · avatar · [data-slot="chip-remove"]', color: "#ffcf7a" },
		{ label: "label (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">check</span>
	<span className="a-label">In review</span>
	<span className="a-part">remove</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="chip/basic" compact />

<ExampleGrid>
	<Example name="chip/filter-count" title="Filters with a count">
		Press the chips. Counts in the labels set expectations, and a `role="status"` line announces how many results are left.
	</Example>
	<Example name="chip/single" title="Single selection">
		`multiple={false}` keeps one chip pressed at a time, but people can still unpress it. When an empty choice is not allowed, use a radio group.
	</Example>
	<Example name="chip/removable" title="Removable">
		Remove a label. `onRemove` turns the chip into an input chip, `removeLabel` names its button "Remove Urgent", and focus stays in the list instead of falling to the page body.
	</Example>
	<Example name="chip/avatar" title="People, with an avatar">
		`avatar` takes a small `Avatar`. Its initials are decoration: the name in the chip and in `removeLabel` is what assistive tech reads.
	</Example>
	<Example name="chip/toggle" title="On its own">
		A single `Chip` is a toggle with `aria-pressed`, good for one quick filter like "Only unread" above a list.
	</Example>
	<Example name="chip/with-icon" title="With an icon">
		An icon helps people scan a long set. Mark it `data-slot="icon"` and `aria-hidden`; the text still carries the meaning.
	</Example>
	<Example name="chip/disabled" title="Disabled, with a reason">
		Arrow keys skip a disabled chip. Say why it is off in text linked with `aria-describedby`, or people think the filter is broken.
	</Example>
</ExampleGrid>

## In context [#in-context]

Chips sit above results, inside filter panels and in share dialogs. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="chip/context-filters" title="Filter panel" uses="Card · ChipGroup · Chip · Button" />
	<Context name="chip/context-recipients" title="Share with people" uses="Card · Field · Input · Chip · Avatar · Button" />
	<Context name="chip/context-applied" title="Applied filters" uses="Chip · Button · Text" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="chip/do-short" title="One to three words.">
		Short labels keep a row of chips scannable and fit on a phone.
	</Guideline>
	<Guideline kind="dont" name="chip/dont-long" title="Sentences in chips.">
		They break the row into ragged lines and take longer to scan than one or two words.
	</Guideline>
	<Guideline kind="do" name="chip/do-filter" title="Chips filter, buttons act.">
		Pressing a chip changes what you see; an action like "Export" stays a button.
	</Guideline>
	<Guideline kind="dont" name="chip/dont-action" title="Chips as action buttons.">
		A chip announces "pressed" or "not pressed", which makes no sense for "Delete".
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="chip" type="ChipProps" include={["value", "pressed", "defaultPressed", "onPressedChange", "disabled", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement", onPressedChange: "(pressed, details) => void" }}
>
	`ChipGroup` takes `value`, `defaultValue` and `onValueChange` (arrays of chip values), `multiple` (`true` by default), `disabled` and `orientation`. Give it a name with `aria-label` or `aria-labelledby`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the chip itself.

<StylingHooks
	slots={["chip", "chip-group", "chip-check", "chip-remove"]}
	prefix="chip"
	attributes={[
		{ attr: "data-slot", value: '"chip" · "chip-group" · "chip-check" · "chip-remove"' },
		{ attr: "data-variant", value: "filter · input" },
		{ attr: "data-pressed", value: "present on a pressed filter chip" },
		{ attr: "data-disabled", value: "present when disabled" },
	]}
>

```css
/* square chips, only in this toolbar */
.report-filters [data-slot="chip"] {
  --cml-chip-radius: var(--cml-radius-control);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus into the group, to one chip, and out again. Inside an input chip, it reaches the remove button." },
		{ key: "Arrow keys", description: "Move between the chips of a ChipGroup." },
		{ key: "Enter / Space", description: "Presses or unpresses the focused chip, or activates the remove button." },
	]}
	notes={[
		"A filter chip is a button with aria-pressed, so screen readers say \"Open, toggle button, pressed\".",
		"ChipGroup has role=\"group\" and needs a name, like \"Status\", so the chips are read as one set.",
		"The check mark shows the pressed state by shape, not only by color.",
		"When you remove a chip, move focus to a neighbour or to the input that adds chips, so keyboard users don't land on the page body.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Toggle", description: "A pressed button for toolbars, with icons.", href: "/docs/components/toggle" },
		{ title: "Tags input", description: "Type to add removable values.", href: "/docs/components/tags-input" },
		{ title: "Checkbox", description: "Many options in a form, with labels.", href: "/docs/components/checkbox" },
	]}
/>


# CodeBlock (/docs/components/code-block)

<ComponentMeta file="code-block" primitive="HTML pre and code" pattern="Code sample with a copy button" />

<Playground
	name="code-block/playground"
	component="CodeBlock"
	controls={[
		{ prop: "showLineNumbers", default: true },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It is a client component, because of the copy button.

<Import names="CodeBlock" />

## Anatomy [#anatomy]

A header with the file name, the language and the copy button, then a `<pre>` that scrolls sideways when lines are long. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "code-block",
		tag: "div",
		children: [
			{
				slot: "code-block-header",
				tag: "div",
				row: true,
				children: [
					{
						slot: "code-block-title",
						tag: "span",
						row: true,
						children: [
							{ slot: "code-block-filename", tag: "span", note: "optional" },
							{ slot: "code-block-language", tag: "span", note: "optional" },
						],
					},
					{ slot: "code-block-copy", tag: "button" },
				],
			},
			{
				slot: "code-block-pre",
				tag: "pre",
				note: "scrolls when wide",
				children: [
					{
						slot: "code-block-code",
						tag: "code",
						children: [
							{
								slot: "code-block-line",
								tag: "span",
								row: true,
								children: [
									{ slot: "code-block-line-number", tag: "span" },
									{ slot: "code-block-line-content", tag: "span", children: [{ slot: "code-token", tag: "span" }] },
								],
							},
						],
					},
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="code-block/basic" compact />

<ExampleGrid>
	<Example name="code-block/with-filename" title="File name and language">
		When people must paste the code into a specific file, put its path in `filename`. The `language` badge tells them the syntax at a glance.
	</Example>
	<Example name="code-block/no-line-numbers" title="Terminal command">
		Turn off line numbers for a one-line command: there is nothing to point at, and the command reads as one piece.
	</Example>
	<Example name="code-block/languages" title="JSON and other formats">
		The built-in highlighter colors strings, comments and JavaScript keywords. That is enough for JSON or a shell command. `language` also sets the comments: `#` for Bash, Python or YAML, `//` for the rest.
	</Example>
	<Example name="code-block/custom-highlight" title="Marked lines">
		Pass `highlight` to render each line yourself, like the lines of a diff. Keep the + and - in the text, so the change doesn't depend on color.
	</Example>
	<Example name="code-block/long-lines" title="Long lines scroll">
		Long lines scroll sideways instead of wrapping, so a command stays copyable as it is. Keyboard users Tab into the code and scroll with the arrow keys.
	</Example>
	<Example name="code-block/interactive-tabs" title="One command per package manager">
		Pick a tab. Tabs show one command at a time and keep the choice clear, instead of four blocks stacked on top of each other.
	</Example>
	<Example name="code-block/copy-status" title="Name the copy and announce it">
		Say what the button copies in `copyLabel`, like "Copy install command". After the copy, `copiedLabel` shows on the button and screen readers hear it too.
	</Example>
</ExampleGrid>

## In context [#in-context]

Code blocks usually sit in a card or a guide, right after the sentence that explains them. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="code-block/context-install" title="Install step" uses="Card · CodeBlock · Button" />
	<Context name="code-block/context-api" title="API endpoint" uses="Card · Badge · CodeBlock" />
	<Context name="code-block/context-config" title="Setup guide" uses="Card · CodeBlock" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="code-block/do-semantic-filename" title="Say where the code goes.">
		A file path like `app/blog/page.tsx` tells people which file to open before they paste.
	</Guideline>
	<Guideline kind="dont" name="code-block/dont-unlabeled-block" title="A snippet with no file.">
		People have to guess whether the line goes in a page, a layout or a config file.
	</Guideline>
	<Guideline kind="do" name="code-block/do-short-excerpt" title="Show only the lines that matter.">
		Cut the rest with a `// …` comment. People see the change at once and copy less by mistake.
	</Guideline>
	<Guideline kind="dont" name="code-block/dont-huge-scroll" title="The whole file for a one-line change.">
		People have to hunt for the line you mean, and the copy button copies all of it.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="code-block"
	type="CodeBlockProps"
	include={["code", "language", "filename", "showLineNumbers", "copyLabel", "copiedLabel", "highlight"]}
	types={{ highlight: "(line, lineNumber) => ReactNode" }}
>
	Native `<div>` attributes go to the root. There is no prop for the `<pre>` or a callback for the copy.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the block itself.

<StylingHooks
	slots={[
		"code-block",
		"code-block-header",
		"code-block-title",
		"code-block-filename",
		"code-block-language",
		"code-block-copy",
		"code-block-pre",
		"code-block-code",
		"code-block-line",
		"code-block-line-number",
		"code-block-line-content",
		"code-token",
	]}
	prefix="code"
	attributes={[
		{ attr: "data-copied", value: "on the copy button, for 1.8 s after a click" },
		{ attr: "data-token", value: "comment · string · keyword · function, from the built-in highlighter" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to the copy button, then to the code, but only when the code is wider than the block. Code that fits adds no Tab stop." },
		{ key: "Enter / Space", description: "Copies the code while the copy button has focus." },
		{ key: "← / →", description: "Scroll long lines sideways while the code has focus." },
	]}
	notes={[
		"The copy button's text is its name. With several blocks on a page, make copyLabel say what it copies.",
		"After a successful copy the button reads copiedLabel for 1.8 seconds, and a status message announces it. If the clipboard is blocked, nothing changes and the code stays selectable.",
		"Line numbers are aria-hidden, so screen readers read the code without them.",
		"Code wider than the block becomes a scroll region (role=\"region\") named by the filename, the language or \"Code\" (from the MessagesProvider), so keyboard users can scroll it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Kbd", href: "/docs/components/kbd", description: "A key or shortcut inside a sentence, like Ctrl + C." },
		{ title: "Typography", href: "/docs/components/typography", description: "Headings and text around the code, including inline code." },
		{ title: "Card", href: "/docs/components/card", description: "The surface that holds a code sample and its explanation." },
	]}
/>


# Combobox (/docs/components/combobox)

<ComponentMeta file="combobox" primitive="Base UI" pattern="WAI-ARIA Combobox" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the parts you need, plus `ComboboxEmpty` for the no-results message. The skin you load styles the input and the popup.

<Import names="Combobox, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem" />

## Anatomy [#anatomy]

`Combobox` holds the items and the value; `ComboboxInput` is the text field with its clear and open buttons; the content is a popup rendered in a portal. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="combobox-input-group"]', color: "#8be36f" },
		{ label: '[data-slot="combobox-clear"] · [data-slot="combobox-trigger"]', color: "#ffcf7a" },
		{ label: '[data-slot="combobox-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">Curitiba</span>
	<span className="a-part">✕</span>
	<span className="a-part">⌄</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="combobox/basic" compact />

<ExampleGrid>
	<Example name="combobox/empty" title="Empty state">
		Type a name that isn't there. `ComboboxEmpty` only shows when nothing matches, so use it to say what to do next, not just "No results".
	</Example>
	<Example name="combobox/objects" title="Objects as items">
		Store the code, show the name: `itemToStringLabel` fills the input, `itemToStringValue` goes to the form, `isItemEqualToValue` compares them.
	</Example>
	<Example name="combobox/controlled" title="Controlled">
		Pick someone. With `value` and `onValueChange` the rest of the screen can follow the choice as it happens.
	</Example>
	<Example name="combobox/filter" title="Custom filter">
		Type "gru" or "galeao". A `filter` function can match codes, nicknames or text without accents, whatever people actually type.
	</Example>
	<Example name="combobox/auto-highlight" title="Enter picks the first match">
		`autoHighlight` highlights the first result as you type, so a short query and Enter is enough for tags and labels.
	</Example>
	<Example name="combobox/labels" title="Named buttons">
		The clear and open buttons are icons. Translate their names with `clearLabel` and `triggerLabel`, and make them specific to the field.
	</Example>
	<Example name="combobox/validation" title="Required, with an error" wide>
		Inside a `Field`, the label names the input and `FieldError` is read with it; tell people to pick from the list, since free text won't be accepted.
	</Example>
</ExampleGrid>

## In context [#in-context]

A combobox is usually one field among several. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="combobox/context-assign" title="Assign an issue" uses="Card · Field · Combobox · Select · Button" />
	<Context name="combobox/context-delivery" title="Delivery estimate" uses="Fieldset · Field · Combobox · Input · Button" />
	<Context name="combobox/context-timezone" title="Time zone setting" uses="Card · Switch · Field · Combobox" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="combobox/do-long-list" title="Long lists people can name.">
		Nobody wants to scroll through 27 state capitals; typing "flo" is faster.
	</Guideline>
	<Guideline kind="dont" name="combobox/dont-short-list" title="Search for three options.">
		Typing is extra work when everything fits on screen; use a Select or radios.
	</Guideline>
	<Guideline kind="do" name="combobox/do-hint" title="Say what to type.">
		A label, an example in the placeholder and a hint about what is covered.
	</Guideline>
	<Guideline kind="dont" name="combobox/dont-generic" title="Just “Search…”.">
		Search what? With no visible label, people guess the scope and the format.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="combobox" type="ComboboxInputProps" include={["disabled", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
>
	These are the props of `ComboboxInput`; other input attributes like `placeholder` pass through. `Combobox` takes Base UI's root props: `items`, `value`, `defaultValue`, `onValueChange`, `inputValue` / `onInputValueChange`, `filter`, `itemToStringLabel`, `itemToStringValue`, `isItemEqualToValue`, `autoHighlight`, `limit`, `multiple`, `disabled`, `required` and `name`. `ComboboxList` takes a function of each item; `ComboboxItem` takes `value` and `disabled`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the combobox itself.

<StylingHooks
	slots={["combobox-input-group", "combobox-input", "combobox-clear", "combobox-trigger", "combobox-popup", "combobox-item", "combobox-empty"]}
	prefix="combobox"
	attributes={[
		{ attr: "data-slot", value: '"combobox-input-group" · "combobox-input" · "combobox-clear" · "combobox-trigger" · "combobox-positioner" · "combobox-popup" · "combobox-list" · "combobox-item" · "combobox-empty"' },
		{ attr: "data-popup-open", value: "on the input and trigger while the list is open" },
		{ attr: "data-highlighted", value: "on the item under the keyboard or pointer" },
		{ attr: "data-selected", value: "on the chosen item" },
		{ attr: "data-disabled", value: "on a disabled input or item" },
		{ attr: "data-invalid", value: "on the input inside an invalid Field" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Typing", description: "Filters the list and opens it." },
		{ key: "↓ / ↑", description: "Opens the list, then moves the highlight; focus stays in the input." },
		{ key: "Enter", description: "Picks the highlighted item and closes the list." },
		{ key: "Esc", description: "Closes the list and keeps what you typed." },
		{ key: "Tab", description: "Leaves the field, closing the list." },
	]}
	notes={[
		"The input has role=\"combobox\" with aria-expanded and aria-activedescendant, so screen readers follow the highlight while you keep typing.",
		"Inside a Field, FieldLabel names the input; outside one, give the input an aria-label.",
		"The clear and open buttons need names: set clearLabel and triggerLabel in the page's language.",
		"The popup is portalled but keeps the skin through PortalScope, and contrast passes WCAG 2.2 AA in all 13 skins.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Select", description: "Pick from a short list without typing.", href: "/docs/components/select" },
		{ title: "CommandPalette", description: "Search actions, not values.", href: "/docs/components/command-palette" },
		{ title: "TagsInput", description: "Type several free values.", href: "/docs/components/tags-input" },
	]}
/>


# CommandPalette (/docs/components/command-palette)

<ComponentMeta file="command-palette" primitive="Base UI" pattern="WAI-ARIA Dialog (Modal) + Combobox" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="CommandPalette, CommandPaletteTrigger, CommandPaletteContent, CommandPaletteInput, CommandPaletteList, CommandPaletteGroup, CommandPaletteItem, CommandPaletteEmpty, CommandPaletteFooter" />

## Anatomy [#anatomy]

`CommandPaletteContent` renders the backdrop and the dialog in a portal. Focus stays in the search; the arrow keys move a highlight through the list with `aria-activedescendant`.

<Anatomy
	tree={{
		slot: "command-palette-dialog",
		tag: "div",
		note: "role=dialog, in a portal after command-palette-backdrop",
		children: [
			{
				slot: "command-palette-header",
				tag: "div",
				row: true,
				children: [
					{ slot: "command-palette-search-icon", tag: "span" },
					{ slot: "command-palette-input", tag: "input", note: "role=combobox" },
				],
			},
			{
				slot: "command-palette-list",
				tag: "div",
				note: "role=listbox, scrolls",
				children: [
					{
						slot: "command-palette-group",
						tag: "div",
						note: "role=group, optional",
						children: [
							{ slot: "command-palette-group-label", tag: "span" },
							{
								slot: "command-palette-item",
								tag: "div",
								note: "role=option",
								row: true,
								children: [
									{ slot: "command-palette-item-icon", tag: "span" },
									{ slot: "command-palette-item-text", tag: "span" },
									{ slot: "command-palette-item-shortcut", tag: "span" },
								],
							},
						],
					},
				],
			},
			{ slot: "command-palette-empty", tag: "div", note: "when nothing matches" },
			{ slot: "command-palette-footer", tag: "div", note: "optional" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy, in the skin, mode and brand from the bar above. Each one starts closed: open it, type, use the arrows and Enter, then Esc. The palette doesn't filter on its own. Keep the query in state, render only the commands that match, and give `CommandPaletteList` a `key={query}`, so the arrow keys follow the new order.

<Preview name="command-palette/basic" compact />

<ExampleGrid>
	<Example name="command-palette/shortcut" title="Ctrl+K and command shortcuts">
		Press Ctrl+K anywhere on this page. The button stays as the visible way in, and each command shows its own shortcut so people learn it.
	</Example>
	<Example name="command-palette/groups" title="Groups: Navigation, Actions, Recent">
		Headings help people scan a long list. A group with no matches disappears with its heading, and the highlight scrolls into view.
	</Example>
	<Example name="command-palette/synonyms" title="Keywords and synonyms">
		Type "receipt" or "add user". People search with their own words, so match keywords too and say which one matched.
	</Example>
	<Example name="command-palette/empty" title="Empty state">
		Repeat what was searched and suggest what to try. The query stays in the box so it's easy to fix.
	</Example>
	<Example name="command-palette/async" title="Results from the server">
		Type a name. While the request runs, the list has `aria-busy` and the footer says "Searching…"; a newer search makes the old one stale.
	</Example>
	<Example name="command-palette/nested" title="Pages inside the palette">
		"Change theme…" opens a page of options. Esc or Backspace in an empty search goes back one level before closing.
	</Example>
	<Example name="command-palette/a11y-announce" title="Counts and results announced">
		The footer count is a polite status, read when typing pauses. After a command runs, a status outside the palette says what happened.
	</Example>
	<Example name="command-palette/disabled" title="A command you can't run">
		Keep it in the list with `aria-disabled` and say why. People find it, learn who can do it, and Enter does nothing.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="command-palette/context-dashboard" title="Dashboard header search" uses="CommandPalette · Button · Avatar · Stat · Card" />
	<Context name="command-palette/context-docs-search" title="Docs site search" uses="CommandPalette · Button · Kbd · Card" />
	<Context name="command-palette/context-go-to-file" title="Editor: Go to file" uses="CommandPalette · Tabs · Button · Card" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="command-palette/do-visible-path" title="A shortcut to things already on the page.">
		Creating and exporting have their own buttons. The palette is the faster way for people who know what they want.
	</Guideline>
	<Guideline kind="dont" name="command-palette/dont-palette-only" title="Actions that live only in the palette.">
		Nobody browses a search box. If "Create invoice" isn't on the page, most people never find it.
	</Guideline>
	<Guideline kind="do" name="command-palette/do-verb-labels" title="Short labels that start with a verb.">
		"Send payment reminder" says what will happen, and the first word is what people type.
	</Guideline>
	<Guideline kind="dont" name="command-palette/dont-vague-labels" title="Nouns and long sentences.">
		"Invoice" could open, create or delete one. A sentence gets cut off and is hard to match.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="command-palette"
	type="CommandPaletteProps"
	include={["open", "defaultOpen", "onOpenChange", "modal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ open: "Whether the palette is open. Use it with `onOpenChange` to control the state.", defaultOpen: "Whether it starts open. Leave it off: a palette should open when people ask for it.", onOpenChange: "Called when it opens or closes. `eventDetails.reason` says why, for example `escape-key`.", modal: "`true` traps focus and hides the page behind from screen readers. Keep the default." }}
>
	`CommandPaletteContent`, `CommandPaletteList`, `CommandPaletteEmpty` and `CommandPaletteFooter` take the props of their `div`; pass `aria-label` to the content and the list. `CommandPaletteInput` takes the props of an `input`, including `value`, `onChange` and `aria-label`. `CommandPaletteTrigger` takes `render`.
</Props>

Each command is a `CommandPaletteItem`:

<Props file="command-palette" type="CommandPaletteItemProps" include={[]}>
	`onSelect` runs the command, on a click or on Enter while the item is highlighted. It also takes the props of its `div`, like `aria-disabled`, `aria-keyshortcuts` and `onMouseDown`. `CommandPaletteGroup` takes `label`, its visible heading.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the palette itself.

<StylingHooks
	slots={["command-palette-backdrop", "command-palette-dialog", "command-palette-header", "command-palette-search-icon", "command-palette-input", "command-palette-list", "command-palette-group", "command-palette-group-label", "command-palette-item", "command-palette-item-icon", "command-palette-item-text", "command-palette-item-shortcut", "command-palette-empty", "command-palette-footer"]}
	prefix="cmd"
	attributes={[
		{ attr: "data-active · aria-selected=\"true\"", value: "on the highlighted command" },
		{ attr: "aria-disabled=\"true\"", value: "a command that can't run; shown muted" },
		{ attr: "data-value", value: "the item's value prop" },
		{ attr: "data-open · data-closed", value: "on the dialog and the backdrop" },
	]}
>

```css
/* a taller list for the file finder */
.editor [data-slot="command-palette-list"] {
  max-height: 24rem;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Ctrl + K / ⌘ + K", description: "Opens the palette from anywhere on the page, and closes it when it's open. Only with the shortcut prop on, and not while typing in another text field, where editors use Ctrl+K for links." },
		{ key: "Enter / Space", description: "On the trigger, opens the palette with focus in the search." },
		{ key: "↓ / ↑", description: "Moves the highlight to the next or previous command, wrapping at the ends. Focus stays in the search." },
		{ key: "Enter", description: "Runs the highlighted command." },
		{ key: "Esc", description: "Closes the palette and returns focus to the element that had it. It doesn't clear the search first." },
		{ key: "Tab", description: "Stays in the search: it's the only control in the dialog." },
	]}
	notes={[
		"The dialog is modal and needs a name: pass aria-label to CommandPaletteContent, and another to CommandPaletteInput, in the page's language.",
		"The search is a combobox with aria-expanded and aria-controls pointing to the listbox. aria-activedescendant follows the highlight, so screen readers read each command as you move.",
		"Results change silently. Put the count in a role=\"status\" inside the palette, and after a command runs, report the result in a status outside it: the palette is gone and focus is back on the trigger.",
		"Ctrl+K listens on the whole page. Leave shortcut on for one palette only and turn it off on the others, or one key press opens them all.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Combobox", description: "Search a list to pick a value for a form field.", href: "/docs/components/combobox" },
		{ title: "Dialog", description: "The modal window the palette is built on.", href: "/docs/components/dialog" },
		{ title: "Kbd", description: "Show the keys of a shortcut next to a command.", href: "/docs/components/kbd" },
	]}
/>


# Container (/docs/components/container)

<ComponentMeta file="layout" pattern="CSS max-inline-size + margin-inline: auto" />

<Playground
	name="container/playground"
	component="Container"
	controls={[{ prop: "size", options: ["sm", "md", "lg", "xl"], default: "sm" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It has no state, so it renders on the server.

<Import names="Container" />

## Anatomy [#anatomy]

One element. The size arrives as the `--cml-container-max` custom property, so your own CSS can still change it.

<Anatomy
	tree={{
		slot: "container",
		tag: "div",
		note: "or the tag in as · centred, padded · your content inside",
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. The bordered box in each one stands for the browser window; widen and narrow your own window to see the column follow.

<Preview name="container/basic" compact />

<ExampleGrid>
	<Example name="container/sizes" title="Four sizes" wide>
		Pick a size. The drawing is a 1440 px screen shrunk to fit, so you see the real proportions: `sm` for reading and forms, `lg` (the default) for most pages, `xl` for tables.
	</Example>
	<Example name="container/reading-width" title="Reading width">
		Long text reads best at 60–75 characters a line. Set `--cml-container-max: 65ch` and the column follows the font, not the screen.
	</Example>
	<Example name="container/full-bleed" title="Full-bleed section" wide>
		Put the background on an outer `section` and the Container inside it: the colour runs edge to edge, the text stays in line with the rest of the page.
	</Example>
	<Example name="container/phone-padding" title="Padding on phones">
		Turn on the wider gutter. Below its maximum, the column fills the screen but keeps 1rem at each side; change `--cml-container-padding` for more air.
	</Example>
	<Example name="container/narrow-form" title="A narrow form">
		A sign-up form doesn't need the page's width. `size="sm"` keeps every label, field and the button within one glance.
	</Example>
	<Example name="container/landmark" title="As a landmark">
		Container is a plain `div`. Pass `as="main"`, `as="article"` or `as="section"` with a label, so screen reader users can jump straight to the column.
	</Example>
</ExampleGrid>

## In context [#in-context]

Containers frame whole pages. These are pieces you can copy, in the skin you picked.

<ContextGrid>
	<Context name="container/context-article" title="Blog article" uses="Container · Heading · Text · Image · Badge" />
	<Context name="container/context-marketing" title="Landing page section" uses="Container · Grid · Badge · Button" />
	<Context name="container/context-settings" title="Settings page" uses="Container · Card · Field · Switch · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="container/do-full-bleed" title="Colour on the section, content in the container.">
		The band reaches both edges on any screen, and its text lines up with the page.
	</Guideline>
	<Guideline kind="dont" name="container/dont-boxed-band" title="A background on the container itself.">
		On wide screens the colour stops at the column and looks like a misplaced card.
	</Guideline>
	<Guideline kind="do" name="container/do-reading-width" title="A narrow column for long text.">
		Short lines let the eye find the start of the next one.
	</Guideline>
	<Guideline kind="dont" name="container/dont-wide-text" title="Articles across an xl column.">
		Lines of 150 characters are tiring, and readers lose their place.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="layout" type="ContainerProps">
	Every attribute of the rendered element passes through, like `id`, `aria-labelledby` or `style`. Don't nest containers: the padding adds up on phones.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: set the custom properties on the container, on a parent or in a skin.

<StylingHooks
	slots={["container"]}
	prefix="container"
	attributes={[
		{ attr: "data-slot", value: '"container"' },
		{ attr: "--cml-container-max", value: "40rem · 48rem · 64rem · 80rem, from size" },
		{ attr: "--cml-container-padding", value: "inline padding, 1rem by default" },
	]}
>

```css
/* a roomier gutter on tablets and up */
@media (min-width: 48rem) {
  [data-slot="container"] {
    --cml-container-padding: 2rem;
  }
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Container isn't interactive and takes no focus. Tab goes straight to the links and fields inside it." }]}
	notes={[
		"It renders a div with no role. Use as=\"main\" for the page's main column, so screen readers can jump to it.",
		"The width is capped in rem, so it grows with the reader's font size and zoom; at 400% zoom the column simply fills the screen, with no sideways scrolling.",
		"The padding keeps text off the screen edge on phones, where rounded corners and cases would otherwise cut it.",
		"Changing the size never changes the reading order: the content stays in source order at every width.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Typography", description: "Headings and text for what goes inside the column.", href: "/docs/components/typography" },
		{ title: "Card", description: "A surface for one group of content inside the page.", href: "/docs/components/card" },
		{ title: "AspectRatio", description: "Media that keeps its shape at any column width.", href: "/docs/components/aspect-ratio" },
	]}
/>


# Context menu (/docs/components/context-menu)

<ComponentMeta file="context-menu" primitive="Base UI" pattern="WAI-ARIA Menu" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the parts you need. The popup renders in a portal, at the pointer, and keeps the skin, mode and brand of the page around it.

<Import names="ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuSeparator" />

## Anatomy [#anatomy]

`ContextMenu` holds the open state. `ContextMenuTrigger` (`data-slot="context-menu-trigger"`) is the area people right-click; `ContextMenuContent` renders the popup below in a portal. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "context-menu-positioner",
		tag: "div",
		note: "in a portal, at the pointer",
		children: [
			{
				slot: "context-menu-popup",
				tag: "div",
				note: "role=menu",
				children: [
					{ slot: "context-menu-group-label", tag: "div" },
					{
						slot: "context-menu-item",
						tag: "div",
						row: true,
						children: [
							{ slot: "context-menu-item-icon", tag: "span" },
							{ slot: "context-menu-item-label", tag: "span" },
							{ slot: "context-menu-item-shortcut", tag: "span" },
						],
					},
					{
						slot: "context-menu-checkbox-item",
						tag: "div",
						row: true,
						children: [
							{ slot: "context-menu-item-indicator", tag: "span" },
							{ slot: "context-menu-item-label", tag: "span" },
						],
					},
					{
						slot: "context-menu-radio-item",
						tag: "div",
						row: true,
						children: [
							{ slot: "context-menu-item-indicator", tag: "span", children: [{ slot: "context-menu-radio-dot", tag: "span" }] },
							{ slot: "context-menu-item-label", tag: "span" },
						],
					},
					{
						slot: "context-menu-sub-trigger",
						tag: "div",
						note: "opens context-menu-sub-popup",
						row: true,
						children: [
							{ slot: "context-menu-item-label", tag: "span" },
							{ slot: "context-menu-sub-arrow", tag: "span" },
						],
					},
					{ slot: "context-menu-separator", tag: "div" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above, and they all start closed: right-click them.

<Preview name="context-menu/basic" compact />

<ExampleGrid>
	<Example name="context-menu/file-row" title="On a file row">
		The classic use: the actions for one file, where the pointer already is. `tabIndex={0}` lets keyboard users focus the row and open the menu with Shift+F10 or the Menu key.
	</Example>
	<Example name="context-menu/canvas" title="On a canvas" wide>
		On an empty board there is nothing to put a button on, so the right-click is where people look. Keep the same commands in a toolbar.
	</Example>
	<Example name="context-menu/groups" title="Groups and separators">
		A `ContextMenuGroupLabel` over each group helps people scan a longer menu; the destructive group goes last.
	</Example>
	<Example name="context-menu/with-shortcuts" title="With shortcuts">
		People who right-click are learning. Show the shortcut with `Kbd` and add `aria-keyshortcuts`, so next time they skip the menu.
	</Example>
	<Example name="context-menu/interactive-status" title="Act, then announce">
		Right-click the note and pick an action. Focus goes back to the note, and a `role="status"` line says what happened.
	</Example>
	<Example name="context-menu/visible-path" title="Also in a visible menu">
		A context menu is hidden by nature. Put the same actions behind a "⋯" button, from one shared list, so touch, keyboard and screen reader users find them.
	</Example>
	<Example name="context-menu/view-options" title="Checkbox and radio items">
		Right-click the board and change its settings: `ContextMenuCheckboxItem` and `ContextMenuRadioItem` keep the menu open and report `aria-checked`, so people can change several at once.
	</Example>
	<Example name="context-menu/submenu" title="Submenu">
		Put a list of destinations behind one "Move to" item instead of stretching the menu; → opens it, ← goes back, and the current folder is disabled.
	</Example>
</ExampleGrid>

## In context [#in-context]

A context menu speeds up work that already has a visible path. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="context-menu/context-file-manager" title="File manager" uses="ContextMenu · Menu · IconButton" />
	<Context name="context-menu/context-kanban-card" title="Kanban card" uses="Card · Badge · ContextMenu" />
	<Context name="context-menu/context-chat-message" title="Chat message" uses="Avatar · ContextMenu · Menu" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="context-menu/do-visible-path" title="The same actions behind a visible button.">
		The right-click is a shortcut for people who know it; the "⋯" button is the way in for everyone else.
	</Guideline>
	<Guideline kind="dont" name="context-menu/dont-hidden-only" title="Actions only on right-click.">
		Nothing on screen says they exist, and on a phone or with a screen reader nobody finds them.
	</Guideline>
	<Guideline kind="do" name="context-menu/do-contextual" title="Actions for the thing under the pointer.">
		Right-click a comment: reply, edit, copy. The menu answers "what can I do with this?".
	</Guideline>
	<Guideline kind="dont" name="context-menu/dont-global" title="App-wide commands.">
		Settings and Sign out have nothing to do with the comment, and they belong in the header where people expect them.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="context-menu" type="ContextMenuItemProps" include={["onClick", "closeOnClick", "disabled", "label", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ onClick: "Runs when the item is chosen with a click, Enter or Space.", closeOnClick: "Whether choosing the item closes the menu.", disabled: "Disables the item. It stays focusable, so people can still read it.", label: "Text for typeahead when the item's content is not plain text.", render: "Renders another element, such as an `<a>` for a link." }}
>
	These are the props of `ContextMenuItem`. `ContextMenu` takes Base UI's root props: `open`, `onOpenChange`, `disabled` and `actionsRef`. `ContextMenuCheckboxItem` takes `checked`, `defaultChecked`, `onCheckedChange` and `shortcut`; `ContextMenuRadioGroup` takes `value`, `defaultValue` and `onValueChange`, and each `ContextMenuRadioItem` a `value`. Wrap a `ContextMenuSubTrigger` and its `ContextMenuSubContent` in a `ContextMenuSub`. `ContextMenuTrigger` renders a `<div>`: give it `tabIndex={0}` so it can be focused, or `render` to use another element.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the popup itself.

<StylingHooks
	slots={["context-menu-trigger", "context-menu-popup", "context-menu-item", "context-menu-item-icon", "context-menu-item-label", "context-menu-item-shortcut", "context-menu-checkbox-item", "context-menu-radio-item", "context-menu-item-indicator", "context-menu-radio-dot", "context-menu-sub-trigger", "context-menu-sub-arrow", "context-menu-sub-popup", "context-menu-group-label", "context-menu-separator"]}
	prefix="context-menu"
	attributes={[
		{ attr: "data-popup-open", value: "on the trigger while the menu is open" },
		{ attr: "data-highlighted", value: "on the item under the keyboard or pointer" },
		{ attr: "data-checked · data-unchecked", value: "on checkbox and radio items" },
		{ attr: "data-disabled", value: "on a disabled item" },
		{ attr: "data-tone", value: "danger" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Shift+F10 / Menu", description: "On a focused trigger: opens the menu and moves focus into it." },
		{ key: "↓ / ↑", description: "Reaches the first or last item, then moves between items, wrapping at the ends." },
		{ key: "Home / End", description: "Jumps to the first or last item." },
		{ key: "A–Z", description: "Jumps to the next item that starts with that letter." },
		{ key: "Enter / Space", description: "Chooses the item; on a checkbox or radio item, toggles it and keeps the menu open." },
		{ key: "→ / ←", description: "On a submenu trigger, → opens the submenu on its first item; inside it, ← closes it and goes back." },
		{ key: "Esc", description: "Closes the submenu, or the menu, and returns focus to the trigger." },
		{ key: "Tab", description: "Closes the whole menu, submenus included, and returns focus to where it was." },
	]}
	notes={[
		"Nothing on screen says a context menu exists. Every action in it must also be reachable from a visible button or menu.",
		"Items are menuitem; checkbox items are menuitemcheckbox and radio items menuitemradio, both with aria-checked. A submenu trigger reports aria-haspopup and aria-expanded.",
		"The trigger is a <div>: add tabIndex={0} so keyboard users can focus it and open the menu with Shift+F10 or the Menu key. Rows that already have a \"⋯\" button can skip it and save a tab stop.",
		"On touch screens a long press opens it; screen reader users rarely find it, which is one more reason for the visible path.",
		"The popup is portalled but keeps the skin through PortalScope, and contrast passes WCAG 2.2 AA in all 13 skins.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Menu", description: "The same list of actions, opened from a visible button.", href: "/docs/components/menu" },
		{ title: "Kbd", description: "Shows the shortcut next to each action.", href: "/docs/components/kbd" },
		{ title: "Button", description: "For the one or two actions people use most.", href: "/docs/components/button" },
	]}
/>


# DataList (/docs/components/data-list)

<ComponentMeta file="data-display" primitive="HTML dl" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="DataList, DataListTerm, DataListDetail, DataListItem" />

## Anatomy [#anatomy]

A native description list: a two-column grid where each term (`<dt>`) sits next to its value (`<dd>`). `DataListItem` renders one pair without adding a wrapper.

<Anatomy
	tree={{
		slot: "data-list",
		tag: "dl",
		note: "two-column grid",
		row: true,
		children: [
			{ slot: "data-list-term", tag: "dt" },
			{ slot: "data-list-detail", tag: "dd" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="data-list/basic" compact />

<ExampleGrid>
	<Example name="data-list/with-badge" title="Status as a badge">
		Put a badge in the value when it is a state people scan for, like Paid. Plain text is easier to read for everything else.
	</Example>
	<Example name="data-list/missing-value" title="Missing values">
		Keep the row and say what is missing, like "Not provided", in a quieter color. A dash or an empty cell is easy to miss, and some screen readers skip it.
	</Example>
	<Example name="data-list/links-and-actions" title="Email and phone links">
		Make a value a link when it opens something, like `mailto:` or `tel:`. The link text is the value itself, so it still reads well out of context.
	</Example>
	<Example name="data-list/multiline-detail" title="Long values">
		Addresses and notes wrap onto several lines. Align the term to the top, so it stays next to the first line instead of floating in the middle.
	</Example>
	<Example name="data-list/term-shorthand" title="Pairs from data">
		When the pairs come from an array, map them to `DataListItem` with `term`. It renders the `<dt>` and `<dd>` for you, with no extra element inside the `<dl>`.
	</Example>
	<Example name="data-list/interactive-copy" title="Copy a value">
		Click the button to copy the key. Its name says what it copies, and a status message announces the result, because a new icon alone says nothing to a screen reader.
	</Example>
</ExampleGrid>

## In context [#in-context]

A data list usually sits below a heading that names the record, with the record's actions next to it. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="data-list/context-order-details" title="Order summary" uses="DataList · Badge · Button" />
	<Context name="data-list/context-profile" title="Team member profile" uses="DataList · Avatar · Badge · Link" />
	<Context name="data-list/context-specs" title="Server details" uses="DataList · Badge · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="data-list/do-name-missing" title="Say when a value is missing.">
		"Not provided" tells people the field exists and is empty, not that the page failed to load.
	</Guideline>
	<Guideline kind="dont" name="data-list/dont-blank-values" title="An empty value.">
		A blank cell looks like a bug, and people can't tell whether the data is missing or still loading.
	</Guideline>
	<Guideline kind="do" name="data-list/do-short-terms" title="Keep terms to one or two words.">
		People scan the terms to find a row. Short terms leave room for the values, even on a phone.
	</Guideline>
	<Guideline kind="dont" name="data-list/dont-long-terms" title="A sentence as the term.">
		The term column grows, the values get squeezed, and the heading above already gives the context.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="data-display" type="DataListItemProps">
	`DataList`, `DataListTerm` and `DataListDetail` take the attributes of `<dl>`, `<dt>` and `<dd>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slots, or set the tokens on a parent, a skin or the list itself.

<StylingHooks slots={["data-list", "data-list-term", "data-list-detail"]} prefix="data-list" />

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "Moves to links and buttons inside the values. The list itself takes no focus." }]}
	notes={[
		"DataList renders a native <dl>, so screen readers announce a list and read each term with its value.",
		"Put DataListTerm and DataListDetail straight inside DataList, in pairs. DataListItem adds no wrapper, so it is safe too.",
		"Name the record with a heading above the list, so people can jump to it and know whose details these are.",
		"Buttons inside a value need a name that says what they act on, like \"Copy publishable key\", and a status message for the result.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Table", description: "Rows and columns, to compare several records.", href: "/docs/components/table" },
		{ title: "Stat", description: "One number with a label, for a dashboard.", href: "/docs/components/stat" },
		{ title: "Badge", description: "A short status inside a value.", href: "/docs/components/badge" },
	]}
/>


# DataTable (/docs/components/data-table)

<ComponentMeta file="data-table" primitive="TanStack Table" pattern="WAI-ARIA table" />

<Playground
	name="data-table/playground"
	component="DataTable"
	controls={[
		{ prop: "selectable", type: "boolean", default: true },
		{ prop: "loading", type: "boolean", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the table and the column type. It runs on the client.

<Import names="DataTable, type ColumnDef" />

## Anatomy [#anatomy]

A native `<table>` inside a container that scrolls sideways when the table is too wide, with a footer for the status and the pages. The footer only shows when the table is selectable or has more than one page.

<Anatomy
	tree={{
		slot: "data-table",
		tag: "div",
		children: [
			{
				slot: "data-table-container",
				tag: "div",
				note: "scrolls when wide",
				children: [
					{
						slot: "data-table-table",
						tag: "table",
						children: [
							{
								slot: "data-table-header",
								tag: "thead",
								children: [
									{
										slot: "data-table-header-row",
										tag: "tr",
										children: [
											{
												slot: "data-table-head",
												tag: "th",
												children: [
													{
														slot: "data-table-sort-button",
														tag: "button",
														note: "sortable columns",
														row: true,
														children: [{ slot: "data-table-sort-icon", tag: "span" }],
													},
												],
											},
										],
									},
								],
							},
							{
								slot: "data-table-body",
								tag: "tbody",
								children: [{ slot: "data-table-row", tag: "tr", row: true, children: [{ slot: "data-table-cell", tag: "td" }, { slot: "data-table-cell", tag: "td" }] }],
							},
						],
					},
				],
			},
			{
				slot: "data-table-footer",
				tag: "div",
				row: true,
				children: [
					{ slot: "data-table-status", tag: "span" },
					{ slot: "pagination", tag: "nav", note: "more than one page" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="data-table/basic" compact />

<ExampleGrid>
	<Example name="data-table/sorting" title="Sorting" wide>
		Click a header to sort. Numbers start with the biggest, text starts at A, and a third click goes back to the original order. Turn sorting off with `enableSorting: false` where the order means nothing, like an id.
	</Example>
	<Example name="data-table/selection" title="Row selection" wide>
		Use `selectable` when people act on several rows at once. Name each checkbox after its row with `selectRowLabel`, so a screen reader says which order it selects, not "Select row 2".
	</Example>
	<Example name="data-table/pagination" title="Pages" wide>
		Past a screenful of rows, set `pageSize`. Say which rows are showing in `selectionStatus`, and translate the page buttons with `previousLabel`, `nextLabel` and `pageLabel`.
	</Example>
	<Example name="data-table/loading-state" title="Loading" wide>
		Click Refresh. `loading` swaps the rows for skeletons, but skeletons say nothing to a screen reader, so a status message announces when loading starts and ends.
	</Example>
	<Example name="data-table/empty" title="No rows yet" wide>
		Pass an `EmptyState` to `emptyState`. The headers stay, so people see what the table will hold, and the message gives them the next step.
	</Example>
	<Example name="data-table/interactive-filter" title="Search" wide>
		Type a customer name. The table filters what you pass to `data`, a status line announces how many orders match, and Clear search sends focus back to the field.
	</Example>
	<Example name="data-table/row-actions" title="Actions in a row" wide>
		Icon buttons get a name with the row, like "Download invoice for #4821", because "Download" alone is the same in every row. The column header stays for screen readers with `VisuallyHidden`.
	</Example>
</ExampleGrid>

## In context [#in-context]

A data table is usually the main piece of an admin page, with actions above it. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="data-table/context-orders" title="Orders to ship" uses="DataTable · Button · Badge" wide />
	<Context name="data-table/context-users" title="Team members" uses="DataTable · Avatar · Badge" wide />
	<Context name="data-table/context-transactions" title="Account activity" uses="DataTable · Badge" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="data-table/do-right-align-numbers" title="Align numbers to the right.">
		Set `meta: { align: "end" }` on number columns. The digits get the same width, so the biggest value stands out.
	</Guideline>
	<Guideline kind="dont" name="data-table/dont-left-align-numbers" title="Numbers aligned to the left.">
		Thousands and hundreds start at the same place, and people have to read every value to compare them.
	</Guideline>
	<Guideline kind="do" name="data-table/do-sort-useful" title="Sort only the columns people sort by.">
		Here only the name sorts. Fewer buttons in the header means fewer Tab stops before the data.
	</Guideline>
	<Guideline kind="dont" name="data-table/dont-sort-everything" title="A sort button on every column.">
		Every column with an accessor sorts by default. Nobody sorts phone numbers, and each extra button is one more stop for keyboard users.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="data-table" type="DataTableProps">
	It also takes the attributes of a `<div>`, like `aria-busy` and `style`. Columns are TanStack `ColumnDef`s: `accessorKey` or `accessorFn`, `header`, `cell`, `enableSorting` and `meta.align`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the table itself.

<StylingHooks
	slots={[
		"data-table",
		"data-table-container",
		"data-table-table",
		"data-table-header",
		"data-table-header-row",
		"data-table-head",
		"data-table-sort-button",
		"data-table-sort-icon",
		"data-table-body",
		"data-table-row",
		"data-table-cell",
		"data-table-footer",
		"data-table-status",
	]}
	prefix="data-table"
	attributes={[
		{ attr: "data-align", value: "start · end, on heads and cells" },
		{ attr: "data-sorted", value: "asc · desc, on the sort button" },
		{ attr: "data-selected", value: "on a selected row" },
		{ attr: "data-selection-cell", value: "on the checkbox head and cells" },
		{ attr: "data-loading", value: "on skeleton rows" },
		{ attr: "data-empty", value: "on the empty row (data-empty-cell on its cell)" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves through the sort buttons, the checkboxes, the controls in cells and the page buttons. When the table is too wide, the scroll area is one extra stop." },
		{ key: "Enter / Space", description: "On a sort button, sorts by that column, then reverses it, then clears it. On a page button, goes to that page." },
		{ key: "Space", description: "Checks or unchecks the focused row checkbox, or every row from the header checkbox." },
		{ key: "← / →", description: "Scroll a wide table sideways while its scroll area has focus." },
	]}
	notes={[
		"The caption prop names the table. Say what the rows are, like \"Orders in October 2026\"; the default \"Data table\" tells people nothing.",
		"Sortable headers get aria-sort (ascending, descending or none), so screen readers say how the rows are sorted.",
		"The header checkbox turns indeterminate when only some rows are selected, and selected rows get aria-selected.",
		"Skeleton rows are silent. Add a role=\"status\" message for loading, and for result counts after a search.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Table", description: "A static table you write by hand, rendered on the server.", href: "/docs/components/table" },
		{ title: "Checkbox", description: "The control used for row selection, with the indeterminate state.", href: "/docs/components/checkbox" },
		{ title: "Empty state", description: "The message to show when the table has no rows.", href: "/docs/components/empty-state" },
	]}
/>


# Date field (/docs/components/date-field)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Spinbutton (one per segment)" />

<Playground
	name="date-field/playground"
	component="DateField"
	controls={[
		{ prop: "granularity", options: ["day", "hour", "minute"], default: "day" },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Values are `@internationalized/date` objects, re-exported from the package; put the field in a `Field` to give it a label.

<Import names="DateField, CalendarDate, CalendarDateTime, Field, FieldLabel" />

## Anatomy [#anatomy]

A box with one segment per part of the date. Literals like `/` are segments too, drawn for the eye and skipped by the keyboard.

<Anatomy
	keys={[
		{ label: '[data-slot="date-field"]', color: "#8be36f" },
		{ label: '[data-slot="date-input"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">input</span>
	<span className="a-label">11</span>
	<span className="a-label">16</span>
	<span className="a-label">2026</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="date-field/basic" compact />

<ExampleGrid>
	<Example name="date-field/controlled" title="Controlled">
		Type a new date. `onChange` gives you a `CalendarDate`, and `toString()` is the ISO date your API expects, with no time zone to go wrong.
	</Example>
	<Example name="date-field/birth-date" title="Birth date with limits">
		Change the year to 2008 or earlier. `minValue` and `maxValue` mark the field invalid, and a `FieldError` says which rule failed.
	</Example>
	<Example name="date-field/granularity" title="Date and time">
		Pass a `CalendarDateTime` and `granularity="minute"` when the time belongs to the date, like an appointment. Hours follow the locale's clock.
	</Example>
	<Example name="date-field/placeholder-value" title="Placeholder value">
		An empty field starts from today when people press the arrows. `placeholderValue` starts it closer to the answer, without filling anything in.
	</Example>
	<Example name="date-field/locales" title="Locales">
		The same 12 November 2026 in three locales: is it 11/12 or 12/11? `locale` sets the segment order and separators, so match it to the page's language.
	</Example>
	<Example name="date-field/read-only" title="Read-only">
		`readOnly` keeps the value focusable and readable by screen readers. Say in the description who can change it.
	</Example>
	<Example name="date-field/disabled" title="Disabled">
		`disabled` on the `Field` reaches the label and every segment. Tell people when it opens again.
	</Example>
</ExampleGrid>

## In context [#in-context]

Date fields come in forms. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="date-field/context-signup" title="Signup with date of birth" uses="Card · Field · Input · DateField · Button" />
	<Context name="date-field/context-passport" title="Travel document" uses="Card · Field · Input · DateField · Button" />
	<Context name="date-field/context-invoice" title="Invoice due date" uses="Card · DateField · NativeSelect · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="date-field/do-one-field" title="One field for a known date.">
		People type a birthday from memory; the segments take the digits in order.
	</Guideline>
	<Guideline kind="dont" name="date-field/dont-three-selects" title="Three selects for day, month and year.">
		Three lists to open and scroll, and nothing stops 31 February.
	</Guideline>
	<Guideline kind="do" name="date-field/do-error-message" title="Say which rule failed.">
		The message tells people what to change, and a screen reader reads it with the field.
	</Guideline>
	<Guideline kind="dont" name="date-field/dont-color-only" title="A red border and nothing else.">
		People see something is wrong, not what. Color alone is not an error message.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="DateFieldProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "placeholderValue", "granularity", "hourCycle", "hideTimeZone", "shouldForceLeadingZeros", "isDateUnavailable", "name", "autoFocus"]}
	types={{ value: "DateValue | null", defaultValue: "DateValue | null", onChange: "(value: DateValue | null) => void", minValue: "DateValue", maxValue: "DateValue", placeholderValue: "DateValue", granularity: "\"day\" | \"hour\" | \"minute\" | \"second\"", hourCycle: "12 | 24", isDateUnavailable: "(date: DateValue) => boolean" }}
	describe={{ className: "Classes added to the root.", style: "Inline styles for the root.", disabled: "Disables every segment. Inside a `Field`, the field's `disabled` is used when this is not set.", readOnly: "Keeps the value focusable and readable, but not editable.", invalid: "Marks the field invalid. Inside a `Field`, the field's `invalid` is used when this is not set.", required: "Marks the field required for assistive tech.", locale: "BCP 47 locale for the segment order, separators and clock, such as `\"en-US\"` or `\"pt-BR\"`. Defaults to the nearest `I18nProvider` or the browser's language." }}
>
	`validationBehavior` defaults to `"aria"`: an out-of-range value marks the field invalid but never blocks the form. React Aria's other props pass through, such as `onFocusChange`, `onKeyDown` and `form`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the field itself.

<StylingHooks
	slots={["date-field", "date-input", "date-segment"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"date-field" · "date-input" · "date-segment"' },
		{ attr: "data-invalid", value: "on the root and segments when invalid" },
		{ attr: "data-disabled · data-readonly", value: "on the root and segments when disabled · read-only" },
		{ attr: "data-placeholder", value: "on a segment with no value yet" },
		{ attr: "data-type", value: "a segment's part: day · month · year · hour · minute · literal…" },
		{ attr: "data-focused", value: "on the segment that has focus" },
	]}
>

```css
/* square, outlined segments, only in this form */
.passport-form [data-slot="date-field"] {
  --cml-segment-radius: 0;
  --cml-segment-focus-bg: transparent;
  --cml-segment-focus-fg: var(--cml-accent-text);
  --cml-segment-focus-shadow: inset 0 -2px 0 var(--cml-accent);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "0–9", description: "Types into the focused segment and moves to the next one when it is full." },
		{ key: "Arrow Up · Arrow Down", description: "Adds or subtracts one, wrapping at the end of the segment." },
		{ key: "Arrow Left · Arrow Right", description: "Moves between segments." },
		{ key: "Page Up · Page Down", description: "Steps by a bigger amount, like 5 years." },
		{ key: "Backspace", description: "Clears the focused segment." },
		{ key: "Tab", description: "Moves to the next segment, then out of the field." },
	]}
	notes={[
		"Each segment is a spinbutton named by its part (day, month, year) and the field's label, so people know which number they are changing.",
		"The whole value is read as text, such as \"November 16, 2026\", not as separate numbers.",
		"FieldDescription and FieldError are linked with aria-describedby, and an invalid field sets aria-invalid.",
		"Always pass locale: the server and the browser then format the same way, and segment names come in the page's language.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Date picker", description: "The same field with a calendar popover.", href: "/docs/components/date-picker" },
		{ title: "Time field", description: "Hours and minutes, with time zones.", href: "/docs/components/time-field" },
		{ title: "Field", description: "Label, description and error for a control.", href: "/docs/components/field" },
	]}
/>


# Date picker (/docs/components/date-picker)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Date Picker Dialog" />

<Playground
	name="date-picker/playground"
	component="DatePicker"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Dates are `@internationalized/date` objects, re-exported from the library. Put the picker in a `Field` to give it a label.

<Import names="DatePicker, CalendarDate, CalendarDateTime, isWeekend, Field, FieldLabel" />

## Anatomy [#anatomy]

A box with one editable segment per date part and a button that opens a `Calendar` in a popup. The popup renders in a portal and keeps the skin.

<Anatomy
	keys={[
		{ label: '[data-slot="date-picker"] · [data-slot="date-picker-control"]', color: "#8be36f" },
		{ label: '[data-slot="date-picker-trigger"] · [data-slot="date-picker-popup"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-input"] · [data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">11 / 14 / 2026</span>
	<span className="a-part">trigger</span>
	<span className="a-part">popup</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="date-picker/basic" compact />

<ExampleGrid>
	<Example name="date-picker/controlled" title="Controlled, with the weekday">
		Pick another day. Spelling out the weekday in the description catches a Saturday nobody meant to pick.
	</Example>
	<Example name="date-picker/min-max" title="Earliest and latest date">
		`minValue` and `maxValue` cross out the days outside the range. Check the value too and set `invalid` on the `Field`, so a typed date gets a message.
	</Example>
	<Example name="date-picker/unavailable" title="Unavailable dates">
		`isDateUnavailable` with `isWeekend` blocks weekends for the page's locale. Say the rule in the description, because the calendar is hidden until opened.
	</Example>
	<Example name="date-picker/with-time" title="Date and time">
		Pass a `CalendarDateTime` and `granularity="minute"` to add hour and minute segments. `hourCycle={24}` drops AM/PM where a 24-hour clock is clearer, like a webinar schedule.
	</Example>
	<Example name="date-picker/placeholder" title="Opens on the right month">
		Without a value the calendar opens on today. `placeholderValue` opens it where the dates that matter are, without filling the field.
	</Example>
	<Example name="date-picker/read-only" title="Read-only">
		`readOnly` keeps the date focusable and readable, unlike `disabled`. Say in the description who can change it.
	</Example>
	<Example name="date-picker/required" title="Required in a form">
		Send the form empty. The error names what is missing, is linked to the input and goes away as soon as a date is picked.
	</Example>
</ExampleGrid>

## In context [#in-context]

Dates are part of bigger tasks. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="date-picker/context-flight" title="Flight search" uses="Card · Field · Input · DatePicker · Button" />
	<Context name="date-picker/context-schedule" title="Schedule a post" uses="Card · Field · Textarea · DatePicker · Button" />
	<Context name="date-picker/context-invoice" title="Invoice due date" uses="Card · Field · Input · NativeSelect · DatePicker · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="date-picker/do-near-date" title="A calendar for dates close to today.">
		A delivery or a booking is a few clicks away, and the calendar shows the weekday.
	</Guideline>
	<Guideline kind="dont" name="date-picker/dont-birth-date" title="A calendar for a date of birth.">
		Paging back 30 years month by month is slow. Use a `DateField` and let people type it.
	</Guideline>
	<Guideline kind="do" name="date-picker/do-state-rule" title="Say which dates work.">
		The rule is visible before people open the calendar or type a date.
	</Guideline>
	<Guideline kind="dont" name="date-picker/dont-hidden-rule" title="A rule people find out by error.">
		"Date not available." comes too late and does not say which dates are.
	</Guideline>
</Guidelines>

## Props [#props]

`DatePicker` takes the props of the React Aria date picker. These are the ones you use most:

<Props
	file="date"
	type="DatePickerProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "placeholderValue", "granularity", "hourCycle", "firstDayOfWeek", "onOpenChange", "name"]}
	types={{ value: "DateValue | null", defaultValue: "DateValue | null", onChange: "(value: DateValue | null) => void", minValue: "DateValue", maxValue: "DateValue", placeholderValue: "DateValue", isDateUnavailable: "(date: DateValue) => boolean", granularity: '"day" | "hour" | "minute" | "second"', hourCycle: "12 | 24", firstDayOfWeek: '"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"', onOpenChange: "(isOpen: boolean) => void", weekdayStyle: '"narrow" | "short" | "long"', calendarFooter: "ReactNode" }}
	describe={{
		className: "Class name for the root element.",
		style: "Inline style for the root element.",
		open: "Opens or closes the calendar popup, controlled. Pair it with `onOpenChange`.",
		disabled: "Disables the segments and the calendar button.",
		readOnly: "Shows the date and keeps it focusable, but it can't be changed.",
		invalid: "Marks the picker invalid. Inside a `Field`, the field's `invalid` is used when this is not set.",
		required: "Marks the picker as required for assistive tech.",
		locale: "The locale for the segment order, month names and first day of the week, like `\"en-US\"`. Defaults to the browser's.",
		weekdayStyle: "How the weekday names in the calendar are written. Defaults to `\"short\"`.",
		triggerLabel: "Accessible name of the calendar button. React Aria provides a translated default.",
		previousLabel: "Accessible name of the previous month button. React Aria provides a translated default.",
		nextLabel: "Accessible name of the next month button. React Aria provides a translated default.",
		calendarFooter: "Content shown under the calendar grid, like a legend or a note.",
	}}
>
	Other React Aria props pass through, such as `defaultOpen`, `shouldCloseOnSelect`, `hideTimeZone`, `shouldForceLeadingZeros`, `pageBehavior` and `autoFocus`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the picker itself. The calendar in the popup reads the `Calendar` tokens.

<StylingHooks
	slots={["date-picker", "date-picker-control", "date-input", "date-segment", "date-picker-trigger", "date-picker-popup", "date-picker-dialog"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"date-picker" · "date-picker-control" · "date-input" · "date-segment" · "date-picker-trigger" · "date-picker-popup"' },
		{ attr: "data-open", value: "on the root while the calendar is open" },
		{ attr: "data-invalid", value: "on the root, the control and the segments when invalid" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-focus-within", value: "on the root and the control while a segment has focus" },
		{ attr: "data-placeholder · data-type", value: "on a segment: still empty · its part (month, day, year, literal…)" },
	]}
>

```css
/* a softer segment highlight, only in the booking form */
.booking [data-slot="date-segment"] {
  --cml-segment-focus-bg: var(--cml-item-highlight);
  --cml-segment-focus-fg: var(--cml-fg);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves between the segments, then to the calendar button." },
		{ key: "Arrow Up / Arrow Down", description: "Increases or decreases the focused segment." },
		{ key: "Arrow Left / Arrow Right", description: "Moves to the previous or next segment." },
		{ key: "0–9", description: "Types into the segment and moves on when it is complete." },
		{ key: "Backspace", description: "Clears the focused segment." },
		{ key: "Alt + Arrow Down", description: "Opens the calendar from a segment." },
		{ key: "Arrow keys (calendar)", description: "Move between days. Page Up / Page Down change the month." },
		{ key: "Enter", description: "Selects the focused day and closes the calendar." },
		{ key: "Escape", description: "Closes the calendar and returns focus to the button." },
	]}
	notes={[
		"Each segment is a spinbutton named by the field's label, so screen readers announce the part and the full date.",
		"The popup is a dialog. Focus moves into the calendar when it opens and back to the button when it closes.",
		"Unavailable and out-of-range days are announced as unavailable, not only crossed out.",
		"FieldDescription and FieldError are linked with aria-describedby, and an invalid picker sets aria-invalid.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Date range picker", description: "A start and an end date in one field.", href: "/docs/components/date-range-picker" },
		{ title: "Date field", description: "A typed date, without a calendar.", href: "/docs/components/date-field" },
		{ title: "Calendar", description: "The month grid on its own.", href: "/docs/components/calendar" },
	]}
/>


# Date range picker (/docs/components/date-range-picker)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Date Picker Dialog" />

<Playground
	name="date-range-picker/playground"
	component="DateRangePicker"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The value is a `{ start, end }` object of `@internationalized/date` dates, re-exported from the library. Put the picker in a `Field` to give it a label.

<Import names="DateRangePicker, CalendarDate, isWeekend, Field, FieldLabel" />

## Anatomy [#anatomy]

Two date inputs joined by a separator, and a button that opens a `RangeCalendar` in a popup. The popup renders in a portal and keeps the skin.

<Anatomy
	keys={[
		{ label: '[data-slot="date-range-picker"] · [data-slot="date-picker-control"]', color: "#8be36f" },
		{ label: '[data-slot="date-range-separator"] · [data-slot="date-picker-trigger"] · [data-slot="date-picker-popup"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-input"] · [data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">12/21/2026</span>
	<span className="a-part">–</span>
	<span className="a-label">12/31/2026</span>
	<span className="a-part">trigger</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="date-range-picker/basic" compact />

<ExampleGrid>
	<Example name="date-range-picker/controlled" title="Controlled, with the length">
		Change the dates. Counting the nights under the field saves people from doing it in their head.
	</Example>
	<Example name="date-range-picker/max-length" title="Longest range">
		There is no prop for a maximum length, so check it in `onChange` and set `invalid` on the `Field`. The error says how to fix it.
	</Example>
	<Example name="date-range-picker/unavailable" title="Booked dates">
		`isDateUnavailable` crosses out the booked days, and a range can't run across them. Say which dates are taken in the description too.
	</Example>
	<Example name="date-range-picker/business-days" title="Across weekends">
		With `allowsNonContiguousRanges`, the range can span unavailable days, like weekends in a sprint, without counting them.
	</Example>
	<Example name="date-range-picker/separator" title="Custom separator">
		`separator` replaces the dash, here with a word. It is hidden from screen readers, which name the two inputs start and end date.
	</Example>
	<Example name="date-range-picker/read-only" title="Read-only">
		`readOnly` shows a closed period that can still be focused and read. Say where to go if it is wrong.
	</Example>
	<Example name="date-range-picker/required" title="Required in a form">
		Send it empty. `startName` and `endName` submit two ISO dates, and the error goes away once both are picked.
	</Example>
</ExampleGrid>

## In context [#in-context]

Ranges filter, book and plan. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="date-range-picker/context-report" title="Report filter with presets" uses="Card · Field · DateRangePicker · Button" />
	<Context name="date-range-picker/context-hotel" title="Hotel booking" uses="Card · Field · DateRangePicker · NumberField · Button" />
	<Context name="date-range-picker/context-time-off" title="Time-off request" uses="Card · NativeSelect · Field · DateRangePicker · Textarea · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="date-range-picker/do-one-range" title="One field for one range.">
		The calendar shows the whole span, and the end can't land before the start.
	</Guideline>
	<Guideline kind="dont" name="date-range-picker/dont-two-pickers" title="Two separate pickers for one stay.">
		Neither calendar shows the span, and people pick the second date without seeing the first.
	</Guideline>
	<Guideline kind="do" name="date-range-picker/do-show-length" title="Say how long it is.">
		"10 business days, back on Monday" confirms the range in words.
	</Guideline>
	<Guideline kind="dont" name="date-range-picker/dont-hide-length" title="Leave people counting.">
		Two dates alone make people count days, and weekends are easy to miss.
	</Guideline>
</Guidelines>

## Props [#props]

`DateRangePicker` takes the props of the React Aria date range picker. These are the ones you use most:

<Props
	file="date"
	type="DateRangePickerProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "allowsNonContiguousRanges", "placeholderValue", "granularity", "firstDayOfWeek", "onOpenChange", "startName", "endName"]}
	types={{ value: "DateRange | null", defaultValue: "DateRange | null", onChange: "(value: DateRange | null) => void", minValue: "DateValue", maxValue: "DateValue", placeholderValue: "DateValue", isDateUnavailable: "(date: DateValue) => boolean", granularity: '"day" | "hour" | "minute" | "second"', firstDayOfWeek: '"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"', onOpenChange: "(isOpen: boolean) => void", weekdayStyle: '"narrow" | "short" | "long"', separator: "ReactNode", calendarFooter: "ReactNode" }}
	describe={{
		className: "Class name for the root element.",
		style: "Inline style for the root element.",
		open: "Opens or closes the calendar popup, controlled. Pair it with `onOpenChange`.",
		disabled: "Disables both inputs and the calendar button.",
		readOnly: "Shows the range and keeps it focusable, but it can't be changed.",
		invalid: "Marks the picker invalid. Inside a `Field`, the field's `invalid` is used when this is not set.",
		required: "Marks both dates as required for assistive tech.",
		locale: "The locale for the segment order, month names and first day of the week, like `\"en-US\"`. Defaults to the browser's.",
		weekdayStyle: "How the weekday names in the calendar are written. Defaults to `\"short\"`.",
		separator: "What goes between the start and the end date. Hidden from screen readers. Defaults to `\"–\"`.",
		triggerLabel: "Accessible name of the calendar button. React Aria provides a translated default.",
		previousLabel: "Accessible name of the previous month button. React Aria provides a translated default.",
		nextLabel: "Accessible name of the next month button. React Aria provides a translated default.",
		calendarFooter: "Content shown under the calendar grid, like a legend or a note.",
	}}
>
	Other React Aria props pass through, such as `defaultOpen`, `shouldCloseOnSelect`, `hourCycle`, `hideTimeZone`, `pageBehavior` and `autoFocus`. Unlike `DatePicker`, it doesn't take `name` from the `Field`: use `startName` and `endName`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the picker itself. The calendar in the popup reads the `RangeCalendar` tokens.

<StylingHooks
	slots={["date-range-picker", "date-picker-control", "date-input", "date-segment", "date-range-separator", "date-picker-trigger", "date-picker-popup", "date-picker-dialog"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"date-range-picker" · "date-picker-control" · "date-input" · "date-range-separator" · "date-picker-trigger" · "date-picker-popup"' },
		{ attr: "data-open", value: "on the root while the calendar is open" },
		{ attr: "data-invalid", value: "on the root, the control and the segments when invalid" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-focus-within", value: "on the root and the control while a segment has focus" },
		{ attr: "data-placeholder · data-type", value: "on a segment: still empty · its part (month, day, year, literal…)" },
	]}
>

```css
/* a wider gap around the separator, only in the report toolbar */
.report-filters [data-slot="date-range-separator"] {
  padding-inline: 0.5rem;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves through the start segments, the end segments, then the calendar button." },
		{ key: "Arrow Up / Arrow Down", description: "Increases or decreases the focused segment." },
		{ key: "Arrow Left / Arrow Right", description: "Moves to the previous or next segment, across both dates." },
		{ key: "0–9", description: "Types into the segment and moves on when it is complete." },
		{ key: "Alt + Arrow Down", description: "Opens the calendar from a segment." },
		{ key: "Enter (calendar)", description: "Starts the range on the focused day; a second Enter ends it and closes the calendar." },
		{ key: "Arrow keys (calendar)", description: "Move between days and extend the range while one is started." },
		{ key: "Escape", description: "Closes the calendar and returns focus to the button." },
	]}
	notes={[
		"The two inputs are a group named by the field's label, and each is announced as the start or end date.",
		"The popup is a dialog. Focus moves into the calendar when it opens and back to the button when it closes.",
		"The separator is aria-hidden, so a word like \"to\" is not read between the dates.",
		"FieldDescription and FieldError are linked with aria-describedby, and an invalid picker sets aria-invalid.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Date picker", description: "One date, typed or picked.", href: "/docs/components/date-picker" },
		{ title: "Range calendar", description: "The range grid on its own, always visible.", href: "/docs/components/range-calendar" },
		{ title: "Date field", description: "A typed date, without a calendar.", href: "/docs/components/date-field" },
	]}
/>


# Dialog (/docs/components/dialog)

<ComponentMeta file="dialog" primitive="Base UI" pattern="WAI-ARIA Dialog (Modal)" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose, DialogActions" />

## Anatomy [#anatomy]

A `dialog-trigger` button opens a `dialog-backdrop` and this popup. Both render in a portal that keeps the skin, mode and brand of the page around the trigger.

<Anatomy
	tree={{
		slot: "dialog-popup",
		tag: "div",
		note: "role=dialog",
		children: [
			{ slot: "dialog-title", tag: "h2" },
			{ slot: "dialog-description", tag: "p" },
			{ slot: "children", note: "fields, tables, text" },
			{
				slot: "dialog-actions",
				tag: "div",
				row: true,
				children: [
					{ slot: "dialog-close", tag: "button" },
					{ slot: "button", tag: "button", note: "main action" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. Open them: the dialog wears the skin, mode and brand from the bar above.

<Preview name="dialog/basic" compact />

<ExampleGrid>
	<Example name="dialog/form-submit" title="A form that closes on submit">
		Click it. Focus starts in the field; submitting saves, closes the dialog, returns focus to the trigger and a status message says what changed.
	</Example>
	<Example name="dialog/controlled" title="Opened by something else">
		When the state lives elsewhere (a menu item, a shortcut), pass `open` and `onOpenChange`. Focus still goes back to whatever opened it.
	</Example>
	<Example name="dialog/scrolling" title="Long content">
		Scroll only the body, so the title and the buttons stay in view. Wrap it in a `ScrollArea`: its viewport takes focus, so the keyboard can scroll it.
	</Example>
	<Example name="dialog/outside-click" title="Doesn't close on outside click">
		When people type a lot, a stray click shouldn't throw it away. `disablePointerDismissal` keeps Esc and the buttons working.
	</Example>
	<Example name="dialog/close-button" title="A close button in the corner">
		Every dialog needs a visible way out: touch screen readers have no Esc. Put the icon button last in the code so focus starts on the content.
	</Example>
	<Example name="dialog/wide" title="Wider for a table" wide>
		There is one default width. Set `inline-size` on `DialogContent` when a table needs room; on a phone it still fits the screen.
	</Example>
</ExampleGrid>

## In context [#in-context]

Dialogs hold a task that belongs to something on the page. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="dialog/context-edit-profile" title="Edit profile" uses="Card · Avatar · Dialog · Field" />
	<Context name="dialog/context-invite" title="Invite teammates" uses="Card · Avatar · Badge · Dialog · NativeSelect" />
	<Context name="dialog/context-export" title="Export a report" uses="Card · Dialog · RadioGroup · Switch" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="dialog/do-one-task" title="One task, a few fields.">
		People finish it and get back to what they were doing.
	</Guideline>
	<Guideline kind="dont" name="dialog/dont-whole-page" title="A whole settings page in a dialog.">
		It scrolls, hides the page it belongs to and can't be linked. Use a page.
	</Guideline>
	<Guideline kind="do" name="dialog/do-task-title" title="A title that names the task.">
		"Invite teammates" and "Send invites" say what happens, also to a screen reader that reads only the title.
	</Guideline>
	<Guideline kind="dont" name="dialog/dont-generic-title" title="&quot;Information&quot; and &quot;OK&quot;.">
		The title is the dialog's accessible name. A generic one tells nobody where they are.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="dialog" type="DialogProps" include={["open", "defaultOpen", "onOpenChange", "modal", "disablePointerDismissal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ open: "Whether the dialog is open. Use it with `onOpenChange` to control the state.", defaultOpen: "Whether the dialog starts open, without controlling the state.", onOpenChange: "Called when the dialog opens or closes. `eventDetails.reason` says why, for example `escape-key` or `outside-press`.", modal: "`true` traps focus, locks scrolling and blocks outside clicks. `trap-focus` only traps focus. `false` leaves the page free.", disablePointerDismissal: "Stops an outside click from closing the dialog. Esc and the buttons still work." }}
>
	`DialogTrigger`, `DialogTitle`, `DialogDescription` and `DialogClose` take the props of their element, plus `render`.
</Props>

`DialogContent` decides where focus goes:

<Props file="dialog" type="DialogContentProps" include={["initialFocus", "finalFocus"]}
	types={{ initialFocus: "boolean | RefObject | (openType) => HTMLElement | boolean", finalFocus: "boolean | RefObject | (closeType) => HTMLElement | boolean" }}
	describe={{ initialFocus: "The element that gets focus on open. By default, the first focusable element inside the dialog.", finalFocus: "The element that gets focus on close. By default, the trigger or the element that had focus before." }}
/>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the popup itself.

<StylingHooks
	slots={["dialog-trigger", "dialog-backdrop", "dialog-popup", "dialog-title", "dialog-description", "dialog-actions", "dialog-close"]}
	prefix="dialog"
	attributes={[
		{ attr: "data-open", value: "present while open" },
		{ attr: "data-closed", value: "present while closed" },
		{ attr: "data-starting-style", value: "present while opening" },
		{ attr: "data-ending-style", value: "present while closing" },
		{ attr: "data-nested", value: "present on a dialog opened from another" },
	]}
>

```css
/* a dialog that fills the screen on phones */
@media (max-width: 40rem) {
  .checkout [data-slot="dialog-popup"] {
    inline-size: 100vw;
    max-block-size: 100dvh;
    border-radius: 0;
  }
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter / Space", description: "On the trigger, opens the dialog. Focus moves to the first field or button inside." },
		{ key: "Tab", description: "Moves to the next focusable element. Focus stays inside the dialog: after the last one it wraps to the first." },
		{ key: "Shift + Tab", description: "Moves to the previous focusable element, wrapping to the last." },
		{ key: "Escape", description: "Closes the dialog. Focus goes back to the element that opened it." },
	]}
	notes={[
		"The popup has role=\"dialog\". DialogTitle names it and DialogDescription describes it, through aria-labelledby and aria-describedby: always include a title.",
		"While it is open, the rest of the page is hidden from screen readers (aria-hidden), focus can't leave and the page doesn't scroll.",
		"A click outside closes it, unless you pass disablePointerDismissal. Esc and the close buttons always work.",
		"When the element that opened it is gone after closing, point finalFocus at something sensible, and announce the result with role=\"status\".",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "AlertDialog", description: "Asks to confirm a decision that can't be undone.", href: "/docs/components/alert-dialog" },
		{ title: "Popover", description: "A small panel next to its trigger, without blocking the page.", href: "/docs/components/popover" },
		{ title: "Field", description: "Label, description and error for the inputs inside.", href: "/docs/components/field" },
	]}
/>


# DirectionProvider (/docs/components/direction-provider)

<ComponentMeta file="scroll-area" primitive="Base UI" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It is Base UI's `DirectionProvider`, re-exported.

<Import names="DirectionProvider" />

You need two things, and they do different jobs:

- **`dir="rtl"` on an element** (usually `<html>`, with `lang`) flips the layout: text alignment, flex and grid order, and every logical property in the skins.
- **`<DirectionProvider direction="rtl">`** tells the components' JavaScript: which arrow key moves forward, which end a slider starts from, and which side a popup aligns to. The browser can't tell them.

## Anatomy [#anatomy]

It renders no element: it only puts the direction in React context. The `dir` attribute is yours to set.

<Anatomy
	tree={{
		slot: "html",
		tag: "html dir=rtl lang=ar",
		note: "layout and screen readers",
		children: [
			{
				slot: "DirectionProvider",
				note: "no element, React context",
				children: [{ slot: "slider · tabs · toolbar · radio-group · menu · select…", note: "read the direction" }],
			},
		],
	}}
/>

## Examples [#examples]

The Arabic and Hebrew texts are short sample strings (Save, Cancel, Settings…). Have a native speaker review your real copy.

<Preview name="direction-provider/basic" compact />

<ExampleGrid>
	<Example name="direction-provider/slider-keys" title="Sliders start on the right">
		Focus each slider and press the arrows. In RTL the fill grows from the right, Arrow Left raises the value and Arrow Right lowers it, so the key matches the movement.
	</Example>
	<Example name="direction-provider/tabs-keys" title="Tabs flip their arrow keys">
		The first tab sits on the right. Arrow Left moves to the next tab; Home and End still go to the first and the last.
	</Example>
	<Example name="direction-provider/menu-rtl" title="Menus in a right-to-left section">
		Open it. Up and Down don't change. The popup renders in `<body>`, so pass it `dir`; it lines up with the trigger's right edge once `<html>` has `dir="rtl"`.
	</Example>
	<Example name="direction-provider/language-switch" title="Switch direction at runtime">
		Flip the switch. Change the provider, `dir` and `lang` together, and mirror icons that mean "forward" or "back".
	</Example>
	<Example name="direction-provider/logical-css" title="Logical properties in your CSS">
		Write `padding-inline-start` and `border-inline-start`, not left and right. The same note then works in both directions without a second stylesheet.
	</Example>
	<Example name="direction-provider/mixed-direction" title="Left-to-right content inside">
		Emails, phone numbers and codes read left to right. Give their inputs `dir="ltr"`, and wrap embedded values in `<bdi>` so they don't reorder the sentence.
	</Example>
</ExampleGrid>

## In context [#in-context]

Whole pieces of UI in right-to-left languages, in the skin you picked.

<ContextGrid>
	<Context name="direction-provider/context-settings" title="Account settings (Arabic)" uses="DirectionProvider · Card · Field · Select · Switch" />
	<Context name="direction-provider/context-order" title="Order summary (Hebrew)" uses="DirectionProvider · Card · DataList · Badge · Button" />
	<Context name="direction-provider/context-filters" title="Price filter (Arabic)" uses="DirectionProvider · Card · Slider · Switch · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="direction-provider/do-both" title="Set dir and the provider.">
		The label, the fill and the arrow keys all agree.
	</Guideline>
	<Guideline kind="dont" name="direction-provider/dont-dir-only" title="Only dir.">
		It fills from the right, yet Arrow Right raises the value and a click lands on the mirrored spot.
	</Guideline>
	<Guideline kind="do" name="direction-provider/do-logical" title="Logical margins and padding.">
		`margin-inline-start` keeps the gap between the word and the badge in any direction.
	</Guideline>
	<Guideline kind="dont" name="direction-provider/dont-physical" title="margin-left in a right-to-left page.">
		The space lands on the far side and the badge touches the word.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="scroll-area"
	type="DirectionProviderProps"
	include={["direction", "children"]}
	types={{ direction: '"ltr" | "rtl"' }}
	describe={{
		direction: "The reading direction the components inside follow.",
		children: "The components that should follow the direction.",
	}}
>
	It renders no element, so it takes no other props. Set `dir` and `lang` on an element yourself.
</Props>

## Styling hooks [#styling-hooks]

There is nothing to style on the provider itself. The skins use logical properties throughout, so they follow `dir`; target it when you need a rule for one direction only.

<StylingHooks
	slots={[]}
	attributes={[
		{ attr: "dir", value: "rtl · ltr, on your element (inherited)" },
		{ attr: ":dir(rtl)", value: "CSS pseudo-class that matches the inherited direction" },
		{ attr: "data-orientation", value: "horizontal · vertical, on sliders, tabs and toolbars" },
	]}
>

```css
/* mirror directional icons in right-to-left pages */
:dir(rtl) .icon-forward {
  scale: -1 1;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Arrow Left", description: "In RTL: next tab or toolbar item; raises a slider's value." },
		{ key: "Arrow Right", description: "In RTL: previous tab or toolbar item; lowers a slider's value." },
		{ key: "Arrow Up / Arrow Down", description: "Unchanged: menus, selects and vertical lists don't flip." },
		{ key: "Home / End", description: "Unchanged: first and last item, or a slider's minimum and maximum." },
	]}
	notes={[
		"The provider has no element and takes no focus. Screen readers learn the direction and language from dir and lang on your elements.",
		"Set lang next to dir, so screen readers read Arabic or Hebrew with the right voice.",
		"Popups render in <body>. Set dir on <html> for a fully RTL page, or pass dir to the popup inside a right-to-left section.",
		"Mirror icons that point forward or back. Leave alone the ones that don't, like play, check or a clock.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "StyleProvider", description: "Skin, mode and brand color for a section.", href: "/docs/components/style-provider" },
		{ title: "Slider", description: "Fills from the right in RTL.", href: "/docs/components/slider" },
		{ title: "Tabs", description: "Arrow keys follow the reading direction.", href: "/docs/components/tabs" },
	]}
/>


# Drawer (/docs/components/drawer)

<ComponentMeta file="drawer" primitive="Base UI" pattern="WAI-ARIA Dialog (Modal)" />

<Playground
	name="drawer/playground"
	component="Drawer"
	controls={[{ prop: "side", options: ["right", "left", "bottom"], default: "right" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter, DrawerClose" />

## Anatomy [#anatomy]

`DrawerContent` renders the backdrop and the sheet in a portal, with the skin, mode and brand of the page around the trigger. Only the body scrolls, so the header and the footer always stay in view.

<Anatomy
	tree={{
		slot: "drawer-viewport",
		tag: "div",
		note: "in a portal, after drawer-backdrop",
		children: [
			{
				slot: "drawer-popup",
				tag: "div",
				note: "role=dialog",
				children: [
					{ slot: "drawer-header", tag: "div", row: true, children: [{ slot: "drawer-title", tag: "h2" }, { slot: "drawer-close", tag: "button", note: "×" }] },
					{ slot: "drawer-body", tag: "div", note: "scrolls", children: [{ slot: "drawer-description", tag: "p", note: "optional" }] },
					{ slot: "drawer-footer", tag: "div", note: "actions, stays in view" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Each one starts closed: open it, then try Tab, Escape and a click on the backdrop.

<Preview name="drawer/basic" compact />

<ExampleGrid>
	<Example name="drawer/sides" title="Sides" wide>
		Right for details and filters, next to the content they change. Left for navigation, where the menu lives. Bottom on phones, where the thumb reaches.
	</Example>
	<Example name="drawer/mobile-nav" title="Navigation on a phone">
		Click a link. The menu closes, focus returns to the menu button and a status message says which page is now showing.
	</Example>
	<Example name="drawer/filters" title="Filters with Apply and Reset">
		Change some filters. The main button counts the results as you go; nothing changes on the page until you press it, and closing without it discards the changes.
	</Example>
	<Example name="drawer/long-content" title="Long content, actions in view">
		Only the body scrolls, so Accept and Decline stay in the footer while people read. A body with only text becomes a tab stop while it scrolls, so keyboard users can scroll it too.
	</Example>
	<Example name="drawer/a11y-named" title="Named by its title">
		`DrawerTitle` is the dialog's name and `DrawerDescription` is read after it. The × has no text, so pass `aria-label` in the page's language.
	</Example>
	<Example name="drawer/bottom-sheet" title="Bottom sheet">
		A short list of choices for phones. Each one closes the sheet and reports what happened in a status message.
	</Example>
	<Example name="drawer/from-code" title="Opened from code">
		Without a `DrawerTrigger`, control it with `open` and `onOpenChange`. Focus still goes back to the button that opened it.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="drawer/context-cart" title="Shopping cart" uses="Drawer · Card · SearchInput · IconButton · Separator" />
	<Context name="drawer/context-notifications" title="Notification center" uses="Drawer · IconButton · Badge · Avatar · Button" />
	<Context name="drawer/context-task" title="Task details" uses="Card · Drawer · Field · Textarea · Checkbox" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="drawer/do-side-task" title="A task that needs the page in view.">
		Editing an address next to the order it belongs to keeps people oriented.
	</Guideline>
	<Guideline kind="dont" name="drawer/dont-confirm" title="A drawer for a yes or no.">
		A whole sheet for one sentence and two buttons is too much. Use an alert dialog, which also puts focus on the safe choice.
	</Guideline>
	<Guideline kind="do" name="drawer/do-sticky-footer" title="Actions in the footer.">
		`DrawerFooter` stays in view while the list scrolls, so the next step is always there.
	</Guideline>
	<Guideline kind="dont" name="drawer/dont-actions-in-body" title="Actions at the end of a long body.">
		People have to scroll past 24 options to find out how to confirm.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="drawer"
	type="DrawerProps"
	include={["open", "defaultOpen", "onOpenChange", "modal", "disablePointerDismissal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
>
	`DrawerContent` takes the popup's props, including `initialFocus` and `finalFocus` to choose where focus goes when it opens and closes. `DrawerClose` without children renders the × button; pass `aria-label` in the page's language (default "Close").
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the sheet itself.

<StylingHooks
	slots={["drawer-trigger", "drawer-backdrop", "drawer-viewport", "drawer-popup", "drawer-header", "drawer-title", "drawer-description", "drawer-body", "drawer-footer", "drawer-close"]}
	attributes={[
		{ attr: "data-swipe-direction", value: "right · left · down" },
		{ attr: "data-open · data-closed", value: "on the popup and the backdrop" },
		{ attr: "data-starting-style · data-ending-style", value: "while it slides in and out" },
		{ attr: "data-swiping", value: "present while it is dragged" },
	]}
>

```css
/* a wider sheet for the order editor */
.orders [data-slot="drawer-popup"][data-swipe-direction="right"] {
  inline-size: min(36rem, calc(100vw - 3rem));
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "On the trigger, opens the drawer and moves focus to the sheet." },
		{ key: "Tab", description: "Moves to the next control in the drawer. From the last one it goes back to the first; the page behind can't be reached." },
		{ key: "Shift + Tab", description: "Moves to the previous control, also wrapping inside the drawer." },
		{ key: "Page Down / Page Up", description: "Scroll a long body once it has focus. A body that scrolls and holds no controls is a tab stop of its own." },
		{ key: "Escape", description: "Closes the drawer and returns focus to the element that opened it." },
	]}
	notes={[
		"The sheet is a modal dialog: the page behind is hidden from screen readers, and a click on the backdrop closes the drawer.",
		"DrawerTitle gives the dialog its name. Every drawer needs one, even if it repeats the trigger's label.",
		"When it closes, focus goes back to the trigger, or to the button that opened it from code. Report results in a status message, because the drawer that showed them is gone.",
		"Swiping toward its edge closes it on touch screens. Every swipe has a button alternative: the ×, a footer action or Escape.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Dialog", description: "A centered window for a short decision or form.", href: "/docs/components/alert-dialog" },
		{ title: "Popover", description: "A small panel next to its trigger that doesn't block the page.", href: "/docs/components/popover" },
		{ title: "Field", description: "Labels, hints and errors for the forms inside a drawer.", href: "/docs/components/field" },
	]}
/>


# Empty state (/docs/components/empty-state)

<ComponentMeta file="data-display" pattern="Heading + text + actions" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="EmptyState, EmptyStateIcon, EmptyStateTitle, EmptyStateDescription, EmptyStateActions" />

## Anatomy [#anatomy]

A centered column with up to four parts. Pass `icon`, `title`, `description` and `actions`, or build it from the parts as children. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "empty-state",
		tag: "div",
		children: [
			{ slot: "empty-state-icon", tag: "span", note: "aria-hidden" },
			{ slot: "empty-state-title", tag: "h3", note: "level set by as" },
			{ slot: "empty-state-description", tag: "p" },
			{ slot: "empty-state-actions", tag: "div", note: "buttons or links" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="empty-state/basic" compact />

<ExampleGrid>
	<Example name="empty-state/no-results" title="No search results">
		Type a product name, then clear the search. Repeat the query in the title so people see what to change, and announce the count in a `role="status"`, since the empty state itself is not read out when it appears.
	</Example>
	<Example name="empty-state/error-state" title="Loading failed">
		When data fails to load, say what failed and that nothing was lost, then offer a retry. A way to reach support is a link, because it goes somewhere.
	</Example>
	<Example name="empty-state/minimal" title="Nothing left to do">
		When empty is the good outcome, a short confirmation is enough: pass `icon={null}` to drop the default folder icon, and leave out actions.
	</Example>
	<Example name="empty-state/in-card" title="Inside a card">
		Keep the card's own title, so people know which section is empty, and say when it will fill up.
	</Example>
	<Example name="empty-state/with-parts" title="Built from parts">
		Compose the parts as children when you need more than a title and a sentence, like the rules for an import. With children, no default icon is drawn.
	</Example>
	<Example name="empty-state/interactive-action" title="First item">
		Create a project, then delete them all. The button you clicked disappears with the view, so focus moves to the button that replaces it and a status message says what happened.
	</Example>
</ExampleGrid>

## In context [#in-context]

An empty state usually sits where the content will be: in a card, under a search, in place of a list. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="empty-state/context-inbox" title="Support inbox at zero" uses="Card · Badge · EmptyState · Link" wide />
	<Context name="empty-state/context-search" title="Catalog search" uses="Card · SearchInput · EmptyState · Button" wide />
	<Context name="empty-state/context-team" title="Team with only you" uses="Card · EmptyState · Button" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="empty-state/do-actionable-cta" title="Give the next step.">
		Say why the space is empty and put the action that fills it right there.
	</Guideline>
	<Guideline kind="dont" name="empty-state/dont-dead-end" title='Just "Empty".'>
		People can't tell if something broke or what to do, so they leave.
	</Guideline>
	<Guideline kind="do" name="empty-state/do-calm-tone" title="Keep a new account calm.">
		Nothing is wrong yet, so use a neutral icon and say how quick the first step is.
	</Guideline>
	<Guideline kind="dont" name="empty-state/dont-alarming-style" title="Error colors for a normal empty state.">
		Red icons and the word "Error" make people think data was lost.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="EmptyStateProps"
	include={["children"]}
	describe={{ children: "Your own content, placed after the description. Use it to compose the parts." }}
>
	`EmptyStateIcon`, `EmptyStateTitle`, `EmptyStateDescription` and `EmptyStateActions` take the attributes of their HTML element (`span`, `h3`, `p`, `div`). `EmptyStateTitle` also takes `as` (`h2` to `h6`, or `p`; default `h3`) to set the heading level. `EmptyState` takes the attributes of a `div`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slots, or set the tokens on a parent, a skin or the empty state itself.

<StylingHooks
	slots={["empty-state", "empty-state-icon", "empty-state-title", "empty-state-description", "empty-state-actions"]}
	prefix="empty-state"
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "Moves to the buttons and links in the actions. The empty state itself is not a Tab stop." }]}
	notes={[
		"The title prop renders an <h3>. Inside a card whose title is also an <h3>, pass <EmptyStateTitle as=\"h4\"> as a child instead, so the headings nest.",
		"The icon is wrapped in aria-hidden, so screen readers read only the title and the description.",
		"The empty state is not a live region. When it replaces results after a search or a delete, announce the change with a role=\"status\" next to it.",
		"When the action that emptied the list removes the focused button, move focus to the next control yourself, such as the search field or the empty state's main action.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Table", description: "A table with no rows keeps its headers and one row that explains why.", href: "/docs/components/table" },
		{ title: "Skeleton", description: "Shows while data loads, before you know whether it is empty.", href: "/docs/components/skeleton" },
		{ title: "Alert", description: "For an error that doesn't replace the content, like a failed save.", href: "/docs/components/alert" },
	]}
/>


# Error summary (/docs/components/error-summary)

<ComponentMeta file="error-summary" pattern="Alert + in-page links" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It goes with the `Field` parts.

<Import names="ErrorSummary" />

## Anatomy [#anatomy]

A danger `Alert` with a title and a list of links. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="alert"][data-kind="error-summary"]', color: "#8be36f" },
		{ label: '[data-slot="alert-icon"] · [data-slot="alert-title"] · [data-slot="error-summary-list"]', color: "#ffcf7a" },
		{ label: '[data-slot="error-summary-link"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">icon</span>
	<span className="a-part">title</span>
	<span className="a-label">Email</span>
	<span className="a-label">Phone</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="error-summary/basic" compact />

<ExampleGrid>
	<Example name="error-summary/focus-on-submit" title="Focus on submit">
		Press Continue with empty fields. The summary takes focus through `ref` and `tabIndex={-1}`, so it is read first, and it shrinks as you fix each field.
	</Example>
	<Example name="error-summary/server-errors" title="Errors from the server">
		Press Save. When your API rejects a value, show the same summary: people get one place to look whether the error came from the browser or the backend.
	</Example>
	<Example name="error-summary/any-control" title="Selects and checkboxes">
		`target` is the id of any focusable control. A checkbox's id lands on its hidden input, which hands focus to the visible box.
	</Example>
	<Example name="error-summary/long-form" title="In a long form">
		Click a link. The control scrolls to the middle of the screen, so a sticky header never hides the field you jumped to.
	</Example>
	<Example name="error-summary/plural" title="One or many">
		Count the errors in the title and pick the wording with `Intl.PluralRules`, so "1 field" and "3 fields" both read right in every language.
	</Example>
	<Example name="error-summary/with-label" title="With a written label">
		`label` adds a word like "Error". Some skins show it in place of the icon, and it gives the alert a text cue besides color.
	</Example>
</ExampleGrid>

## In context [#in-context]

Error summaries sit at the top of real forms. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="error-summary/context-react-hook-form" title="Signup with react-hook-form + zod" uses="Card · ErrorSummary · Field · Input · PasswordInput · Checkbox" />
	<Context name="error-summary/context-checkout" title="Card payment" uses="Card · ErrorSummary · Field · Input · Button" />
	<Context name="error-summary/context-profile" title="Profile not saved" uses="Card · ErrorSummary · Field · Input · Textarea" />
</ContextGrid>

## With react-hook-form and zod [#with-react-hook-form-and-zod]

Camaleo has no dependency on a form library. The signup form above wires react-hook-form and zod to `Field` and `ErrorSummary`; its Code tab has the whole file.

```bash
pnpm add react-hook-form zod @hookform/resolvers
```

- **The schema holds the messages.** `zodResolver(schema)` validates on submit, and each zod message becomes `fieldState.error.message`.
- **`Controller` connects each control.** Pass `fieldState.invalid` to `Field invalid` and the message to `FieldError match={fieldState.invalid}`, so the error is linked to the control and `aria-invalid` is set.
- **Give every control an id.** Use `useId()` and put it on the `Input` (or the `Checkbox`, `NativeSelect` or `Rating`, which pass it to the element that takes focus); the summary links to that same id.
- **Build the summary from `formState.errors`.** Show it when `isSubmitted` and there are errors, map each invalid name to `{ target: id, message: label }`, and focus it when `submitCount` changes. Pass `shouldFocusError: false`, or react-hook-form moves focus to the first field instead.
- **Use `noValidate` on the form.** The browser's own bubbles would show before your messages.

```tsx
const { control, handleSubmit, formState: { errors, isSubmitted, submitCount } } =
	useForm<Values>({ resolver: zodResolver(schema), defaultValues, shouldFocusError: false });
const invalid = (Object.keys(labels) as (keyof Values)[]).filter((name) => errors[name]);

useEffect(() => {
	if (submitCount > 0) summaryRef.current?.focus();
}, [submitCount]);

{isSubmitted && invalid.length > 0 && (
	<ErrorSummary
		ref={summaryRef}
		tabIndex={-1}
		title={`Fix ${invalid.length} fields to continue.`}
		errors={invalid.map((name) => ({ target: ids[name], message: labels[name] }))}
	/>
)}
```

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="error-summary/do-links" title="Link every error to its field.">
		One click or Enter takes people straight to what needs fixing.
	</Guideline>
	<Guideline kind="dont" name="error-summary/dont-no-links" title="An alert that only says something is wrong.">
		People have to hunt through the form for the red fields.
	</Guideline>
	<Guideline kind="do" name="error-summary/do-fix" title="Name the field and the fix.">
		"Card number: enter all 16 digits" works out of context, in a list of links.
	</Guideline>
	<Guideline kind="dont" name="error-summary/dont-generic" title="The same vague message twice.">
		Two links called "Invalid value" can't be told apart by a screen reader user.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="error-summary" type="ErrorSummaryProps"
	types={{ errors: "{ target: string; message: ReactNode }[]" }}
	describe={{ icon: "Replaces the danger icon." }}
>
	The other `div` attributes pass through, including `ref` and `tabIndex`: use them to move focus to the summary after a failed submit.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the summary itself.

<StylingHooks
	slots={["alert", "alert-title", "error-summary-list", "error-summary-link"]}
	prefix="alert"
	attributes={[
		{ attr: "data-slot", value: '"alert" · "alert-title" · "error-summary-list" · "error-summary-link"' },
		{ attr: "data-kind", value: '"error-summary"' },
		{ attr: "data-tone", value: '"danger"' },
	]}
>

```css
/* one error per line, only in the checkout */
.checkout [data-slot="error-summary-list"] {
  flex-direction: column;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves through the links, in the order of the form." },
		{ key: "Enter", description: "Follows a link: focus moves to the control and it scrolls into view." },
		{ key: "Shift + Tab", description: "From the control, back to the summary's links." },
	]}
	notes={[
		"It renders with role=\"alert\", so screen readers announce it as soon as it appears.",
		"Move focus to it after a failed submit (ref + tabIndex={-1}), so keyboard users start from the list instead of the submit button.",
		"Each link focuses the control itself, not just its label, so people can type right away.",
		"Keep the inline FieldError on every field too: the summary is the map, the field says what to change.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Field", description: "Label, description and the error on each field.", href: "/docs/components/field" },
		{ title: "Alert", description: "Static messages in four tones.", href: "/docs/components/alert" },
		{ title: "Checkbox", description: "Terms and consent in a form.", href: "/docs/components/checkbox" },
	]}
/>


# Field (/docs/components/field)

<ComponentMeta file="field" primitive="Base UI" pattern="HTML label + aria-describedby" />

<Playground
	name="field/playground"
	component="Field"
	controls={[
		{ prop: "invalid", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need.

<Import names="Field, FieldLabel, FieldDescription, FieldError" />

<Import names="Input, Textarea, Label, Fieldset, FieldsetLegend" />

## Anatomy [#anatomy]

A `Field` is a grid of up to four parts. The label points at the control, and the description and error are read with it.

<Anatomy
	keys={[
		{ label: '[data-slot="field"]', color: "#8be36f" },
		{ label: '[data-slot="field-label"] · [data-slot="field-description"] · [data-slot="field-error"]', color: "#ffcf7a" },
		{ label: 'control: [data-slot="input"] · [data-slot="textarea"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">label</span>
	<span className="a-label">input</span>
	<span className="a-part">description</span>
	<span className="a-part">error</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="field/basic" compact />

<ExampleGrid>
	<Example name="field/textarea-count" title="Textarea with a counter">
		Type in it. A live count in `FieldDescription` is read with the field, so people hear the limit before they hit it.
	</Example>
	<Example name="field/required" title="Required">
		Type a letter, delete it and leave. `valueMissing` waits until the field was changed or the form submitted, so a fresh form never opens in red.
	</Example>
	<Example name="field/invalid" title="Error from the server">
		When the error comes from your API, set `invalid` and render `FieldError match`. The input gets `aria-invalid` and the message is linked to it.
	</Example>
	<Example name="field/validate" title="Custom validation">
		Type a space or delete letters. `validate` returns the message, and an empty `FieldError` shows it while people type.
	</Example>
	<Example name="field/disabled" title="Disabled">
		`disabled` on the `Field` reaches the label and the control. Say why in the description, or nobody knows who can change it.
	</Example>
	<Example name="field/fieldset" title="Grouped with a fieldset">
		`Fieldset` and `FieldsetLegend` name a group, so "Name" is announced as part of "Emergency contact".
	</Example>
	<Example name="field/label-checkbox" title="Label outside a field">
		For a checkbox or switch, wrap it in `Label`: the whole line becomes clickable and names the control.
	</Example>
	<Example name="field/input-types" title="Input types">
		The right `type` and `autoComplete` bring up the matching phone keyboard and let the browser fill the value in.
	</Example>
</ExampleGrid>

## In context [#in-context]

Fields come in forms. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="field/context-signup" title="Signup form" uses="Card · Field · Input · Checkbox · Button" />
	<Context name="field/context-address" title="Shipping address" uses="Fieldset · Field · Input · NativeSelect" />
	<Context name="field/context-profile" title="Profile settings" uses="Card · Field · Input · Textarea · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="field/do-visible-label" title="A visible label above the input.">
		It stays put while people type, and the placeholder is free to show an example.
	</Guideline>
	<Guideline kind="dont" name="field/dont-placeholder-label" title="The placeholder as the label.">
		It disappears on the first keystroke, and its low contrast is hard to read.
	</Guideline>
	<Guideline kind="do" name="field/do-specific-error" title="Say how to fix it.">
		The error names the rule, so people know what to type.
	</Guideline>
	<Guideline kind="dont" name="field/dont-generic-error" title="A generic error.">
		"Invalid input." tells people something is wrong, not what to change.
	</Guideline>
</Guidelines>

## Props [#props]

`Field` takes the props of the Base UI field root. These are the ones you use most:


<Props
	file="field"
	type="FieldProps"
	include={["invalid", "disabled", "name", "validate", "validationMode", "validationDebounceTime", "dirty", "touched"]}
	types={{"invalid": "boolean", "disabled": "boolean", "name": "string", "validate": "(value, formValues) => string | string[] | null", "validationMode": "\"onSubmit\" | \"onBlur\" | \"onChange\"", "validationDebounceTime": "number", "dirty": "boolean", "touched": "boolean"}}
	describe={{"invalid": "Marks the field invalid, for errors that come from your server or a form library.", "disabled": "Disables the label and the control.", "name": "Identifies the field when the form is submitted. Takes precedence over the control's `name`.", "validate": "Returns the error message(s), or nothing when the value is valid. Can be async.", "validationMode": "When `validate` and the native constraints run.", "validationDebounceTime": "Milliseconds to wait between `validate` calls in `onChange` mode.", "dirty": "Control these states from a form library.", "touched": "Control these states from a form library."}}
/>

`FieldError` takes `match`: `true` to always show it, a `ValidityState` key such as `"valueMissing"` to show it only for that error, or nothing to show it whenever the field is invalid. `Fieldset` takes `disabled`. `Input` and `Textarea` take the attributes of `<input>` and `<textarea>`; `Label` takes those of `<label>`.

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the field itself.

<StylingHooks
	slots={["field", "field-label", "field-description", "field-error", "input", "textarea", "label", "fieldset", "fieldset-legend"]}
	prefix="field"
	attributes={[
		{ attr: "data-slot", value: '"field" · "field-label" · "field-description" · "field-error" · "input" · "textarea"' },
		{ attr: "data-invalid", value: "present on the field and control when invalid" },
		{ attr: "data-valid", value: "present after a passing validation" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-touched · data-dirty", value: "present once focused and left · once changed" },
		{ attr: "data-filled · data-focused", value: "present when it has a value · while focused" },
	]}
>

```css
/* a tighter form, only in this dialog */
.quick-add [data-slot="field"] {
  --cml-field-gap: 0.25rem;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the control. Clicking the label focuses it too." },
		{ key: "Shift + Tab", description: "Moves focus back to the previous control." },
	]}
	notes={[
		"FieldLabel is a real <label> linked to the control, so its text is the control's accessible name.",
		"FieldDescription and a visible FieldError are added to aria-describedby, so screen readers read them after the name.",
		"An invalid field sets aria-invalid on the control. Color is never the only signal: the error message is always text.",
		"FieldsetLegend names the group, and the legend is announced when focus enters it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Native select", description: "The browser's select, styled to match.", href: "/docs/components/native-select" },
		{ title: "Number field", description: "A number input with step buttons.", href: "/docs/components/number-field" },
		{ title: "Input group", description: "Inputs with addons, password and search.", href: "/docs/components/input-group" },
	]}
/>


# File upload (/docs/components/file-upload)

<ComponentMeta file="file-upload" primitive="HTML" pattern="Native file input + role=group" />

<Playground
	name="file-upload/playground"
	component="Dropzone"
	controls={[
		{ prop: "multiple", default: true },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the zone and the list.

<Import names="Dropzone, FileList, FileItem" />

## Anatomy [#anatomy]

The `Dropzone` is a labelled group with a button that opens the file picker. Each `FileItem` in a `FileList` has an icon, the name, a progress bar or meta line, and your actions.

<Anatomy
	keys={[
		{ label: '[data-slot="dropzone"] · [data-slot="file-list"] · [data-slot="file-item"]', color: "#8be36f" },
		{ label: '[data-slot="dropzone-icon"] · [data-slot="dropzone-title"] · [data-slot="dropzone-description"] · button', color: "#ffcf7a" },
		{ label: '[data-slot="file-item-name"] · [data-slot="file-item-meta"] · progress', color: "#7cc7ff" },
	]}
>
	<span className="a-part">icon</span>
	<span className="a-part">title</span>
	<span className="a-part">description</span>
	<span className="a-part">Choose files</span>
	<span className="a-label">q3-report.pdf · 64%</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Nothing leaves your browser: uploads are simulated with timers.

<Preview name="file-upload/basic" compact />

<ExampleGrid>
	<Example name="file-upload/rejections" title="Types and size limit" wide>
		Drop a PDF or a large photo. `accept` and `maxSize` sort the files, `onFilesRejected` says why for each one, and a status line announces the result.
	</Example>
	<Example name="file-upload/progress" title="Progress, cancel and remove" wide>
		Add a file. Keep the upload state yourself and map it to `status`, `progress` and `meta`; the bar takes its name from the file.
	</Example>
	<Example name="file-upload/statuses" title="Every status">
		`status` drives the row: `idle` before sending, `uploading` with a bar, `done` with a check, `error` with the message.
	</Example>
	<Example name="file-upload/retry" title="Retry after an error">
		Click retry. A failed row keeps the file and offers the next step, so people never pick it again from the folder.
	</Example>
	<Example name="file-upload/single" title="One image">
		With `multiple={false}` only the first file is reported, and choosing again replaces it; the row shows its name, type and size.
	</Example>
	<Example name="file-upload/indeterminate" title="Unknown progress">
		When the server can't measure it (a virus scan, a conversion), pass `progress={null}` and say in `meta` what is happening.
	</Example>
	<Example name="file-upload/disabled" title="Disabled, with a reason">
		`disabled` ignores drops and disables the button. Use the description to say why and what to do instead.
	</Example>
</ExampleGrid>

## In context [#in-context]

Uploads are part of a task. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="file-upload/context-ticket" title="Support ticket attachments" uses="Card · Field · Input · Textarea · Dropzone · FileList · IconButton" />
	<Context name="file-upload/context-avatar" title="Profile photo" uses="Card · Avatar · Dropzone · FileItem · Button" />
	<Context name="file-upload/context-import" title="Import contacts from CSV" uses="Card · Dropzone · FileItem · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="file-upload/do-limits" title="Say the types and the limit.">
		People check before they drag, and no file is refused by surprise.
	</Guideline>
	<Guideline kind="dont" name="file-upload/dont-no-limits" title="A bare drop area.">
		The rules exist anyway; people only learn them when a file fails.
	</Guideline>
	<Guideline kind="do" name="file-upload/do-specific-error" title="Say how to fix it.">
		The error names the limit and the way out, right on the file.
	</Guideline>
	<Guideline kind="dont" name="file-upload/dont-generic-error" title="A generic error.">
		"Upload failed." leaves people retrying the same file.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="file-upload" type="DropzoneProps">
	These are the props of `Dropzone`; `children` render between the description and the button. A rejection is `{ file, reason: "type" | "size" }`. `FileList` takes the attributes of `<ul>`; give it an `aria-label`.
</Props>

`FileItem` shows one file:

<Props file="file-upload" type="FileItemProps">
	Other `<li>` attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the zone itself.

<StylingHooks
	slots={["dropzone", "dropzone-icon", "dropzone-title", "dropzone-description", "file-list", "file-item", "file-item-icon", "file-item-name", "file-item-meta", "file-item-error"]}
	prefix="dropzone"
	attributes={[
		{ attr: "data-slot", value: '"dropzone" · "dropzone-icon" · "dropzone-title" · "dropzone-description" · "file-list" · "file-item" · "file-item-icon" · "file-item-body" · "file-item-header" · "file-item-name" · "file-item-meta" · "file-item-error"' },
		{ attr: "data-dragging", value: "on the dropzone while files are dragged over it" },
		{ attr: "data-disabled", value: "on the dropzone when disabled" },
		{ attr: "data-status", value: '"idle" · "uploading" · "done" · "error", on each file item' },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the button inside the zone." },
		{ key: "Enter / Space", description: "Opens the system file picker." },
		{ key: "Tab (in the list)", description: "Moves through each file's actions." },
	]}
	notes={[
		"Dragging is a shortcut, not the only way: the zone always has a real button and a native <input type=\"file\">.",
		"The zone is a group named by its title and described by its description, so the accepted types are read with it.",
		"Each progress bar is named by its file. Name action buttons with the file too: \"Remove cover.png\", not \"Remove\".",
		"Errors are text under the file, not only a red border; announce what was added or refused with a role=\"status\" line.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Progress", description: "A bar for any task with known progress.", href: "/docs/components/progress" },
		{ title: "Field", description: "Label, description and error for any control.", href: "/docs/components/field" },
		{ title: "Error summary", description: "List every error at the top of a long form.", href: "/docs/components/error-summary" },
	]}
/>


# Grid (/docs/components/grid)

<ComponentMeta file="layout" pattern="CSS grid" />

<Playground
	name="grid/playground"
	component="Grid"
	controls={[
		{ prop: "minChildWidth", options: ["8rem", "12rem", "16rem"], default: "12rem" },
		{ prop: "align", options: ["stretch", "start", "center", "end"], default: "stretch" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It has no state, so it renders on the server.

<Import names="Grid" />

## Anatomy [#anatomy]

One grid element with `data-slot="grid"`. Its children are the cells; any child can span with `gridColumn`, like the card here that takes the whole row.

<Anatomy
	tree={{
		slot: "grid",
		tag: "div",
		note: 'minChildWidth="9rem"',
		row: true,
		children: [
			{ slot: "stat", tag: "article", note: "one cell" },
			{ slot: "stat", tag: "article" },
			{ slot: "stat", tag: "article" },
			{ slot: "card", tag: "div", note: 'gridColumn: "1 / -1"' },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Make the window narrower to see them reflow.

<Preview name="grid/basic" compact />

<ExampleGrid>
	<Example name="grid/auto-fit" title="Cards that fit the width" wide>
		`minChildWidth` fits as many columns as there is room for, each at least that wide. No breakpoints: four cards in a row on a desktop, one on a phone.
	</Example>
	<Example name="grid/columns" title="Any column template">
		Pass a string to `columns` for anything CSS grid accepts. `"auto 1fr"` sizes the labels to the longest one and gives the values the rest.
	</Example>
	<Example name="grid/span" title="An item across the row">
		There is no span prop: set `gridColumn` on the child. `"1 / -1"` takes the whole row however many columns fit, so it never breaks the layout.
	</Example>
	<Example name="grid/form-two-columns" title="Two columns, one on phones" wide>
		Pair short fields side by side and give long ones the whole row. With `minChildWidth`, the form falls back to a single column on narrow screens.
	</Example>
	<Example name="grid/align-toggle" title="Equal heights">
		Switch it off. The default `align="stretch"` makes every card in a row as tall as the tallest, so their buttons line up.
	</Example>
	<Example name="grid/gallery" title="Gallery as a list">
		Render `as="ul"` so screen readers announce "6 items". Keep the DOM in the order people see, and avoid `order` or dense packing that would shuffle it.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="grid/context-dashboard" title="Sales dashboard" uses="Grid · Stat · Card · Meter · Badge" />
	<Context name="grid/context-address" title="Address form" uses="Card · Grid · Field · Input · Button" />
	<Context name="grid/context-pricing" title="Pricing plans" uses="Grid · Card · Badge · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="grid/do-equal" title="Cards in a row share one height.">
		With the default stretch and the action at the bottom, the buttons line up and the row reads as a set.
	</Guideline>
	<Guideline kind="dont" name="grid/dont-ragged" title="Cards that end at different heights.">
		`align="start"` leaves a ragged bottom edge, and the eye has to hunt for each button.
	</Guideline>
	<Guideline kind="do" name="grid/do-pair" title="Pair fields that belong together.">
		The card number takes the row; expiry and CVC sit side by side because people fill them in together.
	</Guideline>
	<Guideline kind="dont" name="grid/dont-pair" title="Two columns just to fill the space.">
		Unrelated fields side by side make people zigzag, and the order they read is not the order they type.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="GridProps"
	types={{ as: '"div" | "section" | "ul" | "form" | …', align: "CSS align-items" }}
>
	`as` takes the same tags as [Box](/docs/components/box). When both are set, `minChildWidth` wins over `columns`. Children place themselves with `gridColumn` and `gridRow`.
</Props>

## Styling hooks [#styling-hooks]

Each prop becomes a custom property on the element. Leave a prop out and your stylesheet can set its property instead.

<StylingHooks slots={["grid"]} prefix="grid" attributes={[{ attr: "data-slot", value: '"grid"' }]}>

```css
/* a sidebar layout from 48rem up, one column below */
@media (min-width: 48rem) {
  .account[data-slot="grid"] {
    --cml-grid-columns: 16rem minmax(0, 1fr);
  }
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Grid renders no interactive element. Tab moves through its children in DOM order, row by row." }]}
	notes={[
		"Grid is layout, not a data grid: it has no grid role and no arrow-key navigation. For data people compare across rows, use a Table.",
		"Keep the visual order equal to the DOM order. order, grid-auto-flow: dense and explicit placement can move cells without moving focus or what screen readers read.",
		"Render a collection of cards or photos as=\"ul\" so its size is announced, and name it with aria-label when there is no visible heading.",
		"Don't rely on position to carry meaning (\"the card on the right\"): with minChildWidth, the right column drops below on a phone.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Stack", description: "One column or one row, when cells don't need to line up.", href: "/docs/components/stack" },
		{ title: "Card", description: "The surface most grids are made of.", href: "/docs/components/card" },
		{ title: "Table", description: "Rows and columns of data, with headers people can navigate.", href: "/docs/components/table" },
	]}
/>


# HoverCard (/docs/components/hover-card)

<ComponentMeta file="hover-card" primitive="Base UI" pattern="Link + preview on hover and focus" />

<Playground
	name="hover-card/playground"
	component="HoverCardContent"
	controls={[
		{ prop: "align", options: ["start", "center", "end"], default: "start" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="HoverCard, HoverCardTrigger, HoverCardContent, HoverCardArrow" />

## Anatomy [#anatomy]

The trigger is a link (`hover-card-trigger`, an `<a>`). The card renders in a portal, wrapped in a scope that keeps the skin, mode and brand of the page around the link.

<Anatomy
	tree={{
		slot: "hover-card-positioner",
		tag: "div",
		note: "in a portal",
		children: [
			{
				slot: "hover-card-popup",
				tag: "div",
				note: "no role",
				children: [{ slot: "hover-card-arrow", tag: "div", note: "optional" }],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Hover a link, or Tab to it: the card opens on focus too.

Which one? A **Tooltip** names a control in a few words. A **HoverCard** previews where a link goes, as a bonus for mouse and keyboard users. A **Toggletip** explains a term on click, so it is the one that works on touch and that screen readers read.

<Preview name="hover-card/basic" compact />

<ExampleGrid>
	<Example name="hover-card/author-byline" title="Author of an article">
		Readers check who wrote it without leaving the page. Clicking the name still opens the profile, which is the only way in on a phone.
	</Example>
	<Example name="hover-card/link-preview" title="Link preview">
		Show the title and a one-line summary of the page, so people know if it's worth the click. The link text already says where it goes.
	</Example>
	<Example name="hover-card/a11y-bonus" title="Only a bonus">
		Screen readers don't read the card and touch screens never open it. Put the key fact in the link text ("your account manager"), not only in the card.
	</Example>
	<Example name="hover-card/delays" title="Longer delay in a list">
		In a list of names, `delay={1000}` keeps cards from flashing while the pointer only crosses the list. The default is 600 ms to open and 300 ms to close.
	</Example>
	<Example name="hover-card/lazy-load" title="Load when it opens">
		Hover it. Fetch the details in `onOpenChange`, not for every link on the page, and show a `Skeleton` with `aria-busy` while they load.
	</Example>
	<Example name="hover-card/alignment" title="Alignment" wide>
		`align` lines the card up with the start, center or end of the link. `side` picks the side it opens on; it flips when there is no room.
	</Example>
	<Example name="hover-card/with-arrow" title="With an arrow">
		Add `HoverCardArrow` when several links sit close together, so it's clear which one the card belongs to.
	</Example>
</ExampleGrid>

## In context [#in-context]

Hover cards add a quick look to links people already have. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="hover-card/context-comments" title="Comment thread" uses="Card · Avatar · Link · HoverCard" />
	<Context name="hover-card/context-team-table" title="Task owners" uses="Table · Badge · Avatar · HoverCard" />
	<Context name="hover-card/context-article" title="Help article" uses="Card · Link · HoverCard" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="hover-card/do-real-link" title="A link that works on its own.">
		The profile page has everything the card shows, so a click, a tap or Enter gets people there.
	</Guideline>
	<Guideline kind="dont" name="hover-card/dont-dead-trigger" title="A trigger that goes nowhere.">
		Without `href` it can't be focused or tapped, so keyboard and phone users never see the card.
	</Guideline>
	<Guideline kind="do" name="hover-card/do-summary" title="A short, read-only summary.">
		Three or four facts people can take in at a glance, then move on.
	</Guideline>
	<Guideline kind="dont" name="hover-card/dont-actions" title="Buttons inside the card.">
		It closes when the pointer slips away, and keyboard users can't reach it. Put actions on the profile page, or use a popover.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="hover-card" type="HoverCardContentProps">
	`HoverCardTrigger` takes `delay` (ms before it opens, default 600), `closeDelay` (ms before it closes, default 300) and `render` to use a `Link`. `HoverCard` takes `open`, `onOpenChange` and `defaultOpen`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the card itself.

<StylingHooks
	slots={["hover-card-trigger", "hover-card-positioner", "hover-card-popup", "hover-card-arrow"]}
	prefix="hover-card"
	attributes={[
		{ attr: "data-popup-open", value: "on the trigger while the card is open" },
		{ attr: "data-side", value: "bottom · top" },
		{ attr: "data-align", value: "start · center · end" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Focusing the link opens the card after the same delay as hover. Focus stays on the link; the next Tab moves on and closes the card." },
		{ key: "Escape", description: "Closes the card. Focus stays on the link." },
		{ key: "Enter", description: "Follows the link, as on any link." },
	]}
	notes={[
		"Screen readers don't hear the card: the popup has no role and nothing links it to the trigger. The link text and the page it opens must carry everything.",
		"Touch screens have no hover: a tap follows the link and the card never opens.",
		"The card is never in the tab order, so keyboard users can't reach anything inside it. Never put links or buttons in it.",
		"The pointer can move from the link onto the card without closing it, as WCAG 1.4.13 asks.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Tooltip", description: "A short label for an icon button, on hover or focus.", href: "/docs/components/tooltip" },
		{ title: "Toggletip", description: "An explanation that opens on click, so it works on touch too.", href: "/docs/components/toggletip" },
		{ title: "Avatar", description: "The photo or initials at the top of a profile card.", href: "/docs/components/avatar" },
	]}
/>


# Image (/docs/components/image)

<ComponentMeta file="image" pattern="HTML figure + img" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It is a client component, because it watches the image's error event.

<Import names="Image" />

## Anatomy [#anatomy]

A `<figure>` while the image works, and a `<div>` in its place when it fails. `style` and `className` go to the outer element; every other prop goes to the `<img>`.

<Anatomy
	tree={{
		slot: "image",
		tag: "figure",
		children: [
			{ slot: "image-skeleton", tag: "span", note: "while loadingState" },
			{ slot: "image-img", tag: "img" },
			{ slot: "image-caption", tag: "figcaption", row: true, children: [{ slot: "image-caption-meta", tag: "span", note: "captionMeta" }] },
		],
	}}
/>

When it fails, the default fallback replaces the whole figure:

<Anatomy
	tree={{
		slot: "image-fallback",
		tag: "div",
		note: "role=img",
		row: true,
		children: [
			{ slot: "icon", tag: "svg" },
			{ slot: "image-fallback-body", tag: "div", children: [{ slot: "image-fallback-title", tag: "p" }, { slot: "image-fallback-subtitle", tag: "p" }] },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="image/basic" compact />

<ExampleGrid>
	<Example name="image/with-caption" title="Caption and credit">
		`caption` becomes a `<figcaption>` that screen readers tie to the image; put the credit or file size in `captionMeta`.
	</Example>
	<Example name="image/aspect-ratio" title="Size and crop">
		`width` and `height` reserve the space before the file arrives; an `aspectRatio` in `style` crops the same photo to 16:9 or 1:1 with `object-fit: cover`.
	</Example>
	<Example name="image/loading-state" title="Loading skeleton">
		Set `loadingState` while you wait for the file and clear it in `onLoad`; the component doesn't clear it for you.
	</Example>
	<Example name="image/fallback-default" title="When the file fails">
		The default fallback keeps the frame and shows the file name. It takes `role="img"` and the `alt` as its name, so screen readers still hear what was meant to be there.
	</Example>
	<Example name="image/custom-fallback" title="Fallback with a retry">
		Click Try again. A custom `fallback` can hold controls, and it gets `role="group"` so they stay reachable; after the retry, focus stays on the box and a status message confirms it.
	</Example>
	<Example name="image/interactive-toggle" title="The three states">
		Switch between loaded, loading and failed. The failed state is read only on mount, so change `key` when you need to reset it.
	</Example>
	<Example name="image/decorative" title="Decorative image">
		Use `alt=""` only when the text next to it already says everything. `alt` defaults to empty, so a photo without `alt` is hidden from screen readers too.
	</Example>
</ExampleGrid>

## In context [#in-context]

Images usually sit at the top of a card or in a grid of thumbnails. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="image/context-blog" title="Article card" uses="Card · Image · Badge" wide />
	<Context name="image/context-product" title="Product card" uses="Card · Image · Button" wide />
	<Context name="image/context-gallery" title="Media library" uses="Card · Image" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="image/do-descriptive-alt" title="Describe what the image shows.">
		Say what matters in this context, in one sentence, as you would to someone on the phone.
	</Guideline>
	<Guideline kind="dont" name="image/dont-redundant-alt" title="A file name as alt.">
		Screen readers already say "image", and "image.png" tells nothing about the content.
	</Guideline>
	<Guideline kind="do" name="image/do-same-ratio" title="One ratio per grid.">
		Give every thumbnail the same `aspectRatio`, so rows line up whatever shape each photo has.
	</Guideline>
	<Guideline kind="dont" name="image/dont-mixed-ratios" title="Each image in its own ratio.">
		The row turns ragged, and the eye follows the gaps instead of the pictures.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="image"
	type="ImageProps"
	include={["src", "alt", "width", "height", "onLoad", "onError"]}
	describe={{
		src: "The file to show. Without it, the fallback shows right away.",
		alt: "What the image shows. It also names the fallback. Defaults to `\"\"`, which marks the image as decorative.",
		width: "Width of the file. With `height`, the browser reserves the space before it loads.",
		height: "Height of the file. With `width`, the browser reserves the space before it loads.",
		onLoad: "Runs when the file has loaded. Clear `loadingState` here.",
		onError: "Runs when the file fails; the fallback then takes its place.",
	}}
>
	`style` and `className` go to the outer `<figure>` or fallback; an `aspectRatio` or height there crops the image. Every other `<img>` attribute, like `loading="lazy"` or `srcSet`, goes to the image.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slots, or set the tokens on a parent, a skin or the image itself.

<StylingHooks
	slots={["image", "image-img", "image-skeleton", "image-caption", "image-caption-meta", "image-fallback", "image-fallback-body", "image-fallback-title", "image-fallback-subtitle"]}
	prefix="image"
	attributes={[{ attr: "data-loading", value: "on image, while loadingState is on" }]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "The image is not a Tab stop. Tab reaches only controls inside a custom fallback, like Try again." }]}
	notes={[
		"Loaded, it is an <img> inside a <figure>; the caption is a <figcaption>.",
		"Give every image that carries meaning an alt. Without one, alt is \"\" and screen readers skip it.",
		"The default fallback is role=\"img\" named by alt, so a broken photo still has a name. Without alt it is named \"Unavailable image\", in English.",
		"The skeleton is aria-hidden and the figure has no busy state, so a slow image is not announced.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Avatar", description: "A small round photo of a person, with initials when it fails.", href: "/docs/components/avatar" },
		{ title: "Carousel", description: "Several images or slides in one place, one at a time.", href: "/docs/components/carousel" },
		{ title: "Skeleton", description: "Placeholders for text and blocks while a page loads.", href: "/docs/components/skeleton" },
	]}
/>


# Input group (/docs/components/input-group)

<ComponentMeta file="input-group" primitive="Base UI" pattern="HTML input + button" />

<Playground
	name="input-group/playground"
	component="PasswordInput"
	controls={[
		{ prop: "size", options: ["sm", "md"], default: "md" },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Put it in a `Field` to give it a label.

<Import names="InputGroup, InputAddon, PasswordInput, SearchInput, Input" />

## Anatomy [#anatomy]

The group draws one border and one focus ring. The input inside drops its own, and addons, icons and buttons sit at either end.

<Anatomy
	keys={[
		{ label: '[data-slot="input-group"]', color: "#8be36f" },
		{ label: '[data-slot="input-addon"] · [data-slot="icon"] · [data-slot="input-group-button"]', color: "#ffcf7a" },
		{ label: '[data-slot="input-group-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">https://</span>
	<span className="a-label">input</span>
	<span className="a-part">button</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="input-group/basic" compact />

<ExampleGrid>
	<Example name="input-group/password-rules" title="Password with live rules">
		Type a password. With the text visible, people catch the typo that a rule like "one number" would otherwise reject twice.
	</Example>
	<Example name="input-group/search-filter" title="Search with clear">
		Type, then press the × or Esc. Clearing fires `onChange` and puts focus back in the input, and the count is announced with `aria-live`.
	</Example>
	<Example name="input-group/search-shortcut" title="Keyboard shortcut">
		Press / outside a field. `shortcut` only draws the hint while the field is empty: wire the key yourself and declare it with `aria-keyshortcuts`.
	</Example>
	<Example name="input-group/url-prefix" title="URL with a prefix">
		The fixed part sits in an `InputAddon`, so people type only the domain and the value you save has no "https://" to strip.
	</Example>
	<Example name="input-group/currency" title="Currency and period">
		A currency before and a period after say what the number means, so the label can stay short.
	</Example>
	<Example name="input-group/copy-link" title="Copy button">
		Click Copy. A `Button` inside the group shares its border, and the new label is announced, so people know it worked.
	</Example>
	<Example name="input-group/leading-icon" title="Leading icon">
		An icon helps people scan a long form, but it is decoration: mark it `aria-hidden` and let the label do the naming.
	</Example>
	<Example name="input-group/invalid" title="Invalid">
		In an invalid `Field` the whole group turns red, addon included, and the error says what to try instead.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="input-group/context-sign-in" title="Sign-in card" uses="Card · Field · InputGroup · PasswordInput · Button" />
	<Context name="input-group/context-header" title="App header search" uses="SearchInput · Button" />
	<Context name="input-group/context-shop" title="Shop settings" uses="Card · Field · InputGroup · InputAddon · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="input-group/do-addon" title="Put the fixed part in an addon.">
		People type only what changes, and can't get the prefix wrong.
	</Guideline>
	<Guideline kind="dont" name="input-group/dont-type-prefix" title="Make people type the fixed part.">
		Half will skip "https://", the other half will type it twice.
	</Guideline>
	<Guideline kind="do" name="input-group/do-reveal" title="One password field with a reveal button.">
		People check what they typed by looking at it.
	</Guideline>
	<Guideline kind="dont" name="input-group/dont-confirm" title="A second field to confirm the password.">
		It doubles the typing and still can't show a typo that both fields share.
	</Guideline>
</Guidelines>

## Props [#props]

`PasswordInput` and `SearchInput` take every prop of `Input`, plus their own:

<Props file="input-group" type="PasswordInputProps" include={["disabled"]} />

<Props file="input-group" type="SearchInputProps">
	`InputGroup` takes `size` and the attributes of a `<div>`; `InputAddon` takes those of a `<span>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the group itself.

<StylingHooks
	slots={["input-group", "input-group-input", "input-addon", "input-group-button"]}
	prefix="input-addon"
	attributes={[
		{ attr: "data-slot", value: '"input-group" · "input-group-input" · "input-addon" · "input-group-button"' },
		{ attr: "data-size", value: '"sm" · "md" on the group' },
		{ attr: "data-pressed", value: "on the password button while the text is visible" },
		{ attr: "data-invalid", value: "on the input when its Field is invalid; the group turns red with it" },
	]}
>

```css
/* addons without a tinted background, only in the checkout */
.checkout [data-slot="input-group"] {
  --cml-input-addon-bg: transparent;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the input, then to the show/hide or clear button." },
		{ key: "Enter · Space", description: "On the show/hide button: shows or hides the password. On the clear button: clears the search." },
		{ key: "Escape", description: "In a SearchInput: clears the text (the browser's search behavior)." },
	]}
	notes={[
		"The password button's name says what a press does (\"Show password\" / \"Hide password\"), so it is not also aria-pressed. Focus stays on it, so people can toggle back.",
		"Clearing a search returns focus to the input, so people can type the next query right away.",
		"showLabel, hideLabel and clearLabel default to English. Pass translated ones.",
		"Addon text is read with the input unless you mark it aria-hidden. Hide decoration like \"https://\", keep units like \"/mo\" readable.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Field", description: "Label, description and error for a control.", href: "/docs/components/field" },
		{ title: "Combobox", description: "A search input that suggests values.", href: "/docs/components/combobox" },
		{ title: "Number field", description: "A number input with step buttons.", href: "/docs/components/number-field" },
	]}
/>


# Kbd (/docs/components/kbd)

<ComponentMeta file="display" pattern="HTML kbd" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Kbd" />

## Anatomy [#anatomy]

One `<kbd>` per key. A combination is several `Kbd` side by side, not one.

<Anatomy tree={{ slot: "kbd", tag: "kbd", note: "one key" }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="kbd/basic" compact />

<ExampleGrid>
	<Example name="kbd/combinations" title="Key combinations" wide>
		One `Kbd` per key, so people see at a glance how many keys to press and which ones.
	</Example>
	<Example name="kbd/symbols" title="Mac symbols" wide>
		⌘ and ⌥ mean nothing to a screen reader. Hide the glyph with `aria-hidden` and add the key's name with `VisuallyHidden`.
	</Example>
	<Example name="kbd/platforms" title="Windows and Mac">
		The same action uses Ctrl on Windows and ⌘ on a Mac. When you don't know the system, show both, each with its name.
	</Example>
	<Example name="kbd/sequence" title="One key, then another">
		For shortcuts pressed one after the other, write "then" between the keys. Without it, people press them together.
	</Example>
	<Example name="kbd/in-menu" title="In a menu">
		Open the menu. Shortcuts sit at the end of each item, so people learn them while they click. `aria-keyshortcuts` tells screen readers the keys.
	</Example>
	<Example name="kbd/with-tooltip" title="In a tooltip">
		Hover or focus the button. The tooltip teaches the shortcut at the moment people use the action.
	</Example>
	<Example name="kbd/interactive-recorder" title="Change a shortcut">
		Click "Change shortcut" and press new keys. Tab and Escape are never recorded: Tab moves on, Escape cancels, so keyboard users can always leave.
	</Example>
</ExampleGrid>

## In context [#in-context]

Shortcuts show up where people act. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="kbd/context-shortcuts-dialog" title="Shortcut list" uses="Card · Kbd" />
	<Context name="kbd/context-search-input" title="Search field with a shortcut" uses="SearchInput · Kbd" />
	<Context name="kbd/context-editor-footer" title="Editor status bar" uses="Kbd" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="kbd/do-individual-keys" title="One Kbd per key.">
		Separate caps show how many keys there are, and each one reads as a key.
	</Guideline>
	<Guideline kind="dont" name="kbd/dont-merged-keys" title="The whole shortcut in one cap.">
		"Ctrl + S" in one box looks like a single key with a strange name.
	</Guideline>
	<Guideline kind="do" name="kbd/do-aria-keys" title="Give symbols a name.">
		Screen readers skip ⌘ or read it as "place of interest". Add "Command" as hidden text.
	</Guideline>
	<Guideline kind="dont" name="kbd/dont-prose-text" title="Shortcuts lost in a sentence.">
		"Press ctrl and k" blends into the text, and people skimming the page miss it.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="KbdProps">
	`Kbd` has no props of its own. It renders a `<kbd>` and takes its attributes, like `className` and `style`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the slot, or set the tokens on a parent, a skin or the key itself.

<StylingHooks slots={["kbd"]} />

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Kbd only shows keys and never takes focus. The control it belongs to does." }]}
	notes={[
		"Kbd does not create the shortcut. Listen for the keys yourself, and put aria-keyshortcuts on the control it triggers, like \"Control+S\".",
		"Symbols such as ⌘, ⌥ and ⇧ need a text name. Hide the glyph with aria-hidden and add the name with VisuallyHidden; many screen readers ignore aria-label on a <kbd>.",
		"Never take over Tab, Shift+Tab or Escape. People need them to move on and to leave (WCAG 2.1.2).",
		"Single-key shortcuts, like / or ?, must be easy to turn off, or only work while their area has focus (WCAG 2.1.4).",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Tooltip", href: "/docs/components/tooltip", description: "A short label on hover or focus, a good place to teach a shortcut." },
		{ title: "Input group", href: "/docs/components/input-group", description: "SearchInput shows a shortcut hint inside the field." },
		{ title: "Code block", href: "/docs/components/code-block", description: "For commands people type, not keys they press." },
	]}
/>


# Link (/docs/components/link)

<ComponentMeta file="link" pattern="WAI-ARIA link" />

<Playground
	name="link/playground"
	component="Link"
	label="Read the full guide"
	controls={[
		{ prop: "variant", options: ["default", "muted", "standalone"], default: "default" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Link" />

## Anatomy [#anatomy]

A plain `<a>`. The standalone variant adds an arrow icon after the text. Both have a `data-slot` you can target from CSS.

<Anatomy tree={{ slot: "link", tag: "a", row: true, children: [{ slot: "icon", tag: "svg", note: "standalone only" }] }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="link/basic" compact />

<ExampleGrid>
	<Example name="link/variants" title="Variants" wide>
		Use the default link inside sentences, the muted one where many links sit together (a footer, a legal line), and standalone for the one next step of a section.
	</Example>
	<Example name="link/standalone" title="Standalone">
		A standalone link sits on its own line, so it gets an arrow and a 24px tall target that is easy to hit on a phone.
	</Example>
	<Example name="link/current-page" title="Current page in a menu">
		Click a section. `aria-current="page"` tells screen readers which link is the page you are on; the bold weight shows it to everyone else.
	</Example>
	<Example name="link/external" title="Opens in a new tab">
		A new tab breaks the Back button, so say so. The icon shows it, and hidden text puts "opens in a new tab" in the name screen readers hear.
	</Example>
	<Example name="link/download" title="Download a file">
		Click it to get a real CSV. Put the format and size in the text, so people know what they get before they tap on a slow connection.
	</Example>
	<Example name="link/skip-link" title="Skip to content">
		Click just above the box and press Tab. The first stop is a hidden link that appears on focus and jumps past the menu, so keyboard users don't tab through it on every page.
	</Example>
	<Example name="link/next-link" title="With the Next.js router">
		Pass `render={<NextLink href="…" />}`. The router handles the click without reloading the page, and the link keeps the skin's style.
	</Example>
</ExampleGrid>

## In context [#in-context]

Links sit where people decide where to go next. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="link/context-footer" title="Site footer" uses="Link" />
	<Context name="link/context-banner" title="Release banner" uses="Link" />
	<Context name="link/context-card-link" title="Card with a linked title" uses="Card · Link" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="link/do-meaningful-text" title="Say where the link goes.">
		Screen reader users often jump from link to link, so each one has to make sense out of its sentence.
	</Guideline>
	<Guideline kind="dont" name="link/dont-click-here" title='"Click here" or "Read more".'>
		In a list of links, ten "Click here" sound the same and tell people nothing.
	</Guideline>
	<Guideline kind="do" name="link/do-standalone-cta" title="One standalone link for the next step.">
		Use it for the main way forward from a section, like starting a guide.
	</Guideline>
	<Guideline kind="dont" name="link/dont-button-as-link" title="A link that deletes, saves or copies.">
		Actions belong to `Button`. Screen readers announce a link as "go somewhere", and people don't expect it to change data.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="link" type="LinkProps">
	`Link` takes every `<a>` attribute, like `href`, `target`, `rel`, `download` and `aria-current`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the link itself.

<StylingHooks
	slots={["link", "icon"]}
	attributes={[
		{ attr: "data-variant", value: "default · muted · standalone" },
		{ attr: "aria-current", value: "page (set it yourself on the current page)" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to the next link." },
		{ key: "Enter", description: "Follows the link. Space does not, unlike a button." },
	]}
	notes={[
		"The text is the name screen readers hear. Add hidden text when the icon carries meaning, like \"opens in a new tab\".",
		"Mark the link to the page people are on with aria-current=\"page\", and don't rely on color alone to show it.",
		"Standalone links are at least 24px tall (WCAG 2.5.8). Links inside a sentence are exempt, but leave space between links in a list.",
		"If clicking it changes data or opens a dialog, it is a button. Use Button, even if it looks like a link.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Button", description: "For actions: save, copy, delete, open a dialog.", href: "/docs/components/button" },
		{ title: "Typography", description: "Headings and paragraphs that links sit inside.", href: "/docs/components/typography" },
		{ title: "Card", description: "A box that often links to a detail page from its title.", href: "/docs/components/card" },
	]}
/>


# Menu (/docs/components/menu)

<ComponentMeta file="menu" primitive="Base UI" pattern="WAI-ARIA Menu Button" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the parts you need. The popup renders in a portal and keeps the skin, mode and brand of the page around it.

<Import names="Menu, MenuTrigger, MenuContent, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuSub, MenuSubTrigger, MenuSubContent, MenuGroup, MenuGroupLabel, MenuSeparator" />

## Anatomy [#anatomy]

`Menu` holds the open state. `MenuTrigger` is the button (`data-slot="menu-trigger"`, or the `Button`'s own slot when you pass `render={<Button />}`); `MenuContent` renders the popup below in a portal. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "menu-positioner",
		tag: "div",
		note: "in a portal",
		children: [
			{
				slot: "menu-popup",
				tag: "div",
				note: "role=menu",
				children: [
					{
						slot: "menu-group",
						tag: "div",
						children: [
							{ slot: "menu-group-label", tag: "div" },
							{
								slot: "menu-item",
								tag: "div",
								row: true,
								children: [
									{ slot: "menu-item-icon", tag: "span" },
									{ slot: "menu-shortcut", tag: "span" },
								],
							},
							{
								slot: "menu-checkbox-item",
								tag: "div",
								children: [{ slot: "menu-checkbox-indicator", tag: "span" }],
							},
							{
								slot: "menu-radio-item",
								tag: "div",
								children: [
									{ slot: "menu-radio-indicator", tag: "span", children: [{ slot: "menu-radio-dot", tag: "span" }] },
								],
							},
						],
					},
					{
						slot: "menu-sub-trigger",
						tag: "div",
						note: "opens menu-sub-popup",
						children: [{ slot: "menu-sub-arrow", tag: "span" }],
					},
					{ slot: "menu-separator", tag: "div" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above, and they all start closed.

<Preview name="menu/basic" compact />

<ExampleGrid>
	<Example name="menu/with-shortcuts" title="With shortcuts">
		Show the shortcut with `Kbd` so people learn it while they use the menu, and add `aria-keyshortcuts` so screen readers say it too. The menu only displays it: wire the keys yourself.
	</Example>
	<Example name="menu/groups" title="Groups and separators">
		Past five or six items, a `MenuGroupLabel` over each group lets people skip to the right part instead of reading every row.
	</Example>
	<Example name="menu/checkbox" title="Checkbox items">
		Turn options on and off. `MenuCheckboxItem` stays open after a click and reports `aria-checked`, so screen readers say "checked" or "not checked".
	</Example>
	<Example name="menu/interactive-status" title="Act, then announce">
		Pick an action. Focus goes back to the trigger, and a `role="status"` line tells screen readers what happened, because the menu that showed it is gone.
	</Example>
	<Example name="menu/destructive" title="Destructive, with a confirm">
		Pick "Delete project". It comes last, after a separator, and opens an `AlertDialog`; `finalFocus` brings focus back to the menu button when it closes.
	</Example>
	<Example name="menu/disabled-reason" title="Disabled, with a reason">
		Keep an unavailable action in the menu so people learn it exists, and say why in the item itself: the reason is read with its name.
	</Example>
	<Example name="menu/icon-only" title="Icon-only trigger">
		A "⋯" button has no text, so its `aria-label` says what the actions are for: "Actions for invoice INV-4029", not just "More".
	</Example>
	<Example name="menu/links" title="Links as items">
		For a few related pages, like a help menu, give an item `render={<a href="…" />}`: it opens with Enter, and the browser can open it in a new tab.
	</Example>
	<Example name="menu/view-options" title="Radio items and a submenu">
		For a view setting with one choice, like list or grid, use `MenuRadioItem`; tuck a longer group, like the sort order, into a `MenuSub` that → opens and ← closes.
	</Example>
</ExampleGrid>

## In context [#in-context]

Menus keep the secondary actions out of the way. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="menu/context-table-row" title="Row actions" uses="Table · Badge · IconButton · Menu" />
	<Context name="menu/context-account" title="Account menu" uses="Avatar · Button · Menu" />
	<Context name="menu/context-file-card" title="File card" uses="Card · Badge · IconButton · Menu" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="menu/do-verbs" title="Short labels that start with a verb.">
		"Rename", "Duplicate", "Move to folder…": people know what each item does before they pick it.
	</Guideline>
	<Guideline kind="dont" name="menu/dont-pick-value" title="A menu to pick a value.">
		After the click the trigger still says "Country", and the form gets nothing. Use a Select; to move between pages, use links or a NavigationMenu.
	</Guideline>
	<Guideline kind="do" name="menu/do-danger-last" title="Destructive actions last, after a separator.">
		The red item is out of the way of a quick ↓ Enter, and its color says it is different.
	</Guideline>
	<Guideline kind="dont" name="menu/dont-danger-middle" title="Delete between everyday actions.">
		One slip of the pointer or the arrow keys and the wrong thing is gone.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="menu" type="MenuItemProps" include={["onClick", "closeOnClick", "disabled", "label", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ onClick: "Runs when the item is chosen with a click, Enter or Space.", closeOnClick: "Whether choosing the item closes the menu.", disabled: "Disables the item. It stays focusable, so people can still read it.", label: "Text for typeahead when the item's content is not plain text.", render: "Renders another element, such as an `<a>` for a link." }}
>
	These are the props of `MenuItem`. `Menu` takes Base UI's root props: `open`, `onOpenChange`, `modal` and `disabled`. `MenuCheckboxItem` takes `checked`, `defaultChecked`, `onCheckedChange` and `closeOnClick` (off by default). `MenuRadioGroup` takes `value`, `defaultValue` and `onValueChange`, and each `MenuRadioItem` a `value`; a `MenuGroupLabel` inside the group names it. Wrap a `MenuSubTrigger` and its `MenuSubContent` in a `MenuSub`. `MenuTrigger` takes `render`, usually `<Button />` or `<IconButton aria-label="…" />`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the popup itself.

<StylingHooks
	slots={["menu-trigger", "menu-popup", "menu-item", "menu-item-icon", "menu-shortcut", "menu-checkbox-item", "menu-checkbox-indicator", "menu-radio-item", "menu-radio-indicator", "menu-radio-dot", "menu-sub-trigger", "menu-sub-arrow", "menu-sub-popup", "menu-group-label", "menu-separator"]}
	prefix="menu"
	attributes={[
		{ attr: "data-popup-open", value: "on the trigger while the menu is open" },
		{ attr: "data-highlighted", value: "on the item under the keyboard or pointer" },
		{ attr: "data-checked · data-unchecked", value: "on checkbox and radio items" },
		{ attr: "data-disabled", value: "on a disabled item" },
		{ attr: "data-tone", value: "danger" },
		{ attr: "data-side", value: "top · bottom (on the popup)" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter / Space / ↓", description: "On the trigger: opens the menu and focuses the first item." },
		{ key: "↑", description: "On the trigger: opens the menu and focuses the last item." },
		{ key: "↓ / ↑", description: "Moves between items, wrapping at the ends." },
		{ key: "Home / End", description: "Jumps to the first or last item." },
		{ key: "A–Z", description: "Jumps to the next item that starts with that letter." },
		{ key: "Enter / Space", description: "Chooses the item; on a checkbox or radio item, toggles it and keeps the menu open." },
		{ key: "→ / ←", description: "On a submenu trigger, → opens the submenu on its first item; inside it, ← closes it and goes back." },
		{ key: "Esc", description: "Closes the submenu, or the menu, and returns focus to its trigger." },
		{ key: "Tab", description: "Closes the menu and moves on." },
	]}
	notes={[
		"The trigger reports aria-haspopup and aria-expanded, and so does a submenu trigger; items are menuitem, checkbox items menuitemcheckbox and radio items menuitemradio, both with aria-checked.",
		"Disabled items stay in the arrow-key order and are announced as unavailable, so a reason in their text is read too.",
		"After an action, the menu is gone: announce the result with role=\"status\" and keep focus on the trigger.",
		"The popup is portalled but keeps the skin through PortalScope, and contrast passes WCAG 2.2 AA in all 13 skins.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Select", description: "Picks a value for a form, instead of running an action.", href: "/docs/components/select" },
		{ title: "Context menu", description: "The same actions on right-click.", href: "/docs/components/context-menu" },
		{ title: "Button", description: "One or two actions you can show directly.", href: "/docs/components/button" },
	]}
/>


# Menubar (/docs/components/menubar)

<ComponentMeta file="menubar" primitive="Base UI" pattern="WAI-ARIA Menubar" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the parts you need. The menus render in a portal and keep the skin, mode and brand of the page around them.

<Import names="Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSub, MenubarSubTrigger, MenubarSubContent, MenubarSeparator" />

## Anatomy [#anatomy]

`Menubar` is the bar, one Tab stop. Each `MenubarMenu` pairs a `MenubarTrigger` in the bar with a `MenubarContent` popup, rendered in a portal. Items, checkbox items, radio items and submenus go inside.

<Anatomy
	tree={{
		slot: "menubar",
		tag: "div",
		note: "role=menubar",
		children: [
			{ slot: "menubar-trigger", tag: "button", note: "role=menuitem" },
			{
				slot: "menubar-positioner",
				tag: "div",
				note: "in a portal",
				children: [
					{
						slot: "menubar-popup",
						tag: "div",
						note: "role=menu",
						children: [
							{
								slot: "menubar-item",
								tag: "div",
								row: true,
								children: [
									{ slot: "menubar-item-icon", tag: "span" },
									{ slot: "menubar-item-label", tag: "span" },
									{ slot: "menubar-item-shortcut", tag: "span" },
								],
							},
							{
								slot: "menubar-checkbox-item",
								tag: "div",
								row: true,
								children: [
									{ slot: "menubar-item-indicator", tag: "span", note: "when checked" },
									{ slot: "menubar-item-label", tag: "span" },
								],
							},
							{
								slot: "menubar-sub-trigger",
								tag: "div",
								row: true,
								children: [
									{ slot: "menubar-item-label", tag: "span" },
									{ slot: "menubar-sub-arrow", tag: "span" },
								],
							},
							{ slot: "menubar-separator", tag: "div" },
						],
					},
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above, and they all start closed.

<Preview name="menubar/basic" compact />

<ExampleGrid>
	<Example name="menubar/shortcuts" title="With shortcuts">
		Show each shortcut with `Kbd` so people learn it while they browse, and add `aria-keyshortcuts` so screen readers say it too. The menubar only displays it: wire the keys yourself.
	</Example>
	<Example name="menubar/checkbox" title="Checkbox items">
		Open View and turn the ruler off. `MenubarCheckboxItem` stays open after a click and reports `aria-checked`, so people can flip several settings in a row.
	</Example>
	<Example name="menubar/radio" title="Radio items">
		Pick a zoom level. A `MenubarRadioGroup` is for one value out of a few; each item is announced as "checked" or "not checked".
	</Example>
	<Example name="menubar/submenu" title="Submenu">
		Group variations of one command, like the export formats, under a `MenubarSub`. Keep it to one level: each level is one more hover and one more arrow key.
	</Example>
	<Example name="menubar/disabled-reason" title="Disabled, with a reason">
		Keep an unavailable command in place so people learn where it lives, and say why in the item: disabled items stay focusable, so the reason is read with the name.
	</Example>
	<Example name="menubar/destructive" title="Destructive, with a confirm">
		Pick "Delete document". It comes last, after a separator, and opens an `AlertDialog`; `finalFocus` brings focus back to File when it closes.
	</Example>
	<Example name="menubar/interactive-status" title="Act, then announce">
		Pick a command. Focus goes back to the menu's trigger, and a `role="status"` line tells screen readers what happened, because the menu that showed it is gone.
	</Example>
</ExampleGrid>

## In context [#in-context]

A menubar sits at the top of an app window, above the work. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="menubar/context-spreadsheet" title="Spreadsheet" uses="Menubar · Badge · Kbd · Table" />
	<Context name="menubar/context-photo-editor" title="Photo editor" uses="Menubar · Toolbar" />
	<Context name="menubar/context-mail" title="Mail client" uses="Menubar · Avatar · Badge · Kbd" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="menubar/do-app-window" title="A menubar for an app with many commands.">
		Editors, spreadsheets and design tools have dozens of commands; File, Edit and Format give each one a place people already know.
	</Guideline>
	<Guideline kind="dont" name="menubar/dont-site-nav" title="A menubar to move between pages.">
		Its items are not links: no middle-click, no "open in new tab", and arrow keys a website visitor doesn't expect. Use a NavigationMenu.
	</Guideline>
	<Guideline kind="do" name="menubar/do-groups" title="Related commands together, with their shortcuts.">
		Separators split create, save and print, so people scan three short groups instead of one long list.
	</Guideline>
	<Guideline kind="dont" name="menubar/dont-flat-list" title="Ten commands in no order.">
		Print next to New, Delete next to Rename: people read every row, and a slip lands on the wrong one.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="menubar" type="MenubarItemProps" include={["onClick", "closeOnClick", "disabled", "label", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ onClick: "Runs when the item is chosen with a click, Enter or Space.", closeOnClick: "Whether choosing the item closes the menu.", disabled: "Disables the item. It stays focusable, so people can still read it.", label: "Text for typeahead when the item's content is not plain text.", render: "Renders another element, such as an `<a>` for a link." }}
>
	These are the props of `MenubarItem`. `Menubar` takes `modal`, `disabled`, `loopFocus` and `orientation`, and needs an `aria-label`. `MenubarCheckboxItem` takes `checked`, `defaultChecked`, `onCheckedChange` and `shortcut`; `MenubarRadioGroup` takes `value`, `defaultValue` and `onValueChange`. `MenubarMenu` takes Base UI's menu root props, such as `open` and `onOpenChange`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the bar itself.

<StylingHooks
	slots={["menubar", "menubar-trigger", "menubar-popup", "menubar-item", "menubar-item-icon", "menubar-item-label", "menubar-item-shortcut", "menubar-checkbox-item", "menubar-radio-item", "menubar-item-indicator", "menubar-sub-trigger", "menubar-sub-popup", "menubar-separator"]}
	prefix="menubar"
	attributes={[
		{ attr: "data-popup-open", value: "on the trigger whose menu is open" },
		{ attr: "data-highlighted", value: "on the item under the keyboard or pointer" },
		{ attr: "data-checked · data-unchecked", value: "on checkbox and radio items" },
		{ attr: "data-disabled", value: "on a disabled item" },
		{ attr: "data-tone", value: "danger" },
		{ attr: "data-orientation", value: "horizontal · vertical (on the bar)" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves into the menubar, onto the last-used menu, and out again: the whole bar is one Tab stop." },
		{ key: "→ / ←", description: "In the bar: moves to the next or previous menu, wrapping at the ends. In an open menu: → opens a submenu and ← closes it; on other items they open the next or previous menu." },
		{ key: "↓ / Enter / Space", description: "On a menu in the bar: opens it and focuses the first enabled item." },
		{ key: "↓ / ↑", description: "Moves between items, wrapping at the ends. Disabled items are included." },
		{ key: "Home / End", description: "Jumps to the first or last item." },
		{ key: "A–Z", description: "Jumps to the next item that starts with that letter." },
		{ key: "Enter / Space", description: "Runs the item and closes the menu; on a checkbox or radio item, toggles it and keeps the menu open." },
		{ key: "Esc", description: "Closes the submenu, or the menu and returns focus to its trigger in the bar." },
	]}
	notes={[
		"The bar is role=menubar and needs an aria-label. Its triggers are menuitem with aria-haspopup and aria-expanded; checkbox and radio items report aria-checked.",
		"Once a menu is open, hovering another trigger in the bar switches to it, as in a desktop app.",
		"Shortcuts in Kbd are only shown. Add aria-keyshortcuts so screen readers say them, and handle the keys in your app.",
		"After a command the menu is gone: announce the result with role=\"status\" and leave focus on the trigger.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Menu", description: "One menu behind a button, for the actions of a row or a card.", href: "/docs/components/menu" },
		{ title: "Navigation menu", description: "Links to the pages of a site, with dropdown panels.", href: "/docs/components/navigation-menu" },
		{ title: "Kbd", description: "Shows the keyboard shortcut next to a command.", href: "/docs/components/kbd" },
	]}
/>


# Meter (/docs/components/meter)

<ComponentMeta file="meter" primitive="Base UI" pattern="WAI-ARIA meter" />

<Playground
	name="meter/playground"
	component="Meter"
	controls={[
		{ prop: "tone", options: ["brand", "warning", "danger"], default: "brand" },
		{ prop: "showValue", default: true },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The skin you load styles it.

<Import names="Meter" />

## Anatomy [#anatomy]

A root with a header (label and value) and a track with the fill. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="meter"]', color: "#8be36f" },
		{ label: '[data-slot="meter-track"] · [data-slot="meter-indicator"]', color: "#ffcf7a" },
		{ label: "label · value", color: "#7cc7ff" },
	]}
>
	<span className="a-part">track</span>
	<span className="a-part">indicator</span>
	<span className="a-label">Storage 64.2 of 100 GB</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="meter/basic" compact />

<ExampleGrid>
	<Example name="meter/a11y-vs-progress" title="Meter or Progress?">
		Meter says how full something is, and the value can go up or down. Progress says how far a task has gone, and it only moves toward done.
	</Example>
	<Example name="meter/tones" title="Tones for status">
		`brand` when all is well, `warning` when it gets close to the limit, `danger` when people need to act. Say it in the text too, not only in color.
	</Example>
	<Example name="meter/thresholds" title="Warn before it's full">
		Click to add files. Pick the tone from the value, so the meter turns `warning` at 75% and `danger` when the mailbox is full.
	</Example>
	<Example name="meter/value-label" title="In the real unit">
		Set `max` to the real limit and show "8,450 of 10,000". People think in users and gigabytes, not in percent.
	</Example>
	<Example name="meter/seats" title="Seats, in words">
		`getAriaValueText` lets screen readers say "7 of 10 seats used" instead of "70 percent".
	</Example>
	<Example name="meter/range" title="A range that doesn't start at zero">
		Use `min` and `max` for scales like temperature. The fill shows where 24 °C sits between 16 and 32.
	</Example>
	<Example name="meter/settings-row" title="In a settings row" wide>
		Put the meter next to the action that fixes it. "Free up space" right by the number saves people a search.
	</Example>
</ExampleGrid>

## In context [#in-context]

Meters sit where people check their limits. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="meter/context-plan-limit" title="Team seats" uses="Card · Meter · Button" />
	<Context name="meter/context-password-strength" title="Password strength" uses="Card · Label · Input · Meter" />
	<Context name="meter/context-server" title="Server resources" uses="Card · Meter" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="meter/do-fixed-capacity" title="Measure something with a limit.">
		Disk space, seats, monthly emails: a value and a known maximum.
	</Guideline>
	<Guideline kind="dont" name="meter/dont-task-completion" title="A meter for an upload.">
		An upload is a task with an end. Use Progress, so screen readers announce a progress bar.
	</Guideline>
	<Guideline kind="do" name="meter/do-explain-unit" title="Show the value and the limit.">
		"85 of 100 connections" tells people how much room is left.
	</Guideline>
	<Guideline kind="dont" name="meter/dont-missing-unit" title="A number with no unit.">
		85 what? Percent, megabytes or users? People can't tell whether to worry.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="meter" type="MeterProps" include={["value", "min", "max", "getAriaValueText", "format", "locale"]}
	types={{ getAriaValueText: "(formattedValue, value) => string", format: "Intl.NumberFormatOptions", locale: "Intl.LocalesArgument" }}
	describe={{ value: "The current measurement, between `min` and `max`.", getAriaValueText: "The text screen readers hear for the value. Defaults to the percentage." }}
>
	Other Base UI meter root props and native `<div>` attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["meter", "meter-header", "meter-label", "meter-value", "meter-track", "meter-indicator"]}
	attributes={[
		{ attr: "data-tone", value: "brand · warning · danger" },
		{ attr: "data-slot", value: '"meter" · "meter-track" · "meter-indicator"' },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Not focusable. It shows a value; the controls around it take the focus." }]}
	notes={[
		"It renders role=\"meter\" with aria-valuenow, aria-valuemin and aria-valuemax, and the label as its accessible name.",
		"Screen readers hear the percentage by default. valueLabel only changes the visible text, so pass getAriaValueText with the same words.",
		"Tone is never the only signal: put the status (\"Almost full\") in the value text.",
		"Fills keep at least 3:1 contrast against the track in all 13 skins, light and dark.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Progress", href: "/docs/components/progress", description: "How far a task has gone, like an upload." },
		{ title: "Stat", href: "/docs/components/stat", description: "One key number with a label and a trend." },
		{ title: "Badge", href: "/docs/components/badge", description: "A short status, like \"Almost full\"." },
	]}
/>


# Native select (/docs/components/native-select)

<ComponentMeta file="native-select" primitive="HTML" pattern="Native <select>" />

<Playground
	name="native-select/playground"
	component="NativeSelect"
	controls={[
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need.

<Import names="NativeSelect, Label" />

## Anatomy [#anatomy]

A wrapper around a real `<select>` and a chevron. The options are plain `<option>` and `<optgroup>` elements.

<Anatomy
	keys={[
		{ label: '[data-slot="native-select"]', color: "#8be36f" },
		{ label: '[data-slot="native-select"] > select · [data-slot="icon"]', color: "#ffcf7a" },
		{ label: "<option> (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">select</span>
	<span className="a-label">Brazil</span>
	<span className="a-part">icon</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="native-select/basic" compact />

<ExampleGrid>
	<Example name="native-select/with-description" title="With a description">
		Inside a `Field`, `FieldDescription` is linked to the select, so it is read after the label.
	</Example>
	<Example name="native-select/placeholder" title="Placeholder option">
		An empty, disabled first option plus `required` makes people choose, instead of keeping a guess you made for them.
	</Example>
	<Example name="native-select/groups" title="Option groups">
		`<optgroup>` splits a long list into labeled sections, and screen readers announce the group name.
	</Example>
	<Example name="native-select/long-list" title="Long list">
		Eighty years fit fine: people type "19" to jump, and phones open their own scroll wheel.
	</Example>
	<Example name="native-select/installments" title="Installments">
		Pick a number. A controlled `value` updates the summary, and `aria-live` reads the new amount.
	</Example>
	<Example name="native-select/disabled" title="Disabled, with a reason">
		A disabled select can't be focused, so put the reason in visible text right next to it.
	</Example>
	<Example name="native-select/invalid" title="Required, with an error">
		Choose a method and the error goes away. `Field invalid` marks the select and links the `FieldError` to it.
	</Example>
	<Example name="native-select/inline" title="Inline">
		In a toolbar, `style={{ width: "auto" }}` lets it hug its longest option next to its label.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="native-select/context-pagination" title="Table footer" uses="NativeSelect · Label · IconButton · Text" />
	<Context name="native-select/context-filters" title="Filter panel" uses="Fieldset · NativeSelect · Button" />
	<Context name="native-select/context-shipping" title="Delivery" uses="Card · Field · NativeSelect · Input · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="native-select/do-long-list" title="Long lists people know.">
		Countries, states, years: people scan or type to find them.
	</Guideline>
	<Guideline kind="dont" name="native-select/dont-two-options" title="A select for yes or no.">
		Two options hidden behind a click. Use a `Switch`, a `Checkbox` or a `RadioGroup`.
	</Guideline>
	<Guideline kind="do" name="native-select/do-neutral-first" title="Start with a neutral option.">
		For answers that matter, "Choose a reason…" makes people pick one.
	</Guideline>
	<Guideline kind="dont" name="native-select/dont-preselected" title="An answer already picked.">
		People skip it, and you collect your own default as if it were their answer.
	</Guideline>
</Guidelines>

## Props [#props]

`NativeSelect` takes every attribute of `<select>`. These are the ones you use most:


<Props
	file="native-select"
	type="NativeSelectProps"
	include={["value", "defaultValue", "onChange", "disabled", "required", "name", "autoComplete"]}
	types={{"value": "string", "defaultValue": "string", "onChange": "(event: ChangeEvent<HTMLSelectElement>) => void", "disabled": "boolean", "required": "boolean", "name": "string", "autoComplete": "string"}}
	describe={{"value": "The selected option's `value`, controlled or not.", "defaultValue": "The selected option's `value`, controlled or not.", "onChange": "Runs when people pick another option. Read `event.target.value`.", "disabled": "Disables the select and removes it from the tab order.", "required": "The form won't submit while the selected option has an empty value.", "name": "Identifies the value when the form is submitted.", "autoComplete": "Lets the browser fill it, e.g. `\"country\"` or `\"address-level1\"`."}}
>
	`className` and `style` go to the wrapper `<span>`, so you can size it; every other attribute goes to the `<select>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the select itself.

<StylingHooks
	slots={["native-select"]}
	attributes={[
		{ attr: "data-slot", value: '"native-select" (the wrapper)' },
		{ attr: ":disabled", value: "on the inner select when disabled" },
		{ attr: ":focus", value: "on the inner select while focused" },
		{ attr: "data-invalid", value: "on the inner select when its Field is invalid" },
	]}
>

```css
/* a borderless select inside a table toolbar */
.toolbar [data-slot="native-select"] > select {
  --cml-border-control: transparent;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the select." },
		{ key: "Arrow Up · Arrow Down", description: "Changes the selected option (opens the list on macOS)." },
		{ key: "Alt + Arrow Down", description: "Opens the list of options." },
		{ key: "A–Z", description: "Jumps to the next option that starts with the letter typed." },
	]}
	notes={[
		"It is the browser's own select, so screen readers, voice control and phones all know it.",
		"Inside a Field, the label, description and error are linked to the select; outside one, name it with Label htmlFor.",
		"The chevron is decorative and hidden from assistive tech.",
		"required uses native validation: the form won't submit and the browser explains why.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Select", description: "A custom popup, for short lists with rich options.", href: "/docs/components/select" },
		{ title: "Combobox", description: "Search a long list as you type.", href: "/docs/components/combobox" },
		{ title: "Field", description: "Label, description and error for a control.", href: "/docs/components/field" },
	]}
/>


# Navigation menu (/docs/components/navigation-menu)

<ComponentMeta file="navigation-menu" primitive="Base UI" pattern="WAI-ARIA Disclosure Navigation Menu" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the parts you need. Panels render in a portal and keep the skin, mode and brand of the page around them.

<Import names="NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink" />

## Anatomy [#anatomy]

`NavigationMenu` renders the `<nav>`; give it an `aria-label`. Each `NavigationMenuItem` holds either a `NavigationMenuLink` or a `NavigationMenuTrigger` with its `NavigationMenuContent`, the panel that opens below it.

<Anatomy
	tree={{
		slot: "navigation-menu-list",
		tag: "ul",
		note: "inside the <nav>",
		children: [
			{
				slot: "navigation-menu-item",
				tag: "li",
				row: true,
				children: [
					{
						slot: "navigation-menu-trigger",
						tag: "button",
						note: "aria-expanded",
						children: [{ slot: "navigation-menu-icon", tag: "span", note: "chevron" }],
					},
				],
			},
			{
				slot: "navigation-menu-item",
				tag: "li",
				children: [{ slot: "navigation-menu-link", tag: "a", note: "aria-current when active" }],
			},
			{
				slot: "navigation-menu-positioner",
				tag: "div",
				note: "in a portal",
				children: [
					{
						slot: "navigation-menu-popup",
						tag: "nav",
						children: [
							{
								slot: "navigation-menu-content",
								tag: "div",
								children: [{ slot: "navigation-menu-link", tag: "a" }],
							},
						],
					},
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above, and every panel starts closed.

<Preview name="navigation-menu/basic" compact />

<ExampleGrid>
	<Example name="navigation-menu/links-bar" title="Links only">
		When every top item is a page, you don't need panels: a bar of `NavigationMenuLink`s is a plain list of real links, one Tab stop each.
	</Example>
	<Example name="navigation-menu/mega-panel" title="Products panel">
		Open Products. A short description under each name tells people which product fits before they click, and the icon helps them find it again next time.
	</Example>
	<Example name="navigation-menu/featured" title="Featured card in the panel">
		Promote one timely page, like next week's webinar, beside the regular links. Make the whole card one link so it stays one Tab stop.
	</Example>
	<Example name="navigation-menu/current-page" title="Current page">
		Click the links. `active` sets `aria-current="page"`, which screen readers announce as "current page" and the skin underlines, so it isn't shown by color alone.
	</Example>
	<Example name="navigation-menu/delay" title="Hover delay">
		Move the pointer across the bar. `delay` and `closeDelay` stop panels from flashing open when someone is just passing over them on the way to the page.
	</Example>
	<Example name="navigation-menu/vertical" title="Vertical">
		For the sections of one area, like settings, stack the list down the side. `orientation="vertical"` switches the arrow keys to ↑ and ↓.
	</Example>
	<Example name="navigation-menu/landmarks" title="Named landmarks">
		Screen reader users jump between landmarks by name. With two navs on the page, "Main" and "Footer" tell them apart; two unnamed navs both read as "navigation".
	</Example>
</ExampleGrid>

The bar wraps rather than collapses: it has no phone layout of its own. Below about 640px, swap it for a menu button that opens a [Drawer](/docs/components/drawer) with the same links.

## In context [#in-context]

The navigation menu sits in the header of a site or a section. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="navigation-menu/context-site-header" title="Product site header" uses="NavigationMenu · Button · Card" />
	<Context name="navigation-menu/context-store" title="Store departments" uses="NavigationMenu · SearchInput · IconButton · Badge" />
	<Context name="navigation-menu/context-help-center" title="Help center article" uses="NavigationMenu · Card · Badge" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="navigation-menu/do-destinations" title="Name places people go.">
		"Invoices", "Clients", "Reports": each label is a page, so people know where they'll land and can open it in a new tab.
	</Guideline>
	<Guideline kind="dont" name="navigation-menu/dont-commands" title="Commands dressed as links.">
		"Export CSV" and "Archive" don't take you anywhere. Put actions in a Menu or a Menubar, where they are announced as commands.
	</Guideline>
	<Guideline kind="do" name="navigation-menu/do-describe" title="A few links, each with a line of help.">
		Three options with a sentence each are faster to choose from than a list of names people have to guess at.
	</Guideline>
	<Guideline kind="dont" name="navigation-menu/dont-wall" title="Every page in one panel.">
		Twelve links with no groups or descriptions turn the panel into a sitemap. Split them by topic, or link to a page that lists them.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="navigation-menu" type="NavigationMenuProps" include={["value", "defaultValue", "onValueChange", "delay", "closeDelay", "orientation"]}
	types={{ value: "any", defaultValue: "any", onValueChange: "(value, eventDetails) => void" }}
	describe={{ value: "The `value` of the item whose panel is open, for a controlled menu. `null` closes it.", defaultValue: "The item whose panel starts open. Leave it empty: nothing should open by itself.", onValueChange: "Called when a panel opens or closes, with the reason in `eventDetails`.", delay: "How long the pointer must rest on a trigger before its panel opens, in milliseconds.", closeDelay: "How long a panel waits before closing after the pointer leaves, in milliseconds.", orientation: "Which arrow keys move between the top items: ← → or ↑ ↓." }}
>
	These are the props of `NavigationMenu`. `NavigationMenuLink` takes `active` (sets `aria-current="page"`) and `closeOnClick`. `NavigationMenuTrigger` takes `hideIcon`, and `NavigationMenuContent` takes `align` and `sideOffset`. Give `NavigationMenuItem` a `value` when you control the menu.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the nav itself.

<StylingHooks
	slots={["navigation-menu-list", "navigation-menu-item", "navigation-menu-trigger", "navigation-menu-icon", "navigation-menu-link", "navigation-menu-popup", "navigation-menu-content"]}
	prefix="nav"
	attributes={[
		{ attr: "data-popup-open", value: "on the trigger whose panel is open" },
		{ attr: "aria-current · data-active", value: "page · on the link to the current page" },
		{ attr: "data-open", value: "on the open panel" },
		{ attr: "data-side · data-align", value: "where the panel sits next to its trigger" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab / Shift + Tab", description: "Moves between the top links and triggers. Each one is its own Tab stop, like any list of links." },
		{ key: "→ / ←", description: "Also moves between the top items (↓ / ↑ with orientation=\"vertical\"). It doesn't switch the open panel." },
		{ key: "Enter / Space", description: "On a trigger: opens or closes its panel. On a link: follows it." },
		{ key: "↓", description: "On a trigger in a horizontal bar: opens its panel." },
		{ key: "Esc", description: "Closes the panel and returns focus to its trigger." },
	]}
	notes={[
		"The root is a <nav>: give it an aria-label so it is listed by name among the page's landmarks.",
		"Triggers are buttons with aria-expanded; links are real <a href> elements, so middle-click and \"open in new tab\" work.",
		"Mark the page people are on with active, which sets aria-current=\"page\".",
		"Hover opens a panel after delay (50 ms by default), and moving away closes it after closeDelay. Panels also open from the keyboard, so nothing depends on a mouse.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Drawer", description: "Holds the same links on phones, behind a menu button.", href: "/docs/components/drawer" },
		{ title: "Menubar", description: "Menus of commands for an app, not links to pages.", href: "/docs/components/menubar" },
		{ title: "Menu", description: "A list of actions behind one button.", href: "/docs/components/menu" },
	]}
/>


# Number field (/docs/components/number-field)

<ComponentMeta file="number-field" primitive="Base UI" pattern="WAI-ARIA Spinbutton (keyboard)" />

<Playground
	name="number-field/playground"
	component="NumberField"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Put it in a `Field` to give it a label.

<Import names="NumberField, Field, FieldLabel" />

## Anatomy [#anatomy]

One box with three parts: the minus button, the input and the plus button.

<Anatomy
	keys={[
		{ label: '[data-slot="number-field"] · [data-slot="number-field-group"]', color: "#8be36f" },
		{ label: '[data-slot="number-field-button"]', color: "#ffcf7a" },
		{ label: '[data-slot="number-field-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">−</span>
	<span className="a-label">2</span>
	<span className="a-part">+</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="number-field/basic" compact />

<ExampleGrid>
	<Example name="number-field/bounds" title="Minimum and maximum">
		Click plus until it stops. At `max` the button disables itself, and the description says why before people get there.
	</Example>
	<Example name="number-field/total" title="Live total">
		Change the seats. `value` and `onValueChange` drive the price below, announced with `aria-live`.
	</Example>
	<Example name="number-field/percent" title="Percent, with steps">
		`format={{ style: "percent" }}` works on fractions, so `step={0.05}` is 5 points; `largeStep` is what Shift + arrow adds.
	</Example>
	<Example name="number-field/currency" title="Currency">
		Pass `format` and `locale` and the input shows the currency symbol and separators people expect, while the value stays a number.
	</Example>
	<Example name="number-field/unit" title="With a unit">
		A `unit` format puts "kg" inside the field, so the label doesn't have to say it and nobody guesses pounds.
	</Example>
	<Example name="number-field/required" title="Required">
		Type a number, delete it and leave. Inside a `Field`, `required` and `FieldError match="valueMissing"` work like on any input.
	</Example>
	<Example name="number-field/labels" title="Named step buttons">
		The buttons only show − and +. `decrementLabel` and `incrementLabel` give them names, so translate them with the page.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="number-field/context-cart" title="Shopping cart" uses="Card · Field · NumberField · Button" />
	<Context name="number-field/context-booking" title="Booking" uses="Card · Field · NumberField · Button" />
	<Context name="number-field/context-parcel" title="Package size" uses="Fieldset · Field · NumberField · NativeSelect" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="number-field/do-quantity" title="Small amounts people adjust.">
		Guests, tickets, seats: a click or an arrow key gets there faster than typing.
	</Guideline>
	<Guideline kind="dont" name="number-field/dont-zip" title="Codes that are only digits.">
		ZIP codes, phone and card numbers aren't amounts: steppers and separators break them. Use an `Input` with `inputMode="numeric"`.
	</Guideline>
	<Guideline kind="do" name="number-field/do-unit" title="Show the unit in the value.">
		"45 min" can't be misread.
	</Guideline>
	<Guideline kind="dont" name="number-field/dont-no-unit" title="A bare number.">
		Is 45 minutes, hours or people? Don't make people guess.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="number-field" type="NumberFieldProps"
	include={["value", "defaultValue", "onValueChange", "min", "max", "step", "largeStep", "format", "locale", "disabled", "readOnly", "required", "name"]}
	types={{ onValueChange: "(value: number | null, details) => void", format: "Intl.NumberFormatOptions", locale: "Intl.LocalesArgument" }}
	describe={{ onValueChange: "Runs on every value change, from typing, the buttons or the keyboard. `details.reason` says which." }}
>
	Base UI's other root props pass through, such as `smallStep`, `snapOnStep`, `allowWheelScrub` and `onValueCommitted`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the field itself.

<StylingHooks
	slots={["number-field", "number-field-group", "number-field-input", "number-field-button"]}
	prefix="number"
	attributes={[
		{ attr: "data-slot", value: '"number-field" · "number-field-group" · "number-field-input" · "number-field-button"' },
		{ attr: "data-disabled", value: "on the root when disabled, on a button at its bound" },
		{ attr: "data-readonly", value: "present when read-only" },
		{ attr: "data-invalid", value: "present when invalid" },
		{ attr: "data-scrubbing", value: "present while dragging to change the value" },
	]}
>

```css
/* round step buttons, only in the cart */
.cart [data-slot="number-field"] {
  --cml-number-btn-radius: 999px;
  --cml-number-divider: 0;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Arrow Up · Arrow Down", description: "Adds or subtracts one step." },
		{ key: "Shift + Arrow", description: "Adds or subtracts largeStep." },
		{ key: "Home · End", description: "Jumps to min or max, when they are set." },
		{ key: "Tab", description: "Moves focus to the input. The step buttons are skipped, since the arrows do the same." },
	]}
	notes={[
		"The input is a text box announced as a number field (aria-roledescription), named by the label of its Field.",
		"The step buttons have names from decrementLabel and incrementLabel; they default to English, so pass translated ones.",
		"At a bound, the matching button is disabled, so it never does nothing silently.",
		"It sets inputmode=\"numeric\", so phones open the number pad; with a fractional step or format and min ≥ 0 it uses \"decimal\", which adds the decimal separator.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Field", description: "Label, description and error for a control.", href: "/docs/components/field" },
		{ title: "Slider", description: "Pick a value in a range by dragging.", href: "/docs/components/slider" },
		{ title: "Native select", description: "Pick one value from a fixed list.", href: "/docs/components/native-select" },
	]}
/>


# OTP field (/docs/components/otp-field)

<ComponentMeta file="otp-field" primitive="Base UI" pattern="HTML input (autocomplete=one-time-code)" />

<Playground
	name="otp-field/playground"
	component="OtpField"
	controls={[
		{ prop: "mask", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Put it in a `Field` to give it a label.

<Import names="OtpField, Field, FieldLabel" />

## Anatomy [#anatomy]

A row of cells, one input each. `separator` adds a dash between groups, drawn for the eye only.

<Anatomy
	keys={[
		{ label: '[data-slot="otp-field"]', color: "#8be36f" },
		{ label: '[data-slot="otp-separator"]', color: "#ffcf7a" },
		{ label: '[data-slot="otp-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">4</span>
	<span className="a-label">8</span>
	<span className="a-label">2</span>
	<span className="a-part">–</span>
	<span className="a-label">9</span>
	<span className="a-label">1</span>
	<span className="a-label">3</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="otp-field/basic" compact />

<ExampleGrid>
	<Example name="otp-field/verify" title="Paste, verify and error">
		Paste a code. `onValueComplete` runs once the last cell fills, so you can check it right away; a wrong code marks every cell invalid.
	</Example>
	<Example name="otp-field/expired" title="Expired code">
		When the server rejects the code, set `invalid` on the `Field` and say what to do next, not just that it failed.
	</Example>
	<Example name="otp-field/auto-submit" title="Submit when complete">
		Type six digits. `autoSubmit` submits the form on the last one, and `name` sends the whole code through one hidden input.
	</Example>
	<Example name="otp-field/pin-mask" title="Masked PIN">
		`mask` hides each digit after it is typed. Use it for a PIN someone could read over a shoulder, not for a code that expires in minutes.
	</Example>
	<Example name="otp-field/recovery-code" title="Letters and numbers">
		`validationType="alphanumeric"` accepts letters and opens the full keyboard; `normalizeValue` uppercases them so "k7p" matches.
	</Example>
	<Example name="otp-field/cell-labels" title="Translated cell names">
		The first cell takes the `Field` label and the others get `getCellLabel`, so pass one in the page's language.
	</Example>
	<Example name="otp-field/disabled" title="Disabled while sending">
		Disable it while a new code is on its way, and say so in the description, so nobody types the old one.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="otp-field/context-two-factor" title="Two-step verification" uses="Card · Field · OtpField · Link · Button" />
	<Context name="otp-field/context-phone" title="Confirm a phone number" uses="Card · Field · OtpField · Button" />
	<Context name="otp-field/context-transfer" title="Confirm a transfer" uses="Card · Field · OtpField · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="otp-field/do-say-where" title="Say where the code went.">
		People know which app to open, and notice a wrong number.
	</Guideline>
	<Guideline kind="dont" name="otp-field/dont-bare" title="Just &quot;Code&quot;.">
		From the email, the SMS or the authenticator? People switch apps to guess.
	</Guideline>
	<Guideline kind="do" name="otp-field/do-visible" title="Show the digits as people type.">
		They compare them with the SMS at a glance.
	</Guideline>
	<Guideline kind="dont" name="otp-field/dont-mask" title="Mask a one-time code.">
		It expires in minutes and works once; hiding it only makes typos harder to spot.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="otp-field"
	type="OtpFieldProps"
	include={["length", "value", "defaultValue", "onValueChange", "onValueComplete", "validationType", "normalizeValue", "mask", "autoSubmit", "autoComplete", "name", "required", "disabled"]}
	types={{ getCellLabel: "(index: number, length: number) => string", onValueChange: "(value: string, details) => void", onValueComplete: "(value: string, details) => void", normalizeValue: "(value: string) => string", validationType: "\"numeric\" | \"alpha\" | \"alphanumeric\" | \"none\"" }}
	describe={{ onValueChange: "Runs on every change, from typing, paste or the keyboard. `details.reason` says which.", onValueComplete: "Runs when every cell is filled, after `onValueChange`. Check the code here." }}
>
	Base UI's other root props pass through, such as `readOnly`, `inputMode`, `form` and `onValueInvalid`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the field itself.

<StylingHooks
	slots={["otp-field", "otp-input", "otp-separator"]}
	prefix="otp"
	attributes={[
		{ attr: "data-slot", value: '"otp-field" · "otp-input" · "otp-separator"' },
		{ attr: "data-filled", value: "on a cell with a character; on the root when any cell has one" },
		{ attr: "data-complete", value: "present when every cell is filled" },
		{ attr: "data-invalid", value: "present when its Field is invalid" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-focused", value: "present while any cell has focus" },
	]}
>

```css
/* smaller cells, only in the payment sheet */
.payment-sheet [data-slot="otp-field"] {
  --cml-otp-cell-width: 2.25rem;
  --cml-otp-cell-height: 2.5rem;
  --cml-otp-gap: 0.375rem;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "0–9 · letters", description: "Fills the cell and moves to the next one. Characters that validationType rejects are ignored." },
		{ key: "Backspace", description: "Clears the cell and moves back to the previous one." },
		{ key: "Arrow Left · Arrow Right", description: "Moves between cells without changing them." },
		{ key: "Ctrl + V · Cmd + V", description: "Pastes a whole code and fills every cell from the first." },
		{ key: "Tab", description: "Moves focus into the field and on to the next control." },
	]}
	notes={[
		"The first cell is named by the Field label; the others by getCellLabel, which defaults to English (\"Character 2 of 6\").",
		"autocomplete=\"one-time-code\" is on by default, so iOS and Android offer the code from the SMS above the keyboard. Keep it for SMS and email codes.",
		"The separator is aria-hidden: screen readers hear the cells, not the dashes.",
		"An invalid Field marks every cell with aria-invalid, and each cell is described by the FieldDescription and FieldError. Keep the error right below the cells, where people look after typing.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Field", description: "Label, description and error for a control.", href: "/docs/components/field" },
		{ title: "Input group", description: "Inputs with addons, password and search.", href: "/docs/components/input-group" },
		{ title: "Error summary", description: "Lists a form's errors after submit.", href: "/docs/components/error-summary" },
	]}
/>


# Pagination (/docs/components/pagination)

<ComponentMeta file="pagination" pattern="WAI-ARIA Landmark (navigation)" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. `DataTable` already includes it; use it on its own for any other list.

<Import names="Pagination" />

## Anatomy [#anatomy]

A `nav` landmark around a list. The first and last items are Previous and Next; between them, the page numbers and the gaps. The number of items stays the same as the page changes, so the control doesn't jump in width.

<Anatomy
	tree={{
		slot: "pagination",
		tag: "nav",
		note: "aria-label, holds a ul",
		row: true,
		children: [
			{ slot: "pagination-item", tag: "a | button", note: "Previous" },
			{ slot: "pagination-item", tag: "a | button", note: "aria-current=page" },
			{ slot: "pagination-ellipsis", tag: "li", note: "aria-hidden" },
			{ slot: "pagination-item", tag: "a | button", note: "last page" },
			{ slot: "pagination-item", tag: "a | button", note: "Next" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="pagination/basic" compact />

<ExampleGrid>
	<Example name="pagination/with-links" title="Links, for pages people can share" wide>
		Pass `getHref` when each page has its own URL: search engines follow the links, and people can open a page in a new tab or share it.
	</Example>
	<Example name="pagination/results" title="A list in the browser">
		Change the page. With `onPageChange` the numbers are buttons; focus stays on the one you pressed, and a status message says "Page 3 of 10".
	</Example>
	<Example name="pagination/compact" title="Compact, for phones">
		With text arrows and one sibling, the row wraps to two lines below about 420px. `siblings={0}` and the arrows' names in `VisuallyHidden` keep it under 310px in every skin, one line on a 390px phone; the total moves to the text above.
	</Example>
	<Example name="pagination/page-size" title="With page size and a count" wide>
		Change the rows per page. "Showing 21–40 of 312" says how much there is, and the new page keeps the first row you were looking at.
	</Example>
	<Example name="pagination/first-last" title="First and last always there" wide>
		The first and last pages never leave the row, so a single press goes back to the start or straight to the end of 48 pages.
	</Example>
	<Example name="pagination/siblings" title="Siblings" wide>
		`siblings` sets how many pages show on each side of the current one. Use 0 in narrow places, 2 when people tend to jump a few pages.
	</Example>
	<Example name="pagination/labels" title="Names for screen readers" wide>
		Translate `aria-label`, the arrows and `pageLabel`. Including the total in `pageLabel` makes each number read "Page 3 of 12".
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="pagination/context-blog" title="Blog archive" uses="Card · Link · Badge · Pagination" />
	<Context name="pagination/context-orders" title="Orders table" uses="Table · Badge · NativeSelect · Pagination" />
	<Context name="pagination/context-search" title="Search results" uses="SearchInput · Link · Pagination · VisuallyHidden" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="pagination/do-count" title="Say where people are and how much there is.">
		The current page and "Showing 21–40 of 312" answer both questions before anyone asks.
	</Guideline>
	<Guideline kind="dont" name="pagination/dont-bare" title="Only Previous and Next.">
		Without a page number or a total, people can't tell how far they've gone or how much is left.
	</Guideline>
	<Guideline kind="do" name="pagination/do-whole-list" title="Show a short list whole.">
		Five names fit on the screen. Reading them takes less time than finding the next page.
	</Guideline>
	<Guideline kind="dont" name="pagination/dont-tiny" title="Paginate a tiny list.">
		Three pages of two names hide most of the list behind clicks, and Ctrl+F stops finding them.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="pagination" type="PaginationProps" types={{ previousLabel: "ReactNode", nextLabel: "ReactNode" }}>
	Other props go to the `nav`. Give either `getHref` (links) or `onPageChange` (buttons).
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the pagination itself.

<StylingHooks
	slots={["pagination", "pagination-item", "pagination-ellipsis"]}
	attributes={[
		{ attr: "aria-current", value: '"page" on the current page' },
		{ attr: "aria-disabled", value: '"true" on Previous at page 1 and Next at the last page' },
	]}
>

```css
/* square page numbers in the orders table */
.orders [data-slot="pagination-item"] {
  --cml-radius-control: 4px;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to Previous, each page number and Next, in order. The … gaps are skipped." },
		{ key: "Shift + Tab", description: "Moves back through the same controls." },
		{ key: "Enter", description: "Goes to the focused page. As buttons, Space does too." },
		{ key: "Enter on Next at the last page", description: "As buttons, does nothing and focus stays on Next: it is aria-disabled, not disabled. As links, the edge control has no href and Tab skips it." },
	]}
	notes={[
		"It is a nav landmark. Name it after what it pages through (\"Order pages\") and make the name unique when a page has two.",
		"The current page has aria-current=\"page\". Each number is named by pageLabel, \"Page 3\" by default; the … gaps are hidden from screen readers.",
		"With onPageChange, focus stays on the control that was pressed, so people can keep paging. Announce the change in a role=\"status\" message (\"Page 3 of 12\"); the updated list is right above.",
		"With getHref, each page is a new URL and a full page load; let the page's title say which page it is (\"Orders, page 3 of 12\").",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "DataTable", description: "Sorting, selection and pagination for tabular data.", href: "/docs/components/data-table" },
		{ title: "Breadcrumb", description: "Where a page sits in the site's hierarchy.", href: "/docs/components/breadcrumb" },
		{ title: "Native select", description: "The rows-per-page choice next to it.", href: "/docs/components/native-select" },
	]}
/>


# Popover (/docs/components/popover)

<ComponentMeta file="popover" primitive="Base UI" pattern="WAI-ARIA Dialog (non-modal)" />

<Playground
	name="popover/playground"
	component="Popover"
	controls={[{ prop: "modal", default: false }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose" />

## Anatomy [#anatomy]

`PopoverContent` renders in a portal, with the skin, mode and brand of the page around the trigger. It opens below the trigger, aligned to its start (change it with `side` and `align`), and flips to the other side when there is no room. The arrow is always there. Your content goes inside `popover-scroll`, so put layout (a grid, a gap) on your own wrapper or on that slot, not on `PopoverContent`.

<Anatomy
	tree={{
		slot: "popover-positioner",
		tag: "div",
		note: "in a portal",
		children: [
			{
				slot: "popover-popup",
				tag: "div",
				note: "role=dialog",
				children: [
					{ slot: "popover-arrow", tag: "div", note: "points at the trigger" },
					{
						slot: "popover-scroll",
						tag: "div",
						note: "scrolls when taller than the screen",
						children: [
							{ slot: "popover-title", tag: "h2", note: "names the dialog" },
							{ slot: "popover-description", tag: "p", note: "optional" },
							{ slot: "popover-close", tag: "button", note: "optional" },
						],
					},
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Each one starts closed: open it, then try Tab, Escape and a click outside.

<Preview name="popover/basic" compact />

<ExampleGrid>
	<Example name="popover/rename" title="A short form">
		Click Rename. `initialFocus` puts the cursor in the field, Enter saves, and focus goes back to the button while a status message confirms the new name.
	</Example>
	<Example name="popover/notifications" title="Controlled">
		With `open` and `onOpenChange` you know when it closes. Here that marks the notifications as read and announces it.
	</Example>
	<Example name="popover/a11y-icon" title="From an icon button">
		The icon button needs an `aria-label`; `PopoverTitle` names the panel. Screen readers hear that it opens a dialog and whether it is expanded.
	</Example>
	<Example name="popover/with-close" title="With a close button">
		Phones have no Escape key. A `PopoverClose` with a visible × gives everyone a way out.
	</Example>
	<Example name="popover/live-settings" title="Settings that apply at once">
		The page stays visible and usable behind a popover, so changes can show up right away, with no Apply button.
	</Example>
	<Example name="popover/trap-focus" title="Keep focus inside">
		Tab normally leaves the popover and closes it. With `modal="trap-focus"`, Tab cycles inside, so a half-typed entry isn't lost.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="popover/context-share" title="Share a document" uses="Popover · Switch · Field · Input · Button" />
	<Context name="popover/context-columns" title="Table column settings" uses="Popover · CheckboxGroup · Table" />
	<Context name="popover/context-snooze" title="Snooze a reminder" uses="Card · Popover · RadioGroup · Badge" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="popover/do-menu" title="A list of commands is a menu.">
		`Menu` gives arrow keys, type-to-select and the right roles for Edit, Duplicate and Delete.
	</Guideline>
	<Guideline kind="dont" name="popover/dont-action-list" title="A popover full of buttons.">
		Each one is a Tab stop, and screen readers hear a dialog instead of a menu.
	</Guideline>
	<Guideline kind="do" name="popover/do-tooltip" title="A tooltip for a name.">
		Hover or focus shows "Archive" at once, and it's the same text the screen reader says.
	</Guideline>
	<Guideline kind="dont" name="popover/dont-popover-label" title="A click to read a label.">
		If it only explains the button, nobody should have to open and close a panel. Popovers are for content people interact with.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="popover"
	type="PopoverProps"
	include={["open", "defaultOpen", "onOpenChange", "modal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
>
	`PopoverContent` takes `side`, `align` and the popup's props, including `initialFocus` and `finalFocus`. `PopoverTrigger` takes `openOnHover` and `delay` for a panel that also opens on hover; keep the click, so it works on touch and with a keyboard.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the popup itself.

<StylingHooks
	slots={["popover-trigger", "popover-positioner", "popover-popup", "popover-arrow", "popover-scroll", "popover-title", "popover-description", "popover-close"]}
	attributes={[
		{ attr: "data-side", value: "bottom · top · left · right" },
		{ attr: "data-align", value: "start · center · end" },
		{ attr: "data-open · data-closed", value: "on the popup" },
		{ attr: "data-starting-style · data-ending-style", value: "while it fades in and out" },
	]}
>

```css
/* a wider panel for the share popover */
.share [data-slot="popover-popup"] {
  inline-size: min(26rem, calc(100vw - 2rem));
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "On the trigger, opens the popover and moves focus to its first control, to initialFocus, or to the panel when it has no controls." },
		{ key: "Tab", description: "Moves through the controls. After the last one, focus goes to what follows the trigger and the popover closes." },
		{ key: "Shift + Tab", description: "From the first control, goes back to the trigger; the popover stays open." },
		{ key: "Escape", description: "Closes the popover and returns focus to the trigger." },
	]}
	notes={[
		"It is never taller than the space on screen: past that, the content scrolls inside and the arrow stays put. With only text inside, the scrolling box becomes a tab stop so keyboard users can scroll it.",
		"It is a non-modal dialog: the rest of the page stays reachable. A click outside closes it.",
		"The trigger has aria-haspopup=\"dialog\" and aria-expanded, so screen readers know what opens and whether it's open.",
		"PopoverTitle gives the dialog its name. Add one even when the panel is small.",
		"Results of an action inside it go in a status message: the popover closes and takes its text with it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Tooltip", description: "A short label on hover or focus, never interactive.", href: "/docs/components/tooltip" },
		{ title: "Menu", description: "A list of commands with arrow-key navigation.", href: "/docs/components/menu" },
		{ title: "Drawer", description: "A larger panel from the edge, for longer tasks.", href: "/docs/components/drawer" },
	]}
/>


# ProgressCircle (/docs/components/progress-circle)

<ComponentMeta file="data-display" primitive="SVG ring" pattern="WAI-ARIA progressbar" />

<Playground
	name="progress-circle/playground"
	component="ProgressCircle"
	controls={[
		{ prop: "tone", options: ["brand", "warning", "danger"], default: "brand" },
		{ prop: "showValue", default: true },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="ProgressCircle" />

## Anatomy [#anatomy]

A root with the progressbar role holds the ring (an SVG with a track and an arc, plus the value on top) and an optional label below. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "progress-circle",
		tag: "div",
		note: "role progressbar",
		children: [
			{
				slot: "progress-circle-ring",
				tag: "div",
				children: [
					{
						slot: "progress-circle-svg",
						tag: "svg",
						row: true,
						children: [
							{ slot: "progress-circle-track", tag: "circle" },
							{ slot: "progress-circle-indicator", tag: "circle" },
						],
					},
					{ slot: "progress-circle-value", tag: "span", note: "hidden while busy" },
				],
			},
			{ slot: "progress-circle-label", tag: "span", note: "optional" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="progress-circle/basic" compact />

<ExampleGrid>
	<Example name="progress-circle/tones" title="Stuck or failed">
		Use `tone="warning"` when the task is stuck and `tone="danger"` when it failed. Say why in the label too, so the color is not the only signal.
	</Example>
	<Example name="progress-circle/sizes" title="Sizes">
		Change `size` and `strokeWidth` together. A thin stroke on a big ring looks faint, and a thick one on a small ring crowds the number.
	</Example>
	<Example name="progress-circle/indeterminate" title="Unknown duration">
		Pass `value={null}` when you can't measure the work yet: the number hides and the arc spins (it pulses with reduced motion). Leaving `value` out is not the same, it means 0%.
	</Example>
	<Example name="progress-circle/custom-label" title="Count instead of percent">
		Set `max` to the real total and show "3/5" in `valueLabel`. `getAriaValueText` gives screen readers the words, "3 of 5 lessons", instead of "60%".
	</Example>
	<Example name="progress-circle/inline" title="Tiny ring next to text">
		Below about 40 px the number doesn't fit. Hide it with `showValue={false}`, write the value beside the ring and name the ring with `aria-label`.
	</Example>
	<Example name="progress-circle/meter" title="A measurement, not a task">
		Storage used never moves toward "done". Pass `role="meter"` so screen readers don't announce it as a task in progress.
	</Example>
	<Example name="progress-circle/interactive-upload" title="Announce when it's done">
		Click until it finishes. Screen readers don't announce every change of the ring, so a `role="status"` message says when all the photos are in.
	</Example>
</ExampleGrid>

## In context [#in-context]

Rings fit where a bar would be too wide: next to a title, in a card or in a row of goals. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="progress-circle/context-upload" title="Upload in progress" uses="Card · ProgressCircle · Button" />
	<Context name="progress-circle/context-fitness" title="Daily goals" uses="Card · ProgressCircle" />
	<Context name="progress-circle/context-course" title="Course card" uses="Card · ProgressCircle · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="progress-circle/do-accessible-label" title="Say what is running.">
		"Importing contacts" tells people what they are waiting for, and becomes the ring's accessible name.
	</Guideline>
	<Guideline kind="dont" name="progress-circle/dont-unlabeled-circle" title="A ring with just a number.">
		40% of what? Without a label, people can't tell which task it tracks, and screen readers only hear "Progress".
	</Guideline>
	<Guideline kind="do" name="progress-circle/do-tone-problem" title="Save danger for a real problem.">
		A red ring next to "Upload failed" points people to the one thing that needs them.
	</Guideline>
	<Guideline kind="dont" name="progress-circle/dont-static-danger" title="Red for a task that is just running.">
		A profile setup at 25% is normal. Red there teaches people to ignore red when something really breaks.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="ProgressCircleProps"
	include={["value", "min", "max", "size", "strokeWidth", "tone", "label", "showValue", "valueLabel", "getAriaValueText"]}
	types={{ value: "number | null" }}
>
	Native `<div>` attributes pass through, like `aria-label`, `aria-valuetext` and `role`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the ring itself.

<StylingHooks
	slots={[
		"progress-circle",
		"progress-circle-ring",
		"progress-circle-svg",
		"progress-circle-track",
		"progress-circle-indicator",
		"progress-circle-value",
		"progress-circle-label",
	]}
	prefix="progress-circle"
	attributes={[
		{ attr: "data-tone", value: "brand · warning · danger, on the root and the indicator" },
		{ attr: "data-indeterminate", value: "present when value is null" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Not focusable. It reports status; the controls around it take the focus." }]}
	notes={[
		"It renders role=\"progressbar\" with aria-valuenow, aria-valuemin and aria-valuemax. The label names it (any content, not only a string); without label or aria-label, the name is just \"Progress\", from the MessagesProvider.",
		"Screen readers hear the percentage, or valueLabel when it is a string. When it isn't, or when the visible text is short like \"3/5\", pass getAriaValueText so screen readers hear the whole phrase.",
		"With value={null}, aria-valuenow is left out, which tells assistive tech the duration is unknown.",
		"Changes are not announced. When the task ends or fails, say so in a status message (role=\"status\").",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Progress", href: "/docs/components/progress", description: "The same feedback as a full-width bar, with label and value above it." },
		{ title: "Meter", href: "/docs/components/meter", description: "A measurement in a known range, like storage used." },
		{ title: "Spinner", href: "/docs/components/spinner", description: "Busy feedback for a button or a small area, without a value." },
	]}
/>


# Progress (/docs/components/progress)

<ComponentMeta file="progress" primitive="Base UI" pattern="WAI-ARIA progressbar" />

<Playground
	name="progress/playground"
	component="Progress"
	controls={[
		{ prop: "showValue", default: true },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The skin you load styles it.

<Import names="Progress" />

## Anatomy [#anatomy]

A root with a header (label and value) and a track with the fill. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="progress"]', color: "#8be36f" },
		{ label: '[data-slot="progress-track"] · [data-slot="progress-indicator"]', color: "#ffcf7a" },
		{ label: "label · value", color: "#7cc7ff" },
	]}
>
	<span className="a-part">track</span>
	<span className="a-part">indicator</span>
	<span className="a-label">Uploading invoice-march.pdf 65%</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="progress/basic" compact />

<ExampleGrid>
	<Example name="progress/indeterminate" title="Unknown duration">
		When you can't measure the work yet, pass `value={null}`. The number disappears, a segment slides along the track (it pulses in place with reduced motion), and screen readers hear that the bar is busy, not stuck at 0%.
	</Example>
	<Example name="progress/interactive-upload" title="Stage by stage">
		Click through it. Naming the current stage in `valueLabel` tells people what is happening, not just how much is left.
	</Example>
	<Example name="progress/custom-value" title="Count instead of percent">
		Set `max` to the real total and show "16 of 20 photos". People understand items better than a percentage.
	</Example>
	<Example name="progress/steps" title="Steps in a setup flow">
		For a short wizard, `value={3}` with `max={5}` reads as "Step 3 of 5", which says how much is left.
	</Example>
	<Example name="progress/value-text" title="What screen readers hear">
		`valueLabel` only changes the visible text. Pass `getAriaValueText` too, so "1.2 of 3 GB" is read as words and not as "40 percent".
	</Example>
	<Example name="progress/upload-list" title="A list of uploads" wide>
		One bar per file, each labelled with the file name, so people can tell which one is done, which is running and which is waiting.
	</Example>
	<Example name="progress/cancel" title="With a cancel action">
		Click it. Long tasks need a way out. After canceling, say what happened in a status message and offer to try again.
	</Example>
</ExampleGrid>

## In context [#in-context]

Progress bars sit next to the task they track. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="progress/context-file-upload" title="Upload queue" uses="Card · Progress · Button" />
	<Context name="progress/context-onboarding" title="Profile setup" uses="Card · Progress · Button" />
	<Context name="progress/context-import" title="Contact import" uses="Card · Progress · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="progress/do-label" title="Say what is running.">
		"Downloading update 4.2" tells people what they are waiting for, and gives the bar its accessible name.
	</Guideline>
	<Guideline kind="dont" name="progress/dont-unlabeled" title="A bare verb and no number.">
		"Downloading" what? Without a name and a value, people can't decide whether to wait.
	</Guideline>
	<Guideline kind="do" name="progress/do-real-steps" title="No estimate? Say it's busy.">
		If you can't measure the work, use `value={null}` instead of guessing a number.
	</Guideline>
	<Guideline kind="dont" name="progress/dont-fake-progress" title="Don't invent a percentage.">
		A timer that races to 99% and then waits breaks trust. People give up on a bar they don't believe.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="progress" type="ProgressProps" include={["value", "min", "max", "getAriaValueText", "format", "locale"]}
	types={{ value: "number | null", getAriaValueText: "(formattedValue, value) => string", format: "Intl.NumberFormatOptions", locale: "Intl.LocalesArgument" }}
	describe={{ value: "How far the task has gone, between `min` and `max`. `null` means the duration is unknown.", getAriaValueText: "The text screen readers hear for the value. Defaults to the percentage." }}
>
	Other Base UI progress root props and native `<div>` attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["progress", "progress-header", "progress-value", "progress-track", "progress-indicator"]}
	attributes={[
		{ attr: "data-progressing", value: "present while the task runs" },
		{ attr: "data-complete", value: "present when value reaches max" },
		{ attr: "data-indeterminate", value: "present when value is null" },
		{ attr: "data-slot", value: '"progress" · "progress-track" · "progress-indicator"' },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Not focusable. It reports status; the controls around it take the focus." }]}
	notes={[
		"It renders role=\"progressbar\" with aria-valuenow, aria-valuemin and aria-valuemax, and the label as its accessible name.",
		"Screen readers hear the percentage by default. When the visible value is a count or a size, pass getAriaValueText so both say the same thing.",
		"With value={null}, aria-valuenow is left out, which tells assistive tech the duration is unknown.",
		"Screen readers don't announce every change. When the task ends or fails, say so in a status message (role=\"status\").",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Meter", href: "/docs/components/meter", description: "A measurement in a known range, like storage used." },
		{ title: "Spinner", href: "/docs/components/spinner", description: "Busy feedback for a button or a small area." },
		{ title: "File upload", href: "/docs/components/file-upload", description: "Pick files to send, with their progress." },
	]}
/>


# Radio group (/docs/components/radio-group)

<ComponentMeta file="radio-group" primitive="Base UI" pattern="WAI-ARIA Radio Group" />

<Playground
	name="radio-group/playground"
	component="RadioGroup"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Give the group a name with `Fieldset` and `FieldsetLegend`, and wrap each `Radio` in a `Label`.

<Import names="RadioGroup, Radio, Fieldset, FieldsetLegend, Label" />

## Anatomy [#anatomy]

A `RadioGroup` holds the value. Each `Radio` is a circle with a dot inside, named by the `Label` around it.

<Anatomy
	keys={[
		{ label: '[data-slot="radio-group"]', color: "#8be36f" },
		{ label: '[data-slot="radio"] · [data-slot="radio-indicator"]', color: "#ffcf7a" },
		{ label: '[data-slot="label"] text', color: "#7cc7ff" },
	]}
>
	<span className="a-part">radio</span>
	<span className="a-label">Pro</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="radio-group/basic" compact />

<ExampleGrid>
	<Example name="radio-group/with-description" title="With descriptions">
		When the names alone don't help people choose, add a line under each option and link it with `aria-describedby`.
	</Example>
	<Example name="radio-group/controlled" title="Controlled">
		Click an option. `value` and `onValueChange` let the rest of the screen react, here the price below.
	</Example>
	<Example name="radio-group/required" title="Required, with an error">
		Submit it empty. With no safe default, mark the group `required` and say what to do in the `FieldError`.
	</Example>
	<Example name="radio-group/disabled-option" title="A disabled option">
		Disable only the option that can't be used, and say how to unlock it. Arrow keys skip it.
	</Example>
	<Example name="radio-group/horizontal" title="In a row">
		Two or three short options can sit side by side. Longer labels read faster in a column.
	</Example>
	<Example name="radio-group/read-only" title="Read-only">
		On a review step, `readOnly` shows the choice and keeps it focusable, unlike `disabled`, which fades it out.
	</Example>
</ExampleGrid>

## In context [#in-context]

Radio groups ask one question at a time. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="radio-group/context-shipping" title="Shipping speed" uses="Card · RadioGroup · Separator · Button" />
	<Context name="radio-group/context-appearance" title="Appearance settings" uses="Card · Fieldset · RadioGroup" />
	<Context name="radio-group/context-cancel" title="Cancellation survey" uses="Card · RadioGroup · Textarea · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="radio-group/do-checkbox" title="A checkbox for a single yes.">
		People can tick it and untick it again.
	</Guideline>
	<Guideline kind="dont" name="radio-group/dont-single" title="A radio button on its own.">
		Once it is picked it can't be unpicked, so a lone radio traps people.
	</Guideline>
	<Guideline kind="do" name="radio-group/do-distinct" title="Options that don't overlap.">
		Each answer fits exactly one option.
	</Guideline>
	<Guideline kind="dont" name="radio-group/dont-overlap" title="Ranges that share an edge.">
		A team of 10 fits two options, so people guess.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="radio-group" type="RadioGroupProps" include={["value", "defaultValue", "onValueChange", "name", "required", "disabled", "readOnly"]}
	types={{ value: "any", defaultValue: "any", onValueChange: "(value, details) => void" }}
>
	`Radio` takes a required `value` (what the group reports when it is picked) and `disabled`. Native attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the group itself.

<StylingHooks
	slots={["radio", "radio-indicator", "radio-group"]}
	prefix="radio"
	attributes={[
		{ attr: "data-slot", value: '"radio-group" · "radio" · "radio-indicator"' },
		{ attr: "data-checked", value: "present on the picked radio" },
		{ attr: "data-unchecked", value: "present on the others" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-readonly", value: "present when read-only" },
		{ attr: "data-invalid", value: "present when its Field is invalid" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus into the group, to the picked radio (or the first one), and out again." },
		{ key: "Arrow keys", description: "Move to the previous or next radio and pick it." },
		{ key: "Space", description: "Picks the focused radio if it isn't picked yet." },
	]}
	notes={[
		"The whole group is one tab stop, so a long form stays quick to tab through.",
		"Give every group a name: a FieldsetLegend, or aria-labelledby pointing at a visible heading.",
		"The hit area is at least 24 × 24 px (WCAG 2.5.8) in every skin, and the label text is clickable too.",
		"Inside a Field, the error is linked to the group with aria-describedby.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Checkbox", description: "Any number of options, or a single yes.", href: "/docs/components/checkbox" },
		{ title: "Select", description: "One choice out of a long list.", href: "/docs/components/select" },
		{ title: "Toggle group", description: "One choice as pressed buttons, for toolbars.", href: "/docs/components/toggle" },
	]}
/>


# Range calendar (/docs/components/range-calendar)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Grid" />

<Playground
	name="range-calendar/playground"
	component="RangeCalendar"
	controls={[
		{ prop: "weekdayStyle", options: ["narrow", "short", "long"], default: "short" },
		{ prop: "firstDayOfWeek", options: ["sun", "mon"], default: "sun" },
		{ prop: "allowsNonContiguousRanges", default: false },
		{ prop: "readOnly", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Dates are `@internationalized/date` objects, re-exported from Camaleo.

<Import names="RangeCalendar, CalendarDate, isWeekend" />

## Anatomy [#anatomy]

The same parts as `Calendar`. The days between the start and the end get the range background.

<Anatomy
	keys={[
		{ label: '[data-slot="range-calendar"]', color: "#8be36f" },
		{ label: '[data-slot="calendar-title"] · [data-slot="calendar-nav-button"] · [data-slot="calendar-footer"]', color: "#ffcf7a" },
		{ label: '[data-slot="calendar-grid"] · [data-slot="calendar-cell"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">title</span>
	<span className="a-part">‹ ›</span>
	<span className="a-label">start · range · end</span>
	<span className="a-part">footer</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="range-calendar/basic" compact />

<ExampleGrid>
	<Example name="range-calendar/nights" title="Controlled, with a nights count">
		Click a check-in, then a check-out. `end.compare(start)` gives the nights, and the footer repeats the range in words.
	</Example>
	<Example name="range-calendar/min-max" title="Min and max">
		`minValue` and `maxValue` keep the range inside the season, and the arrows stop at its first and last month.
	</Example>
	<Example name="range-calendar/min-stay" title="Minimum stay">
		Pick a single night. Check the length in `onChange`, set `invalid` and say the rule in the footer, which is a live status.
	</Example>
	<Example name="range-calendar/booked" title="Booked nights">
		Try to cross Oct 20. By default a range can't span unavailable days, so nobody books a stay that overlaps another guest.
	</Example>
	<Example name="range-calendar/work-days" title="Across weekends">
		`allowsNonContiguousRanges` lets a range cross unavailable days. Count only the days that matter, like work days off.
	</Example>
	<Example name="range-calendar/first-day" title="Week starts on Monday">
		`firstDayOfWeek="mon"` makes a two-week sprint read as two full rows.
	</Example>
	<Example name="range-calendar/read-only" title="Read-only">
		`readOnly` shows a confirmed stay. People can still move through it with the keyboard and hear the dates.
	</Example>
</ExampleGrid>

## In context [#in-context]

Ranges drive bookings, requests and reports. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="range-calendar/context-hotel" title="Hotel stay with a price" uses="Card · RangeCalendar · Button" />
	<Context name="range-calendar/context-vacation" title="Time off request" uses="Card · Badge · RangeCalendar · Button" />
	<Context name="range-calendar/context-report" title="Report period with presets" uses="Card · ButtonGroup · RangeCalendar · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="range-calendar/do-summary" title="Sum up the range in words.">
		"5 nights" confirms the choice at a glance and is read by screen readers.
	</Guideline>
	<Guideline kind="dont" name="range-calendar/dont-no-summary" title="Only the highlight.">
		People count cells to know how long they picked, and get it wrong by one.
	</Guideline>
	<Guideline kind="do" name="range-calendar/do-block-booked" title="Mark booked days before people pick.">
		`isDateUnavailable` stops the range at the booked nights, and the footer says why.
	</Guideline>
	<Guideline kind="dont" name="range-calendar/dont-error-after" title="Reject the range after it's picked.">
		Every day looked free, so the error comes as a surprise and people start over.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="RangeCalendarProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "allowsNonContiguousRanges", "firstDayOfWeek", "focusedValue", "defaultFocusedValue", "onFocusChange", "autoFocus"]}
	types={{ value: "{ start: DateValue; end: DateValue } | null", defaultValue: "{ start: DateValue; end: DateValue } | null", onChange: "(value: { start; end }) => void", minValue: "DateValue | null", maxValue: "DateValue | null", isDateUnavailable: "(date: DateValue) => boolean", firstDayOfWeek: "\"sun\" | \"mon\" | \"tue\" | \"wed\" | \"thu\" | \"fri\" | \"sat\"", focusedValue: "DateValue | null", defaultFocusedValue: "DateValue | null", onFocusChange: "(date: CalendarDate) => void" }}
	describe={{ className: "Class names for the root element.", style: "Inline styles for the root element.", disabled: "Disables every day and the arrows, and removes the grid from the tab order.", readOnly: "Shows the range without letting people change it. Days stay focusable.", invalid: "Marks the range as invalid, for rules your app checks, like a minimum stay.", locale: "BCP 47 locale for month names, weekdays and the first day of the week, e.g. `\"pt-BR\"`. Defaults to the nearest `I18nProvider` or the browser.", weekdayStyle: "How the weekday headers are written: `\"narrow\"`, `\"short\"` (default) or `\"long\"`.", previousLabel: "Accessible name of the previous-month arrow. React Aria's localized \"Previous\" by default.", nextLabel: "Accessible name of the next-month arrow. React Aria's localized \"Next\" by default.", footer: "Content under the grid: the range in words, a nights count or a total." }}
>
	`DateRange` is exported as the type of the value. React Aria's other range calendar props pass through, such as `pageBehavior` and `createCalendar`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the calendar itself.

<StylingHooks
	slots={["range-calendar", "calendar-header", "calendar-title", "calendar-nav", "calendar-nav-button", "calendar-grid", "calendar-header-cell", "calendar-cell", "calendar-footer"]}
	prefix="calendar"
	attributes={[
		{ attr: "data-slot", value: '"range-calendar" · "calendar-header" · "calendar-grid" · "calendar-cell" · "calendar-footer"' },
		{ attr: "data-selected", value: "present on every day of the range" },
		{ attr: "data-selection-start · data-selection-end", value: "present on the first · the last day of the range" },
		{ attr: "data-today", value: "present on today's date" },
		{ attr: "data-unavailable", value: "present on days isDateUnavailable rejects" },
		{ attr: "data-disabled · data-outside-month", value: "present on days outside min/max · on days of another month" },
	]}
>

```css
/* a softer band between the two ends */
.booking [data-slot="range-calendar"] {
  --cml-calendar-range-bg: color-mix(in oklab, var(--cml-accent) 8%, transparent);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Arrow keys", description: "Move focus one day, or one week up and down. After the first pick, the range follows focus." },
		{ key: "Enter / Space", description: "Picks the start, then the end of the range." },
		{ key: "Escape", description: "Cancels a range that has a start but no end yet." },
		{ key: "Home / End", description: "Move focus to the first or last day of the month." },
		{ key: "Page Up / Page Down", description: "Move to the previous or next month. With Shift, by a year." },
	]}
	notes={[
		"The grid is labelled by aria-label plus the visible month, and the chosen range is announced when it changes.",
		"Each day is announced with its full date and whether it is selected, today or unavailable.",
		"The range is shown by the highlight and by the start and end shapes; add a text summary in the footer so it never relies on color.",
		"A range can't cross unavailable days unless you set allowsNonContiguousRanges.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Calendar", description: "Pick a single day.", href: "/docs/components/calendar" },
		{ title: "Date range picker", description: "Two date fields with this calendar in a popover.", href: "/docs/components/date-range-picker" },
		{ title: "Slider", description: "Pick a range of numbers instead.", href: "/docs/components/slider" },
	]}
/>


# Rating (/docs/components/rating)

<ComponentMeta file="rating" primitive="Base UI" pattern="WAI-ARIA Radio Group" />

<Playground
	name="rating/playground"
	component="Rating"
	controls={[
		{ prop: "readOnly", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. The skin you load draws the stars.

<Import names="Rating" />

## Anatomy [#anatomy]

Interactive, the root is a radio group with one radio per star. Read-only, the root is an image and each star is a plain shape.

<Anatomy
	keys={[
		{ label: '[data-slot="rating"]', color: "#8be36f" },
		{ label: '[data-slot="rating-item"] · [data-slot="rating-star"]', color: "#ffcf7a" },
		{ label: 'star icon: [data-slot="icon"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">★</span>
	<span className="a-part">★</span>
	<span className="a-part">★</span>
	<span className="a-label">☆</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="rating/basic" compact />

<ExampleGrid>
	<Example name="rating/read-only" title="Read-only, with the number">
		`readOnly` turns the stars into one image named by `getLabel`. Print the average and the count next to it, so everyone can compare at a glance.
	</Example>
	<Example name="rating/half" title="Half values">
		Read-only, any fraction shows as a half star, so 4.5 and 3.5 look different. Interactive ratings take whole stars only.
	</Example>
	<Example name="rating/caption" title="With a caption">
		Pick a star. Words like "Good" or "Excellent" in the caption and in each star's name tell people what the score means.
	</Example>
	<Example name="rating/required" title="Required in a review">
		Send without a star. Check the value on submit and show a `FieldError`; inside a `Field` the message is linked to the group.
	</Example>
	<Example name="rating/in-list" title="Several on one screen">
		When a list has one rating per row, give each its own `aria-label` with the item's name, or a screen reader hears "Your rating" three times.
	</Example>
	<Example name="rating/disabled" title="Disabled, with a reason">
		Say when rating opens. A row of grey stars with no explanation looks broken.
	</Example>
	<Example name="rating/size" title="Sizes">
		Set `--cml-star-size` on the rating: small for lists and cards, large when the rating is the whole task.
	</Example>
</ExampleGrid>

## In context [#in-context]

Ratings live in reviews, cards and follow-ups. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="rating/context-review" title="Product review" uses="Card · Field · Rating · Textarea · Button" />
	<Context name="rating/context-product" title="Product card" uses="Card · Badge · Rating · Button" />
	<Context name="rating/context-feedback" title="Support feedback" uses="Card · Rating · ChipGroup · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="rating/do-with-count" title="Show the number and the count.">
		"4.8 · 128 reviews" is precise, and tells people how much to trust it.
	</Guideline>
	<Guideline kind="dont" name="rating/dont-stars-only" title="Stars on their own.">
		Nobody can tell 4.6 from 4.8, and a single review looks as solid as a hundred.
	</Guideline>
	<Guideline kind="do" name="rating/do-five" title="Five stars for an opinion.">
		A short scale is quick to pick and easy to read back.
	</Guideline>
	<Guideline kind="dont" name="rating/dont-ten" title="Ten stars.">
		The difference between 6 and 7 means nothing, and the targets get small.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="rating" type="RatingProps" include={["readOnly", "disabled", "required", "name"]}
	types={{ getLabel: "(value, max) => string" }}
	describe={{ readOnly: "Shows the value as stars (halves included) in one image, e.g. an average of 4.8." }}
>
	Inside a `Field`, the label names the group and `disabled` and `name` can come from there too. The other radio-group attributes pass through.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the rating itself.

<StylingHooks
	slots={["rating", "rating-item", "rating-star"]}
	prefix="star"
	attributes={[
		{ attr: "data-slot", value: '"rating" · "rating-item" · "rating-star"' },
		{ attr: "data-filled", value: "present on the stars up to the value" },
		{ attr: "data-checked", value: "present on the picked star" },
		{ attr: "data-fill", value: "full · half · empty (read-only stars)" },
		{ attr: "data-readonly", value: "present on a read-only rating" },
		{ attr: "data-disabled", value: "present when disabled" },
	]}
>

```css
/* gold stars, only on product cards */
.product-card [data-slot="rating"] {
  --cml-star-color: var(--cml-warning);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the picked star (or the first one), and out of the rating." },
		{ key: "→ / ↓", description: "Picks the next star." },
		{ key: "← / ↑", description: "Picks the previous star." },
		{ key: "Space", description: "Picks the focused star." },
	]}
	notes={[
		"Interactive, it is a radio group: one tab stop, and each star is a radio named by getLabel, like \"4 of 5 stars\".",
		"Read-only, it is a single role=\"img\" with getLabel as its name, so screen readers hear \"Rated 4.8 out of 5\" once, not five shapes.",
		"Give the group a name: a FieldLabel inside a Field, or aria-label when it stands alone. An id goes to the first star, so an ErrorSummary link can focus it.",
		"Filled stars differ by shape and fill, not only color, and each target is at least 24 × 24 px.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Radio group", description: "One choice with a text label each.", href: "/docs/components/radio-group" },
		{ title: "Slider", description: "A score along a continuous scale.", href: "/docs/components/slider" },
		{ title: "Chip", description: "Quick tags to explain a score.", href: "/docs/components/chip" },
	]}
/>


# ScrollArea (/docs/components/scroll-area)

<ComponentMeta file="scroll-area" primitive="Base UI" pattern="Scrollable region (WCAG 2.1.1)" />

<Playground
	name="scroll-area/playground"
	component="ScrollArea"
	controls={[{ prop: "orientation", options: ["vertical", "horizontal", "both"], default: "both" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It renders on the client.

<Import names="ScrollArea" />

## Anatomy [#anatomy]

The root clips, the viewport scrolls. Give the root a height, or a max-height so it grows with its content up to that and then scrolls (a width, for horizontal scrolling): without one, the box just grows with its content. The scrollbars only appear when there is something to scroll.

<Anatomy
	tree={{
		slot: "scroll-area",
		tag: "div",
		note: "set its size",
		children: [
			{ slot: "scroll-area-viewport", tag: "div", note: "scrolls, focusable when it overflows" },
			{ slot: "scroll-area-scrollbar", tag: "div", note: "vertical · horizontal", children: [{ slot: "scroll-area-thumb", tag: "div" }] },
			{ slot: "scroll-area-corner", tag: "div", note: "orientation=both" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Click inside one and use the arrow keys, or press Tab until the box gets a focus ring.

<Preview name="scroll-area/basic" compact />

<ExampleGrid>
	<Example name="scroll-area/horizontal" title="One row, sideways">
		On a phone, a row of filters that scrolls sideways takes less room than one that wraps into four lines. The cut-off chip at the edge shows there is more.
	</Example>
	<Example name="scroll-area/code" title="Long lines">
		Logs, diffs and commands lose their shape when they wrap. Keep the lines whole and let the box scroll sideways.
	</Example>
	<Example name="scroll-area/sidebar-nav" title="A list between a title and a button">
		Only the part that grows scrolls. The title and the "New project" button stay where people expect them.
	</Example>
	<Example name="scroll-area/both" title="Both directions" wide>
		A spreadsheet scrolls both ways. Make the header row and the first column sticky so every number keeps its labels.
	</Example>
	<Example name="scroll-area/new-messages" title="New messages">
		Send a reply. The newest message scrolls into view, and `role="log"` on the list lets screen readers announce it without moving focus.
	</Example>
	<Example name="scroll-area/a11y-named" title="Named by its heading">
		When the content overflows, the viewport joins the Tab order. Give the root `role="region"` and a name with `aria-labelledby`, so people hear what they landed on.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="scroll-area/context-activity" title="Activity feed" uses="Card · ScrollArea · Avatar · Button" />
	<Context name="scroll-area/context-terms" title="Terms to accept" uses="Card · ScrollArea · Checkbox · Button" />
	<Context name="scroll-area/context-filter" title="Brand filter" uses="Fieldset · SearchInput · ScrollArea · Checkbox" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="scroll-area/do-header-outside" title="Scroll only the part that grows.">
		The title and its action stay in view while the list moves.
	</Guideline>
	<Guideline kind="dont" name="scroll-area/dont-nested" title="A scroll area inside another.">
		The wheel gets stuck in the inner box, and people lose track of which one they are scrolling. Make the inner list shorter or let the page scroll.
	</Guideline>
	<Guideline kind="do" name="scroll-area/do-peek" title="Show that there is more.">
		A row cut in half and a visible scrollbar tell people the list goes on.
	</Guideline>
	<Guideline kind="dont" name="scroll-area/dont-hidden-bar" title="Hide the scrollbar.">
		With no bar and a height that ends exactly on a row, the list looks complete. Most people will never find the last items.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="scroll-area"
	type="ScrollAreaProps"
	include={["overflowEdgeThreshold", "render"]}
	types={{ overflowEdgeThreshold: "number | { xStart, xEnd, yStart, yEnd }", render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ overflowEdgeThreshold: "How many pixels from an edge before the data-overflow-* attributes appear. Useful for fades." }}
>
	The other props (`style`, `className`, `role`, `aria-label`…) go to the root. Set its size there.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the box itself.

<StylingHooks
	slots={["scroll-area", "scroll-area-viewport", "scroll-area-scrollbar", "scroll-area-thumb", "scroll-area-corner"]}
	prefix="scrollbar"
	attributes={[
		{ attr: "data-orientation", value: "vertical · horizontal, on each scrollbar" },
		{ attr: "data-has-overflow-x · data-has-overflow-y", value: "present when the content is wider or taller" },
		{ attr: "data-overflow-y-start · data-overflow-y-end", value: "present while there is more above or below (also -x-)" },
		{ attr: "data-hovering · data-scrolling", value: "on the scrollbar, while the pointer is over the box or it scrolls" },
	]}
>

```css
/* fade the bottom edge while there is more below */
.feed [data-slot="scroll-area"][data-overflow-y-end] [data-slot="scroll-area-viewport"] {
  mask-image: linear-gradient(to bottom, black calc(100% - 2rem), transparent);
}
/* always show the scrollbars at full strength */
.feed { --cml-scrollbar-idle-opacity: 1; }
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the viewport when its content overflows. Without overflow it is skipped." },
		{ key: "↓ / ↑", description: "Scroll down or up a little." },
		{ key: "→ / ←", description: "Scroll sideways when the content is wider." },
		{ key: "Page Down / Page Up", description: "Scroll by almost a whole box." },
		{ key: "Space / Shift + Space", description: "Scroll down or up by a box, like Page Down and Page Up." },
		{ key: "Home / End", description: "Jump to the start or the end." },
	]}
	notes={[
		"Scrolling stays native: the wheel, touch, the keyboard and the browser's own find-in-page all keep working.",
		"The viewport is focusable only while something overflows, so keyboard users can always reach hidden content (axe: scrollable-region-focusable).",
		"Name it when it is a region: role=\"region\" with aria-label or aria-labelledby on the root.",
		"The scrollbars are for the pointer and are hidden from screen readers (aria-hidden). They only fade, never move, so reduced motion needs nothing extra.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Table", description: "A table that scrolls sideways on its own on small screens.", href: "/docs/components/table" },
		{ title: "Drawer", description: "A side panel whose body scrolls while the header and footer stay.", href: "/docs/components/drawer" },
		{ title: "Dialog", description: "Long content in a modal, with the actions kept in view.", href: "/docs/components/dialog" },
	]}
/>


# Select (/docs/components/select)

<ComponentMeta file="select" primitive="Base UI" pattern="WAI-ARIA Listbox (select-only combobox)" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import the parts you need; add `SelectGroup`, `SelectGroupLabel` and `SelectSeparator` for long lists. The skin you load styles the trigger and the popup.

<Import names="Select, SelectTrigger, SelectValue, SelectContent, SelectItem" />

## Anatomy [#anatomy]

`Select` holds the state; the trigger shows the value; the content is a popup rendered in a portal. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="select-trigger"]', color: "#8be36f" },
		{ label: '[data-slot="select-value"] · chevron', color: "#ffcf7a" },
		{ label: '[data-slot="select-popup"] › [data-slot="select-item"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">Brazil</span>
	<span className="a-part">⌄</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="select/basic" compact />

<ExampleGrid>
	<Example name="select/placeholder" title="With a placeholder">
		Leave out `defaultValue` when the choice is the person's to make; `SelectValue placeholder` says what to pick without pretending it is a value.
	</Example>
	<Example name="select/groups" title="Groups and separators">
		Past eight or so options, `SelectGroup` with a `SelectGroupLabel` lets people jump to the right section instead of reading every row.
	</Example>
	<Example name="select/align-trigger" title="Aligned with the trigger">
		`alignItemWithTrigger` opens the list over the trigger with the current option in place, so short lists feel like a native menu.
	</Example>
	<Example name="select/controlled" title="Controlled">
		Pick another option. With `value` and `onValueChange` the rest of the form can react, here the delivery date and price under the field.
	</Example>
	<Example name="select/multiple" title="Several values">
		`multiple` keeps the list open and returns an array; give `SelectValue` a function so the trigger reads "Mon, Wed, Fri" instead of a count.
	</Example>
	<Example name="select/disabled-items" title="Unavailable options">
		Disable an option rather than removing it, so people learn it exists, and say when it comes back.
	</Example>
	<Example name="select/validation" title="Required, with an error" wide>
		Inside a `Field`, the label names the trigger and `FieldError` is announced with it; say what to do, not just that it is wrong.
	</Example>
</ExampleGrid>

## In context [#in-context]

A select is rarely alone. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="select/context-filters" title="Filter panel" uses="Card · Field · Select · Switch · Button" />
	<Context name="select/context-address" title="Country and state" uses="Fieldset · Field · Select · Input" />
	<Context name="select/context-pagination" title="Rows per page" uses="Field · Select · IconButton · Text" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="select/do-label" title="A visible label above it.">
		The label stays put after a value is chosen, so people always know what the field is.
	</Guideline>
	<Guideline kind="dont" name="select/dont-placeholder-label" title="The placeholder as the label.">
		Once something is picked, "Country" disappears and the field has no name on screen.
	</Guideline>
	<Guideline kind="do" name="select/do-radio" title="Two or three options? Show them all.">
		Radios cost one click and nothing is hidden.
	</Guideline>
	<Guideline kind="dont" name="select/dont-two-options" title="Hiding two options in a popup.">
		It takes two clicks to see a choice that would fit on one line.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="select" type="SelectContentProps" include={["finalFocus", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement", finalFocus: "boolean | RefObject | (type) => …" }}
	describe={{ finalFocus: "Where focus goes when the popup closes. By default, back to the trigger." }}
>
	These are the props of `SelectContent`. `Select` takes Base UI's root props: `items` (a record or `{ label, value }[]`, so the trigger shows the label before the popup opens), `value`, `defaultValue`, `onValueChange`, `multiple`, `disabled`, `required`, `readOnly`, `name` and `open` / `onOpenChange`. `SelectItem` takes `value` and `disabled`; `SelectValue` takes `placeholder` or a function of the value as children.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the select itself.

<StylingHooks
	slots={["select-trigger", "select-value", "select-popup", "select-item", "select-group-label", "select-separator"]}
	prefix="select"
	attributes={[
		{ attr: "data-slot", value: '"select-trigger" · "select-value" · "select-positioner" · "select-popup" · "select-list" · "select-item" · "select-group" · "select-group-label" · "select-separator"' },
		{ attr: "data-popup-open", value: "on the trigger while the popup is open" },
		{ attr: "data-placeholder", value: "on the value while nothing is chosen" },
		{ attr: "data-highlighted", value: "on the item under the keyboard or pointer" },
		{ attr: "data-selected", value: "on the chosen item(s)" },
		{ attr: "data-disabled", value: "on a disabled trigger or item" },
		{ attr: "data-invalid", value: "on the trigger inside an invalid Field" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter / Space", description: "Opens the list on the trigger; picks the highlighted option." },
		{ key: "↓ / ↑", description: "Opens the list, then moves between options." },
		{ key: "Home / End", description: "Jumps to the first or last option." },
		{ key: "A–Z", description: "Jumps to the next option starting with that letter." },
		{ key: "Esc", description: "Closes the list and returns focus to the trigger." },
	]}
	notes={[
		"Inside a Field, FieldLabel names the trigger and FieldDescription / FieldError are read after it.",
		"The trigger reports aria-expanded and the options carry aria-selected, so screen readers announce the state.",
		"The popup is portalled but keeps the skin through PortalScope, and contrast passes WCAG 2.2 AA in all 13 skins.",
		"For very long lists or on mobile, NativeSelect gives you the platform's own picker.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Combobox", description: "A select you can type into to filter.", href: "/docs/components/combobox" },
		{ title: "NativeSelect", description: "The browser's own select, styled.", href: "/docs/components/native-select" },
		{ title: "Menu", description: "A list of actions, not a value.", href: "/docs/components/menu" },
	]}
/>


# Separator (/docs/components/separator)

<ComponentMeta file="separator" primitive="Base UI" pattern="WAI-ARIA separator" />

<Playground
	name="separator/playground"
	component="Separator"
	controls={[
		{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The skin you load styles it.

<Import names="Separator" />

## Anatomy [#anatomy]

One `<div>` with `role="separator"`: 1px tall when horizontal, 1px wide when vertical. It has a `data-slot` you can target from CSS.

<Anatomy tree={{ slot: "separator", tag: "div", note: "role=\"separator\" · data-orientation" }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="separator/basic" compact />

<ExampleGrid>
	<Example name="separator/horizontal" title="Between stacked blocks">
		The line takes the full width of its parent. Space it with the parent's `gap`, so the gap above and below stays the same.
	</Example>
	<Example name="separator/vertical" title="Between items in a row">
		With `orientation="vertical"` the line takes the height of the row. Use it for short facts that sit side by side, like file count and size.
	</Example>
	<Example name="separator/button-groups" title="Between groups of buttons">
		Split actions that do different kinds of things, like replying and deleting. For a real toolbar with arrow keys, use Toolbar and its own separator.
	</Example>
	<Example name="separator/labelled" title='With a label, like "or"'>
		Put the word between two separators with `aria-hidden`. Screen readers read "or" once, instead of "separator, or, separator".
	</Example>
	<Example name="separator/decorative" title="Only decoration">
		This short accent line adds no structure, so it gets `aria-hidden` and screen readers skip it. Keep the separator role for lines that really split content.
	</Example>
	<Example name="separator/interactive-toggle" title="Changing with the layout">
		Click Side by side. When the blocks move into a row, switch the orientation too, so the line and `aria-orientation` follow the layout.
	</Example>
</ExampleGrid>

## In context [#in-context]

Separators split menus, lists and panels into groups people can scan. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="separator/context-profile-menu" title="Account card" uses="Card · Separator · Link · Button" />
	<Context name="separator/context-feed-divider" title="Activity by day" uses="Separator" />
	<Context name="separator/context-sidebar-nav" title="Sidebar sections" uses="Separator" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="separator/do-semantic-divider" title="One line between real groups.">
		A separator says "something new starts here". Use it where the topic changes.
	</Guideline>
	<Guideline kind="dont" name="separator/dont-empty-spacing" title="Lines stacked to make space.">
		Use margin or `gap` for space. Extra lines look like a bug and screen readers announce each one.
	</Guideline>
	<Guideline kind="do" name="separator/do-vertical-flex" title="Let a vertical line take the row's height.">
		Put it straight in a flex row. It stretches with the items, and you don't need to set a height.
	</Guideline>
	<Guideline kind="dont" name="separator/dont-inline-breaks" title="A pipe character as a divider.">
		Some screen readers say "vertical bar" between the items. Use a vertical separator instead.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="separator" type="SeparatorProps">
	`Separator` also takes the attributes of a `<div>`, like `aria-hidden` and `style`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the separator itself.

<StylingHooks
	slots={["separator"]}
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "A separator doesn't take focus. Tab skips it." }]}
	notes={[
		"It renders role=\"separator\" with aria-orientation, so screen readers can announce the break between groups.",
		"Pass aria-hidden when the line is only decoration, or when a word like \"or\" already says what it means.",
		"The line is a hint, not the only signal. Groups should also make sense from their headings or labels.",
		"Inside Menu, Select or Toolbar, use their own separator part: it carries the right role for that widget.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Card", description: "A box whose sections are often split by a separator.", href: "/docs/components/card" },
		{ title: "Typography", description: "Headings that name the groups a separator splits.", href: "/docs/components/typography" },
		{ title: "Data list", description: "Label and value rows with their own dividers.", href: "/docs/components/data-list" },
	]}
/>


# Sidebar (/docs/components/sidebar)

<ComponentMeta file="sidebar" pattern="WAI-ARIA Landmarks (navigation)" />

<Playground
	name="sidebar/playground"
	component="Sidebar"
	controls={[{ prop: "collapsed", default: false }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Sidebar, SidebarHeader, SidebarNav, SidebarGroup, SidebarItem, SidebarFooter, SidebarToggle" />

## Anatomy [#anatomy]

An `<aside>` with three rows. Only the nav scrolls, so the brand and the footer stay in view. `SidebarBrand` and `SidebarContent` are other names for `SidebarHeader` and `SidebarNav`.

<Anatomy
	tree={{
		slot: "sidebar",
		tag: "aside",
		children: [
			{ slot: "sidebar-brand", tag: "div", note: "logo and name" },
			{
				slot: "sidebar-nav",
				tag: "nav",
				note: "scrolls",
				children: [
					{
						slot: "sidebar-group",
						tag: "div",
						note: "role=group",
						children: [
							{ slot: "sidebar-group-label", tag: "span" },
							{
								slot: "sidebar-item",
								tag: "a",
								row: true,
								children: [
									{ slot: "sidebar-item-icon", tag: "span" },
									{ slot: "sidebar-item-label", tag: "span" },
									{ slot: "sidebar-item-count", tag: "span", note: "optional" },
								],
							},
						],
					},
				],
			},
			{ slot: "sidebar-footer", tag: "div", note: "account, sidebar-toggle" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Press Tab to walk through the links.

<Preview name="sidebar/basic" compact />

<ExampleGrid>
	<Example name="sidebar/rail" title="Collapse to a rail">
		Press the button at the bottom. Labels hide but still name each link for screen readers, and a tooltip shows them on hover and focus.
	</Example>
	<Example name="sidebar/current" title="Current page">
		Click a link. `current` adds `aria-current="page"`, and the bar beside it shows the page without relying on color.
	</Example>
	<Example name="sidebar/router-link" title="With your router">
		Pass `render={<NextLink href="…" />}`. The router handles the click without reloading the page, and the item keeps its style. Here `current` comes from the path, so the link to this page is marked.
	</Example>
	<Example name="sidebar/counts" title="Counts that make sense when heard">
		The count is read as part of the link's name, so add the unit in `VisuallyHidden`: "Inbox 12 unread", not "Inbox 12".
	</Example>
	<Example name="sidebar/nested" title="Nested sections">
		A project with its own pages opens in place with a `Collapsible`. Its header is a button, because it only shows links and goes nowhere.
	</Example>
	<Example name="sidebar/account-menu" title="Account menu in the footer">
		The person and their settings sit at the bottom, out of the way of the pages. The menu opens upward when there is no room below.
	</Example>
	<Example name="sidebar/phone-drawer" title="On phones, in a drawer">
		The Sidebar has no phone mode of its own. Below a breakpoint, hide it and put the same links in a left `Drawer`, which traps focus and returns it to the menu button.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="sidebar/context-docs" title="Documentation site" uses="Sidebar · Collapsible · Badge" />
	<Context name="sidebar/context-admin" title="Store admin" uses="Sidebar · Meter · Button" />
	<Context name="sidebar/context-projects" title="Team workspace" uses="Sidebar · IconButton · Avatar" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="sidebar/do-groups" title="A few named groups.">
		Two or three headings let people skip to the part of the app they need.
	</Guideline>
	<Guideline kind="dont" name="sidebar/dont-flat" title="Ten links in one list.">
		Without groups, people read every link to find one, and related pages end up far apart.
	</Guideline>
	<Guideline kind="do" name="sidebar/do-short-labels" title="One or two words per link.">
		Short names fit the column and are quick to scan. The page itself can have a longer title.
	</Guideline>
	<Guideline kind="dont" name="sidebar/dont-long-labels" title="Sentences as labels.">
		Long labels get cut off, and the words that tell them apart are the ones that disappear.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="sidebar"
	type="SidebarProps"
	types={{ onCollapseChange: "(collapsed: boolean) => void" }}
>
	`SidebarItem` takes `href`, `icon`, `count` and `current`, plus `render` to use your router's link instead of the `a`. `SidebarGroup` takes `label`. `SidebarToggle` takes `collapseLabel` and `expandLabel`; pass them in the page's language (defaults "Collapse sidebar" and "Expand sidebar"). `useSidebar()` reads and sets the state from any part inside.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the sidebar itself.

<StylingHooks
	slots={["sidebar", "sidebar-brand", "sidebar-nav", "sidebar-group", "sidebar-group-label", "sidebar-item", "sidebar-item-icon", "sidebar-item-label", "sidebar-item-count", "sidebar-footer", "sidebar-toggle"]}
	prefix="sidebar"
	attributes={[
		{ attr: "data-collapsed", value: "on the sidebar, while it is a rail" },
		{ attr: "data-current · aria-current", value: "page · on the link of the page shown" },
	]}
>

```css
/* a wider sidebar and a slimmer rail */
.app [data-slot="sidebar"] {
  --cml-sidebar-width: 16rem;
  --cml-sidebar-rail-width: 3.25rem;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to the next link, section header or button, top to bottom. In the rail too: the hidden labels don't take a stop." },
		{ key: "Shift + Tab", description: "Moves to the previous one." },
		{ key: "Enter", description: "On a link, follows it. On the toggle or a section header, collapses or expands it." },
		{ key: "Space", description: "On the toggle or a section header, collapses or expands it." },
	]}
	notes={[
		"The links sit in a <nav>. Give it an aria-label, like \"Main\", so it is listed by name among the page's landmarks.",
		"Groups are role=\"group\" and take their name from the label, so a screen reader says \"Workspace, group\" when you enter one.",
		"The toggle is a button with aria-expanded and a name that says what it will do. In the rail, each link keeps its full name and only the label is hidden.",
		"The current page gets aria-current=\"page\" and a bar and a weight change, not only a color.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Drawer", description: "Holds the same links on phones, behind a menu button.", href: "/docs/components/drawer" },
		{ title: "Navigation menu", description: "Links across the top, for sites with a few sections.", href: "/docs/components/navigation-menu" },
		{ title: "Breadcrumb", description: "Shows where the current page sits, above its title.", href: "/docs/components/breadcrumb" },
	]}
/>


# Skeleton (/docs/components/skeleton)

<ComponentMeta file="display" pattern="aria-hidden" />

<Playground
	name="skeleton/playground"
	component="Skeleton"
	controls={[
		{ prop: "shape", options: ["line", "circle"], default: "line" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. The skin you load styles it.

<Import names="Skeleton" />

## Anatomy [#anatomy]

One `<span>` with a soft shimmer. You set its width and height; `shape` picks a line or a circle.

<Anatomy
	keys={[
		{ label: '[data-slot="skeleton"]', color: "#8be36f" },
		{ label: 'data-shape="line | circle"', color: "#ffcf7a" },
	]}
>
	<span className="a-part">shape</span>
	<span className="a-label">Placeholder</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="skeleton/basic" compact />

<ExampleGrid>
	<Example name="skeleton/shapes" title="Line and circle">
		`shape="circle"` for avatars and icons, the default `line` for titles and text. Size each one like the thing it stands for.
	</Example>
	<Example name="skeleton/paragraph" title="A paragraph of text">
		Vary the line widths and make the last one short. Equal bars look like a block, not like text.
	</Example>
	<Example name="skeleton/card-loading" title="From placeholder to content">
		Click it. The card keeps its header, body and footer while loading, and the button stays real and usable.
	</Example>
	<Example name="skeleton/no-shift" title="No jump when it loads">
		Click it. Each placeholder sits in a box with the line height of the text it waits for, so nothing below moves.
	</Example>
	<Example name="skeleton/list-loading" title="A list, marked busy">
		Skeletons are hidden from screen readers. Put `aria-busy="true"` and a name on the container, so people know the list is loading.
	</Example>
	<Example name="skeleton/table-loading" title="A table while it loads" wide>
		Keep the real column headers and fill only the cells. People can already read what the table will hold.
	</Example>
	<Example name="skeleton/vs-spinner" title="Skeleton or Spinner?">
		Skeleton when you know what is coming, like a profile or a list. Spinner when an action is running, like saving.
	</Example>
</ExampleGrid>

## In context [#in-context]

Skeletons stand in for whole pieces of UI. These are the loading states you can copy, in the skin you picked.

<ContextGrid>
	<Context name="skeleton/context-profile" title="Profile header" uses="Card · Skeleton" />
	<Context name="skeleton/context-feed" title="Activity post" uses="Card · Skeleton" />
	<Context name="skeleton/context-article" title="Help article" uses="Card · Badge · Skeleton" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="skeleton/do-match-shape" title="Copy the shape of the content.">
		An avatar circle and two lines of the right size: the page looks the same when the data arrives.
	</Guideline>
	<Guideline kind="dont" name="skeleton/dont-generic-blocks" title="One big gray box.">
		It says nothing about what is coming, and the page jumps when the real layout appears.
	</Guideline>
	<Guideline kind="do" name="skeleton/do-aria-busy" title="Mark the region busy.">
		Give the container a name and `aria-busy="true"`, and remove it when the content is in.
	</Guideline>
	<Guideline kind="dont" name="skeleton/dont-interactive-skeleton" title="Skeletons in place of buttons.">
		You already know the actions. Show the real buttons, disabled if they can't work yet, so people see what they will be able to do.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="SkeletonProps">
	Native `<span>` attributes pass through. Set the size with `style` or `className`.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["skeleton"]}
	attributes={[
		{ attr: "data-shape", value: "line · circle" },
		{ attr: "aria-hidden", value: '"true", always' },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Not focusable. A skeleton is only a picture of the layout." }]}
	notes={[
		"Every Skeleton has aria-hidden=\"true\", so screen readers skip it.",
		"Say that something is loading on the container: a name and aria-busy=\"true\", or a status message for longer waits.",
		"With reduced motion turned on, the shimmer stops and the placeholder stays still.",
		"Don't put a tab stop or a click handler on a skeleton; there is nothing to use yet.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Spinner", href: "/docs/components/spinner", description: "Busy feedback when an action is running." },
		{ title: "Progress", href: "/docs/components/progress", description: "How far a task has gone, like an upload." },
		{ title: "Empty state", href: "/docs/components/empty-state", description: "What to show when it loaded and there is nothing." },
	]}
/>


# Slider (/docs/components/slider)

<ComponentMeta file="slider" primitive="Base UI" pattern="WAI-ARIA Slider" />

<Playground
	name="slider/playground"
	component="Slider"
	controls={[
		{ prop: "thumbAlignment", options: ["center", "edge"], default: "center" },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. The skin you load styles the track and the thumbs.

<Import names="Slider" />

## Anatomy [#anatomy]

One component that renders the control, the track, the filled indicator and one thumb per value. Every part has a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="slider"] › [data-slot="slider-control"]', color: "#8be36f" },
		{ label: '[data-slot="slider-track"] · [data-slot="slider-indicator"]', color: "#ffcf7a" },
		{ label: '[data-slot="slider-thumb"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">━━━━━━</span>
	<span className="a-label">●</span>
	<span className="a-part">──────</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="slider/basic" compact />

<ExampleGrid>
	<Example name="slider/range" title="Range">
		Pass an array and you get one thumb per value; name each one with `getAriaLabel`, since "minimum" and "maximum" aren't visible.
	</Example>
	<Example name="slider/visible-value" title="With the value shown">
		Drag it. Show the value next to the label, and pass the same `format` and `locale` so screen readers hear "$25,000" instead of "25000".
	</Example>
	<Example name="slider/step" title="Steps">
		`step` snaps to the values that make sense; `largeStep` is what Page Up and Page Down jump by.
	</Example>
	<Example name="slider/min-gap" title="Range with a minimum gap">
		`minStepsBetweenValues` keeps the thumbs apart, here at least two hours between start and end.
	</Example>
	<Example name="slider/committed" title="Save on release">
		Drag, then let go. `onValueCommitted` fires once at the end, so you save or fetch once instead of on every pixel.
	</Example>
	<Example name="slider/in-field" title="Inside a Field">
		`FieldLabel` names the thumb and `FieldDescription` explains the scale, with no `getAriaLabel` needed.
	</Example>
	<Example name="slider/vertical" title="Vertical">
		`orientation="vertical"` fits sliders side by side, like an equalizer; `getAriaValueText` adds the unit, so screen readers say "+4 decibels".
	</Example>
	<Example name="slider/disabled" title="Disabled, with a reason">
		A locked slider still shows the current value; say what unlocks it right below.
	</Example>
</ExampleGrid>

## In context [#in-context]

Sliders sit in panels and players. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="slider/context-player" title="Audio player" uses="Card · Slider · IconButton · Text" />
	<Context name="slider/context-price" title="Price filter" uses="Card · Slider · Checkbox · Button" />
	<Context name="slider/context-display" title="Text size setting" uses="Card · Field · Slider · Switch" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="slider/do-show-value" title="Show the number when it matters.">
		People choosing a loan need to see the amount, not guess it from a position.
	</Guideline>
	<Guideline kind="dont" name="slider/dont-hide-value" title="A bare track for a precise amount.">
		Where on the bar is $25,000? Nobody can tell.
	</Guideline>
	<Guideline kind="do" name="slider/do-approximate" title="Approximate values.">
		Volume, brightness, zoom: the effect is the feedback.
	</Guideline>
	<Guideline kind="dont" name="slider/dont-exact" title="Exact values on a long scale.">
		Dragging to 1987 out of 90 years is fiddly; use a NumberField or an input.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="slider" type="SliderProps"
	include={["value", "defaultValue", "onValueChange", "onValueCommitted", "min", "max", "step", "largeStep", "minStepsBetweenValues", "format", "locale", "thumbAlignment", "thumbCollisionBehavior", "orientation", "disabled", "name"]}
	types={{ value: "number | number[]", defaultValue: "number | number[]", onValueChange: "(value, details) => void", onValueCommitted: "(value, details) => void", format: "Intl.NumberFormatOptions" }}
	describe={{ thumbAlignment: "How the thumbs line up with the ends: centered on the value (`center`) or kept inside the track (`edge`)." }}
>
	Pass an array as `value` or `defaultValue` for a range. Inside a `Field`, the label and description reach the thumbs, and `disabled` / `name` can come from there too.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the slider itself.

<StylingHooks
	slots={["slider", "slider-control", "slider-track", "slider-indicator", "slider-thumb"]}
	prefix="slider"
	attributes={[
		{ attr: "data-slot", value: '"slider" · "slider-control" · "slider-track" · "slider-indicator" · "slider-thumb"' },
		{ attr: "data-dragging", value: "present while a thumb is dragged" },
		{ attr: "data-orientation", value: '"horizontal" · "vertical"' },
		{ attr: "data-disabled", value: "present when disabled" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "→ / ↑", description: "Increases the value by one step (↑ moves a vertical slider up)." },
		{ key: "← / ↓", description: "Decreases the value by one step." },
		{ key: "Page Up / Page Down", description: "Changes the value by largeStep." },
		{ key: "Home / End", description: "Jumps to the minimum or maximum." },
		{ key: "Tab", description: "Moves between thumbs, in order." },
	]}
	notes={[
		"Each thumb is a native range input with role=\"slider\", aria-valuemin, aria-valuemax and aria-valuenow.",
		"With format and locale, aria-valuetext reads the formatted value, like \"R$ 1.200\" or \"9 hours\"; getAriaValueText adds what the number alone doesn't say, like the unit.",
		"Outside a Field, give every thumb a name with getAriaLabel.",
		"The control is at least 24 px tall in every skin, which meets the WCAG 2.2 target size.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "NumberField", description: "Type or step an exact number.", href: "/docs/components/number-field" },
		{ title: "Progress", description: "Shows a value people can't change.", href: "/docs/components/progress" },
		{ title: "Select", description: "Pick from named options instead of a scale.", href: "/docs/components/select" },
	]}
/>


# Spinner (/docs/components/spinner)

<ComponentMeta file="spinner" pattern="ARIA status" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It renders on the server.

<Import names="Spinner" />

## Anatomy [#anatomy]

A `role="status"` wrapper with the spinning ring and a visually hidden label.

<Anatomy
	keys={[
		{ label: 'role="status"', color: "#8be36f" },
		{ label: '[data-slot="spinner"]', color: "#ffcf7a" },
		{ label: "label (visually hidden)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">◌</span>
	<span className="a-label">Loading</span>
</Anatomy>

## Examples [#examples]

<Preview name="spinner/basic" compact />

<ExampleGrid>
	<Example name="spinner/sizes" title="Sizes">
		It is `1em` wide, so it follows `font-size`. Inside text it matches the line.
	</Example>
	<Example name="spinner/tone" title="Color">
		It draws in `currentColor`. Set `color` with a token so it keeps contrast in every skin.
	</Example>
	<Example name="spinner/with-text" title="With visible text">
		When the text is on screen, hide it from assistive tech (`aria-hidden`) so the status isn't read twice.
	</Example>
	<Example name="spinner/inline" title="Inside a sentence">
		Next to text it follows the line height. Say how far along it is when you know it ("3 of 12").
	</Example>
	<Example name="spinner/in-button" title="In a button">
		Don't place a spinner by hand inside a button — use `Button loading`, which keeps the width and the focus.
	</Example>
	<Example name="spinner/field" title="Checking a field" wide>
		A spinner in the field description while the value is validated on the server.
	</Example>
</ExampleGrid>

## In context [#in-context]

<ContextGrid>
	<Context name="spinner/context-table" title="Loading a list" uses="Card · Skeleton · Spinner" />
	<Context name="spinner/context-upload" title="Upload in progress" uses="Card · Spinner · Text" />
	<Context name="spinner/context-page" title="Page loading" uses="Spinner" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="spinner/do-label" title="Say what is loading.">
		"Syncing" is better than a generic "Loading" — and the label is what screen readers hear.
	</Guideline>
	<Guideline kind="dont" name="spinner/dont-long" title="A spinner for a long task you can measure.">
		If you know the percentage, show it.
	</Guideline>
	<Guideline kind="do" name="spinner/do-progress" title="Use Progress when you know how far along it is.">
		People wait better when they can see the end.
	</Guideline>
	<Guideline kind="do" name="spinner/context-table" title="Pair it with skeletons for content.">
		The skeleton shows the shape of what is coming; the spinner says it is on its way.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="spinner" type="SpinnerProps">
	Every `<span>` attribute passes through: `style`, `className`, `aria-*`.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["spinner"]}
	attributes={[
		{ attr: "data-slot", value: '"spinner" (the ring)' },
		{ attr: "role", value: '"status" (the wrapper)' },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Not focusable. It only announces its label." }]}
	notes={[
		"role=\"status\" announces the label politely, without moving focus.",
		"Under prefers-reduced-motion the animation eases down through --cml-spinner-ease.",
		"Mark the region that is loading with aria-busy=\"true\" so assistive tech waits for it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Button", description: "Has a loading state built in.", href: "/docs/components/button" },
		{ title: "Progress", description: "For tasks with a known percentage.", href: "/docs/components/progress" },
		{ title: "Skeleton", description: "Placeholders in the shape of the content.", href: "/docs/components/skeleton" },
	]}
/>


# Splitter (/docs/components/splitter)

<ComponentMeta file="splitter" pattern="WAI-ARIA Window Splitter" />

<Playground
	name="splitter/playground"
	component="Splitter"
	controls={[{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Splitter, SplitterPanel, SplitterHandle" />

## Anatomy [#anatomy]

The value is the size of the first panel, in percent; the second takes the rest. Give the splitter a height. Panels clip their content, so put a `ScrollArea` inside the ones that can grow.

<Anatomy
	tree={{
		slot: "splitter",
		tag: "div",
		note: "set its height",
		row: true,
		children: [
			{ slot: "splitter-panel", tag: "div", note: "panel=first, takes the value" },
			{ slot: "splitter-handle", tag: "div", note: "role=separator", children: [{ slot: "splitter-grip", tag: "span" }] },
			{ slot: "splitter-panel", tag: "div", note: "panel=second, the rest" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Drag a handle, or press Tab until one has a focus ring and use the arrow keys.

<Preview name="splitter/basic" compact />

<ExampleGrid>
	<Example name="splitter/mail" title="Three columns" wide>
		Put a second splitter inside the second panel. Each handle gets its own name, so people know which border they are moving.
	</Example>
	<Example name="splitter/vertical" title="Stacked">
		`orientation="vertical"` puts one panel above the other, like an editor over its terminal. ↑ and ↓ move the handle.
	</Example>
	<Example name="splitter/collapsible" title="Collapsible panel">
		Click "Hide filters", or press Enter on the handle. Both collapse the panel to 0 and bring it back at the size it had; a collapsed panel is hidden, so its controls leave the Tab order.
	</Example>
	<Example name="splitter/controlled" title="Remembered size">
		Drag the handle, then reset it. With `value` and `onValueChange`, the size is yours to save in the user's profile.
	</Example>
	<Example name="splitter/limits" title="Limits">
		`min` and `max` keep both sides usable. Home and End jump straight to them.
	</Example>
	<Example name="splitter/a11y-named" title="A name and a value in words">
		The handle is a focusable separator. Name it after what it resizes, and add `aria-valuetext` so a screen reader says "Sidebar 30% wide" instead of "30".
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context wide name="splitter/context-support" title="Support inbox" uses="Splitter · ScrollArea · Badge · Avatar · Textarea · Button" />
	<Context wide name="splitter/context-query" title="Query editor" uses="Splitter · Textarea · Button · Table" />
	<Context wide name="splitter/context-ide" title="Code editor" uses="Splitter · TreeView · ScrollArea" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="splitter/do-min" title="Sensible minimums.">
		Set `min` so the narrow side always shows whole words.
	</Guideline>
	<Guideline kind="dont" name="splitter/dont-tiny" title="Panels that shrink to nothing.">
		A 5% sidebar cuts every name off. People have to drag it open again before they can read anything.
	</Guideline>
	<Guideline kind="do" name="splitter/do-button" title="A button next to the handle.">
		Show and hide the panel with a labelled button, so people who don't drag can still reach it.
	</Guideline>
	<Guideline kind="dont" name="splitter/dont-drag-only" title="Content reachable only by dragging.">
		A panel at 0% with no button looks like it doesn't exist. Essential content needs a visible way in.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="splitter"
	type="SplitterProps"
	types={{ onValueChange: "(value: number) => void" }}
>
	`SplitterPanel` takes `panel` (`"first"` or `"second"`). `SplitterHandle` takes `aria-label` (default "Resize panel"; pass it in the page's language) and `aria-valuetext`. Other props go to the elements.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the splitter itself.

<StylingHooks
	slots={["splitter", "splitter-panel", "splitter-handle", "splitter-grip"]}
	prefix="splitter"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical, on every part" },
		{ attr: "data-panel", value: "first · second, on the panels" },
		{ attr: "data-dragging", value: "on the splitter and the handle while it is dragged" },
	]}
>

```css
/* a thin line instead of a bar, without the grip */
.editor [data-slot="splitter"] {
  --cml-splitter-handle-size: 0.375rem;
  --cml-splitter-handle-bg: transparent;
}
.editor [data-slot="splitter-grip"] { display: none; }
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus to the handle." },
		{ key: "← / →", description: "Side by side: makes the first panel narrower or wider by one step (1% by default)." },
		{ key: "↑ / ↓", description: "Stacked: makes the first panel shorter or taller by one step." },
		{ key: "Shift + arrow", description: "Moves five steps at once." },
		{ key: "Home / End", description: "Jumps to the smallest (min) or the largest (max) size." },
		{ key: "Enter", description: "Collapses the first panel to 0, or brings it back at the size it had. An arrow key on a collapsed panel opens it at min." },
	]}
	notes={[
		"The handle is role=\"separator\" with aria-valuenow, aria-valuemin (0, since Enter can collapse) and aria-valuemax in percent, and aria-controls pointing at the first panel.",
		"Name every handle after what it resizes (\"Resize sidebar\"); the default \"Resize panel\" is in English.",
		"Enter collapses the first panel, but few people know that key. When hiding a panel matters, also offer a button with aria-expanded.",
		"The panels don't stack on narrow screens by themselves. On a phone, switch to orientation=\"vertical\" or show one panel at a time.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "ScrollArea", description: "Scrolls the content inside each panel.", href: "/docs/components/scroll-area" },
		{ title: "Tree view", description: "The file or folder tree that often fills the first panel.", href: "/docs/components/tree-view" },
		{ title: "Drawer", description: "A side panel for phones, where there is no room to split.", href: "/docs/components/drawer" },
	]}
/>


# Stack (/docs/components/stack)

<ComponentMeta file="layout" pattern="CSS flexbox" />

<Playground
	name="stack/playground"
	component="Stack"
	controls={[
		{ prop: "direction", options: ["column", "row"], default: "column" },
		{ prop: "align", options: ["stretch", "flex-start", "center", "flex-end"], default: "stretch" },
		{ prop: "justify", options: ["flex-start", "center", "space-between", "flex-end"], default: "flex-start" },
		{ prop: "wrap", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It has no state, so it renders on the server.

<Import names="Stack" />

## Anatomy [#anatomy]

One flex element with `data-slot="stack"`. Stacks nest: this page header is a row whose two children are stacks of their own.

<Anatomy
	tree={{
		slot: "stack",
		tag: "header",
		note: 'direction="row" justify="space-between"',
		row: true,
		children: [
			{ slot: "stack", tag: "div", note: "gap={0}", children: [{ slot: "heading", tag: "h3" }, { slot: "text", tag: "p", note: "count" }] },
			{ slot: "stack", tag: "div", note: 'direction="row" gap={2}', row: true, children: [{ slot: "button", tag: "button" }, { slot: "button", tag: "button" }] },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="stack/basic" compact />

<ExampleGrid>
	<Example name="stack/gap-scale" title="Gap shows what belongs together" wide>
		`gap` counts steps of `--cml-space`, so the rhythm follows the skin. Small gaps join a label to its value; large gaps separate groups.
	</Example>
	<Example name="stack/toolbar-row" title="Page header row">
		`justify="space-between"` puts the title on one side and the actions on the other. With `wrap`, the actions drop below the title on a phone.
	</Example>
	<Example name="stack/wrap" title="Tags that wrap">
		A row of tags should wrap, not scroll sideways or squeeze. It is also a `ul`, so screen readers say how many topics there are.
	</Example>
	<Example name="stack/direction-toggle" title="Row or column">
		Switch it on. The same three children turn from a row into a column; only `direction` changes, so the reading order stays the same.
	</Example>
	<Example name="stack/reading-order" title="Visual order equals Tab order">
		Turn on `row-reverse` and press Tab: focus starts on the right. To put the main action at the end, place it last in the DOM and use `justify="flex-end"`.
	</Example>
	<Example name="stack/dividers" title="Rows with dividers">
		Stack has no divider prop. Put a `Separator` between children and the gap spaces it evenly above and below.
	</Example>
	<Example name="stack/as-list" title="A list that stacks">
		`as="ul"` keeps list semantics while Stack handles the spacing. Remove the bullets and the indent with `listStyle` and `padding`.
	</Example>
	<Example name="stack/responsive" title="Responsive without breakpoints">
		There are no breakpoint props. Give each child a minimum width with `flex` and turn on `wrap`: three fields in a row become one column on a phone.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="stack/context-order" title="Order summary" uses="Card · Stack · Separator · Button" />
	<Context name="stack/context-profile" title="Profile header" uses="Card · Stack · Avatar · Badge · Button" />
	<Context name="stack/context-signup" title="Sign-up form" uses="Card · Stack · Field · Input · Checkbox" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="stack/do-gap-groups" title="Tight gaps inside a group, wide gaps between groups.">
		The title and its due date read as one thing, and the action stands apart.
	</Guideline>
	<Guideline kind="dont" name="stack/dont-even-gap" title="The same gap everywhere.">
		Every line is equally far from the next, so nothing says what belongs together.
	</Guideline>
	<Guideline kind="do" name="stack/do-dom-order" title="Order the DOM the way it reads.">
		Cancel comes first and Publish last, pushed to the end with `justify="flex-end"`. Tab follows the eye.
	</Guideline>
	<Guideline kind="dont" name="stack/dont-reverse" title="row-reverse to move the main button.">
		It looks identical, but Tab now starts on the right and moves left, and screen readers read Publish before Cancel.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="StackProps"
	types={{ as: '"div" | "section" | "ul" | "form" | …', align: "CSS align-items", justify: "CSS justify-content" }}
>
	`as` takes the same tags as [Box](/docs/components/box). Every other prop goes to the element. Your `style` is merged after the custom properties, so it can override any of them.
</Props>

## Styling hooks [#styling-hooks]

Each prop becomes a custom property on the element. Leave a prop out and your stylesheet can set its property instead, for example at a breakpoint.

<StylingHooks slots={["stack"]} prefix="stack" attributes={[{ attr: "data-slot", value: '"stack"' }]}>

```css
/* the actions bar becomes a row from 40rem up */
@media (min-width: 40rem) {
  .actions[data-slot="stack"] {
    --cml-stack-direction: row;
    --cml-stack-justify: flex-end;
  }
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Stack renders no interactive element. Tab moves through its children in DOM order." }]}
	notes={[
		"Visual order must match DOM order. column-reverse and row-reverse only move the picture: Tab and screen readers still follow the DOM, so reorder the JSX instead.",
		"Wrapping keeps the DOM order too: items flow left to right, then on to the next line, which is the order people read.",
		"Space is not meaning. If items form a list, render as=\"ul\"; if a group needs a name, give it a heading.",
		"Use as for landmarks and forms (as=\"form\", as=\"nav\") so the semantics come with the layout.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Grid", description: "When items need to line up in rows and columns.", href: "/docs/components/grid" },
		{ title: "Box", description: "The same element choice with as, without the flex layout.", href: "/docs/components/box" },
		{ title: "Separator", description: "A line between the children of a stack.", href: "/docs/components/separator" },
	]}
/>


# Stat (/docs/components/stat)

<ComponentMeta file="data-display" pattern="HTML article" />

<Playground
	name="stat/playground"
	component="StatDelta"
	label="+14.2%"
	controls={[{ prop: "trend", options: ["up", "down", "neutral"], default: "up" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Stat, StatLabel, StatValue, StatHelpText, StatDelta" />

## Anatomy [#anatomy]

An `<article>` with the label, the value and a help line. The delta usually sits inside the help line, before the comparison. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "stat",
		tag: "article",
		children: [
			{ slot: "stat-label", tag: "span" },
			{ slot: "stat-value", tag: "span" },
			{ slot: "stat-help", tag: "span", children: [{ slot: "stat-delta", tag: "span", note: "arrow + change" }] },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="stat/basic" compact />

<ExampleGrid>
	<Example name="stat/trend-up" title="Going up">
		`trend="up"` adds an arrow and the success color. Always say what you compare with, like "vs. September", or the change means nothing.
	</Example>
	<Example name="stat/trend-down" title="Going down">
		`trend="down"` turns the arrow down and the color to danger. Write the change in the unit of the value: points for a rate, not a percent of a percent.
	</Example>
	<Example name="stat/sentiment" title="When down is good">
		For churn, latency or costs, a drop is good news. Add `sentiment="positive"` to keep the down arrow but use the success color.
	</Example>
	<Example name="stat/trend-neutral" title="No change">
		`neutral` (the default) shows no arrow and a muted color. Use it when the change is zero or too small to matter.
	</Example>
	<Example name="stat/with-help-text" title="Against a goal">
		The help line can compare with a goal instead of a past period. People see how far they are from it without a second number to read.
	</Example>
	<Example name="stat/custom-icon" title="Your own icon">
		Pass `icon` to match the icons of your product, or `icon={null}` to show the number alone. Give the icon `aria-hidden`, like the default arrow.
	</Example>
	<Example name="stat/spoken-context" title="Without a help line">
		In a compact stat with no help line, add the comparison with `VisuallyHidden`. Screen readers then hear "+6 since yesterday", not a bare number.
	</Example>
	<Example name="stat/interactive-metric" title="Changing the period">
		Pick another period. The toggle group keeps the choice pressed and the stat updates in place, so the label and the layout don't jump.
	</Example>
</ExampleGrid>

## In context [#in-context]

Stats usually come in a row of three or four inside a card, with one heading for the group. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="stat/context-sales" title="Store dashboard" uses="Card · Stat" wide />
	<Context name="stat/context-mrr" title="Subscription metrics" uses="Card · Stat · Badge" wide />
	<Context name="stat/context-telemetry" title="Server health" uses="Card · Stat · Badge" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="stat/do-accessible-delta" title="Write the sign in the text.">
		The arrow is hidden from screen readers and not everyone sees the color. "+14.2%" says the direction to everyone.
	</Guideline>
	<Guideline kind="dont" name="stat/dont-color-only-delta" title="Direction shown only by color.">
		Without the sign or the arrow, "14.2%" in green reads as a plain number to many people.
	</Guideline>
	<Guideline kind="do" name="stat/do-formatted-numbers" title="Format the value and give its unit.">
		Currency, thousands separators and a percent sign tell people what the number is before they read the label.
	</Guideline>
	<Guideline kind="dont" name="stat/dont-missing-units" title="Raw numbers.">
		"48250" and "14.2" leave people guessing: dollars or orders, percent or points.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="data-display" type="StatDeltaProps" include={["trend", "sentiment", "icon"]}>
	`Stat` takes the attributes of `<article>`; `StatLabel`, `StatValue` and `StatHelpText` take those of `<span>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the stat itself.

<StylingHooks
	slots={["stat", "stat-label", "stat-value", "stat-help", "stat-delta"]}
	prefix="stat"
	attributes={[
		{ attr: "data-trend", value: "up · down · neutral (on stat-delta)" },
		{ attr: "data-sentiment", value: "positive · negative · neutral (on stat-delta, sets the color)" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "A stat has no Tab stop. Tab only reaches buttons or links you put inside it." }]}
	notes={[
		"Screen readers read the parts in order: label, value, change and comparison. Keep that order in the markup.",
		"The default arrow has aria-hidden, and the color is visual only, so the sign in the text (+ or −) must say the direction.",
		"Don't put aria-label on StatDelta: it is a plain span, and most screen readers ignore the label there. Add words with VisuallyHidden.",
		"StatValue uses tabular numbers, so the digits don't shift when the value updates.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Card", description: "The container that groups a row of stats under one heading.", href: "/docs/components/card" },
		{ title: "Meter", description: "Shows a value inside a known range, like disk usage, as a bar.", href: "/docs/components/meter" },
		{ title: "Data list", description: "Label and value pairs for the details of one record.", href: "/docs/components/data-list" },
	]}
/>


# Stepper (/docs/components/stepper)

<ComponentMeta file="stepper" pattern="Ordered list with aria-current=&quot;step&quot;" />

<Playground
	name="stepper/playground"
	component="Stepper"
	controls={[{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It is a client component: each step reads its status from the stepper.

<Import names="Stepper, Step, StepIndicator, StepTitle, StepDescription, StepSeparator" />

## Anatomy [#anatomy]

A `Stepper` is an `<ol>` and each `Step` an `<li>`, so screen readers say "list, 4 items" and the position of each one. Set `activeStep` on the stepper and every step works out its status: done before it, current at it, upcoming after it. The line between steps is drawn by the step itself, or by a `StepSeparator` placed last in it; the indicator is hidden from screen readers, so the title carries the meaning. A horizontal stepper narrower than 30rem (a container query, not the viewport) hides every title but the current one.

<Anatomy
	tree={{
		slot: "stepper",
		tag: "ol",
		note: "data-orientation",
		children: [
			{
				slot: "step",
				tag: "li",
				note: "data-status · aria-current=step",
				row: true,
				children: [
					{ slot: "step-indicator", tag: "span", note: "number, ✓ or ✕, aria-hidden" },
					{ slot: "step-title", tag: "span" },
					{ slot: "step-description", tag: "span", note: "optional" },
					{ slot: "step-separator", tag: "span", note: "optional, aria-hidden" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="stepper/basic" compact />

<ExampleGrid>
	<Example name="stepper/wizard" title="Back and Continue" wide>
		Press Continue. Focus moves to the new step's heading, so a screen reader says "Step 2 of 4: Shipping" and keyboard users start at the top of the new form.
	</Example>
	<Example name="stepper/status-text" title="State in words">
		Color and a check mark are not enough. Name the list with `aria-label` and give each state a word, visible or in `VisuallyHidden`.
	</Example>
	<Example name="stepper/clickable" title="Go back to a finished step">
		Click Cart. Only steps people already reached are links; steps ahead stay plain text, because their data doesn't exist yet.
	</Example>
	<Example name="stepper/error" title="A step with an error">
		`status="error"` turns the step red with a cross and keeps `aria-current` when it is the active step. Say what went wrong in words too, because color and the icon are not announced.
	</Example>
	<Example name="stepper/separator" title="One line styled apart">
		Place a `StepSeparator` last in a step when one line needs its own look, such as a dashed line to a step that waits on someone else.
	</Example>
	<Example name="stepper/vertical" title="Vertical, with descriptions">
		A column has room for a line under each step. Use it in a sidebar or for a setup checklist people come back to.
	</Example>
	<Example name="stepper/optional" title="Optional step">
		Mark it with a badge, not just lighter text, so people know they can move on without it.
	</Example>
	<Example name="stepper/compact" title="Compact on phones">
		Below 30rem of width, a horizontal stepper keeps only the current title on screen; the others stay in the list for screen readers. Add "Step 2 of 4" above it so people still see how long the flow is.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="stepper/context-checkout" title="Checkout" uses="Card · Stepper · Field · Input · Button" />
	<Context name="stepper/context-onboarding" title="Store setup" uses="Card · Badge · Stepper · Field · Button" />
	<Context name="stepper/context-tracking" title="Order tracking" uses="Card · Badge · Stepper · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="stepper/do-short" title="Three to five steps, one or two words each.">
		People read the whole flow at a glance and know how far they are from the end.
	</Guideline>
	<Guideline kind="dont" name="stepper/dont-long" title="Sentences for labels.">
		They don't fit side by side, so the stepper hides all but the current one and people can't see what's ahead. Put the details in each step's heading.
	</Guideline>
	<Guideline kind="do" name="stepper/do-tabs" title="Tabs for sections in any order.">
		Settings pages have no first or last section, and nothing is ever "done".
	</Guideline>
	<Guideline kind="dont" name="stepper/dont-tabs" title="A stepper for free navigation.">
		Numbers and check marks promise an order and an end that don't exist, and the steps can't be clicked.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="stepper" type="StepperProps" include={["aria-label"]} types={{ "aria-label": "string" }} describe={{ "aria-label": "Names the list, for example \"Checkout progress\"." }}>
	`Step` takes `status` (`"completed" · "current" · "upcoming" · "error"`), or the shorthands `completed` and `current`; without them, the status comes from `activeStep`, and is `"upcoming"` when there is none. `StepIndicator` takes its step's status, or its own `status`; with `"completed"` it shows a check mark and with `"error"` a cross instead of its children. The rest are the native props of `<ol>`, `<li>` and `<span>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the stepper itself.

<StylingHooks
	slots={["stepper", "step", "step-indicator", "step-title", "step-description", "step-separator"]}
	prefix="step"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical (on the stepper)" },
		{ attr: "data-status", value: "completed · current · upcoming · error (on the step and the indicator)" },
		{ attr: "aria-current", value: '"step" on the current step' },
	]}
>

```css
/* square indicators and a thicker line in the checkout */
.checkout [data-slot="stepper"] {
  --cml-step-indicator-radius: 6px;
  --cml-stepper-line: 3px solid var(--cml-border-control);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Skips the stepper unless a step holds a link or a button; then it moves to it, in order." },
		{ key: "Enter", description: "On a step link, goes back to that step." },
	]}
	notes={[
		"It is an <ol>: screen readers announce the number of steps and the position of each one. Name it with aria-label.",
		"The current step has aria-current=\"step\". Completed and upcoming steps are not announced by color or the check mark, which is aria-hidden: add a word such as \"done\" in VisuallyHidden. The same goes for an error: say what went wrong in the title or a StepDescription.",
		"When the step changes, move focus to the new step's heading, and put \"Step 2 of 4\" in it, so screen readers and keyboard users start in the right place.",
		"Make only reached steps clickable. Steps ahead stay text, so people never land on a form whose earlier answers are missing.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Timeline", description: "A history of what happened, with dates, rather than a flow to finish.", href: "/docs/components/timeline" },
		{ title: "Progress", description: "A bar for progress that has no named steps.", href: "/docs/components/progress" },
		{ title: "Error summary", description: "Lists what to fix before the next step.", href: "/docs/components/error-summary" },
	]}
/>


# StyleProvider (/docs/components/style-provider)

<ComponentMeta file="style-provider" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)) and import the stylesheet of every skin you render, islands included. A skin without its CSS falls back to the defaults.

<Import names="StyleProvider, useStyleScope, PortalScope, Portal, STYLE_NAMES" />

For the whole page, a Server Component can spread `styleScopeProps({ styleName, mode, brand })` on `<html>` instead: same attributes, no client code. See [Installation](/docs/installation) for the CSS and the fonts.

## Anatomy [#anatomy]

`StyleProvider` renders a `<div>` with `data-style`, `data-mode` and the brand tokens as inline variables. Every `[data-style]` element redeclares all the tokens and paints its own background, text color and font, so a nested island starts clean instead of inheriting its parent's skin. The mode and the brand, on the other hand, flow down until an island sets its own.

<Anatomy
	tree={{
		slot: "[data-style] [data-mode]",
		tag: "div",
		note: "StyleProvider · brand tokens inline",
		children: [
			{ slot: "your app", note: "wears the skin" },
			{
				slot: "[data-style]",
				tag: "div",
				note: "nested StyleProvider: an island",
				children: [{ slot: "your section" }],
			},
		],
	}}
/>

Popups (Menu, Select, Popover, Dialog, Drawer…) render in `<body>`, outside every provider. They wrap their content in a `portal-scope` element that copies the scope of the provider they were opened from.

<Anatomy
	tree={{
		slot: "portal-scope",
		tag: "div",
		note: "in <body> · display: contents · same data-style, data-mode, brand",
		children: [{ slot: "menu-positioner · select-positioner · dialog-popup…" }],
	}}
/>

## Examples [#examples]

Every preview already sits inside a StyleProvider: the one the bar above controls. These examples nest a second one, so you can see an island next to the page around it.

<Preview name="style-provider/basic" compact />

<ExampleGrid>
	<Example name="style-provider/skins-gallery" title="All skins side by side" wide>
		Click a tile. A theme picker shows each choice in its own island, so people see the skin before they commit to it. Mode and brand still come from the page.
	</Example>
	<Example name="style-provider/runtime-switch" title="Switch skin at runtime">
		Pick a skin and flip the switch. New props only swap attributes, so nothing remounts and the state inside survives.
	</Example>
	<Example name="style-provider/tenant-brand" title="A brand per tenant">
		Set only `brand` to give each customer their color. Pass the page's skin from `useStyleScope()`, because `styleName` doesn't inherit.
	</Example>
	<Example name="style-provider/portal-menu" title="Popups keep the island's style">
		Open the menu. It renders in `<body>`, yet it keeps the island's skin, mode and brand, because every popup re-applies the scope it was opened from.
	</Example>
	<Example name="style-provider/custom-portal" title="Your own portal">
		Click Pay. `Portal` moves content to another node and keeps the island's style; use it, or wrap your own `createPortal` in `PortalScope`.
	</Example>
	<Example name="style-provider/read-scope" title="Read the current scope">
		`useStyleScope()` returns the nearest provider's props. Use it to pass the skin on, or to color a chart or canvas that can't read CSS.
	</Example>
	<Example name="style-provider/a11y-contrast" title="Hard brand colors stay readable">
		Yellow, pale lime, near black: the brand scale picks black or white text for every step, so labels keep at least 4.5:1 in any skin and mode.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, with an island inside the skin you picked.

<ContextGrid>
	<Context name="style-provider/context-appearance" title="Appearance settings" uses="StyleProvider · Select · RadioGroup · Card · Switch" />
	<Context name="style-provider/context-campaign" title="Campaign section" uses="StyleProvider · Heading · Stat · Button" />
	<Context name="style-provider/context-booking" title="Embedded booking widget" uses="StyleProvider · useStyleScope · Card · Select · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="style-provider/do-section-island" title="An island for a whole section.">
		A news panel, a campaign or an embedded widget can have its own identity. The rest of the page keeps one skin.
	</Guideline>
	<Guideline kind="dont" name="style-provider/dont-mixed-form" title="Different skins inside one form.">
		Three fields in three skins look broken, and people stop trusting the form.
	</Guideline>
	<Guideline kind="do" name="style-provider/do-keep-skin" title="Pass the skin on when you change the mode.">
		`styleName={useStyleScope()?.["data-style"]}` with `mode="dark"` gives a dark card in the page's own skin.
	</Guideline>
	<Guideline kind="dont" name="style-provider/dont-drop-skin" title="Only mode on a nested provider.">
		Without `styleName` the island falls back to `minimal`. Switch the skin in the bar above: this card never changes.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="style-provider"
	type="StyleProviderProps"
	types={{ styleName: "StyleName (13 skins)" }}
>
	All `<div>` props pass through; `style` merges with the brand variables. `useStyleScope()` returns `{ "data-style", "data-mode"?, style? }` or `null` outside a provider. `PortalScope` takes only `children`. `Portal` takes `children` and `container` (default `document.body`). `styleScopeProps(options)` returns the same attributes for a Server Component.
</Props>

## Styling hooks [#styling-hooks]

The provider is the source of the tokens every component reads. Target its attributes to change a skin, or set a token on an island to change only that section.

<StylingHooks
	slots={["portal-scope"]}
	prefix="brand"
	attributes={[
		{ attr: "data-style", value: "minimal · neumorphism · retro-pixel · editorial · neubrutalism · retro · glass · swiss · progressive · clay · material · cupertino · y2k" },
		{ attr: "data-mode", value: "light · dark · system (absent: inherited)" },
		{ attr: "style", value: "--cml-brand and --cml-brand-50 … -950, each with -fg and -hover" },
		{ attr: "data-slot", value: '"portal-scope" on the popup wrapper in <body>' },
	]}
>

```css
/* rounder controls, only in the glass skin */
[data-style="glass"] {
  --cml-radius-control: 14px;
}

/* a quieter surface for one island */
.help-center[data-style] {
  --cml-surface: light-dark(var(--cml-brand-50), var(--cml-brand-950));
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "The provider isn't interactive and takes no focus. Keyboard behavior comes from the components inside it." }]}
	notes={[
		"Without mode, the root follows prefers-color-scheme through CSS alone (color-scheme and light-dark()), so there is no flash and no script before hydration.",
		"Text, focus rings and control borders pass WCAG 2.2 AA in all 13 skins, light and dark, with any brand color. The library tests this in CI.",
		"Forced colors (Windows high contrast) replace the skin: components keep a transparent border and an outline for focus, so they stay visible.",
		"Reduced motion calms every skin's transitions, and reduced transparency makes glass opaque. Both are read from the system, per island too.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "DirectionProvider", description: "Right-to-left layouts and arrow keys.", href: "/docs/components/direction-provider" },
		{ title: "Menu", description: "A popup that keeps the scope it opened from.", href: "/docs/components/menu" },
		{ title: "Dialog", description: "Portaled content that re-applies the island's style.", href: "/docs/components/dialog" },
	]}
/>


# Switch (/docs/components/switch)

<ComponentMeta file="switch" primitive="Base UI" pattern="WAI-ARIA Switch" />

<Playground
	name="switch/playground"
	component="Switch"
	controls={[
		{ prop: "defaultChecked", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. Wrap the switch in a `Label` that names the setting.

<Import names="Switch, Label" />

## Anatomy [#anatomy]

A track with a thumb that slides to the end when it is on. Both parts have a `data-slot` you can target from CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="switch"]', color: "#8be36f" },
		{ label: '[data-slot="switch-thumb"]', color: "#ffcf7a" },
		{ label: '[data-slot="label"] text', color: "#7cc7ff" },
	]}
>
	<span className="a-part">thumb</span>
	<span className="a-label">Auto-save drafts</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="switch/basic" compact />

<ExampleGrid>
	<Example name="switch/immediate" title="Applies right away">
		Click it. A switch takes effect the moment it moves, so confirm what changed in a status line instead of a Save button.
	</Example>
	<Example name="switch/with-description" title="With a description">
		Put what the setting does below the label and link it with `aria-describedby`, so the name stays short.
	</Example>
	<Example name="switch/list" title="A list of settings">
		Related switches go in a `Fieldset` with a legend that reads as the start of each label.
	</Example>
	<Example name="switch/saving" title="Saving to the server">
		Click it. When the change takes a moment, keep the switch focused with `readOnly` and announce "Saving…" and the result.
	</Example>
	<Example name="switch/dependent" title="Dependent settings">
		Turn the first one off. Child settings are disabled, not hidden, so people still see what they would get back.
	</Example>
	<Example name="switch/disabled" title="Disabled, with a reason">
		Say why it can't be turned on and link the reason with `aria-describedby`.
	</Example>
</ExampleGrid>

## In context [#in-context]

Switches belong to settings screens. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="switch/context-notifications" title="Notification settings" uses="Card · Switch · Separator" />
	<Context name="switch/context-flags" title="Feature previews" uses="Card · Switch · Badge" />
	<Context name="switch/context-pricing" title="Yearly billing" uses="Card · Switch · Badge · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="switch/do-instant" title="A switch for a change that applies now.">
		Dark mode turns on as soon as it moves.
	</Guideline>
	<Guideline kind="dont" name="switch/dont-submit" title="A switch that waits for Save.">
		It looks done but isn't. In a form you submit, use a `Checkbox`.
	</Guideline>
	<Guideline kind="do" name="switch/do-setting" title="Name the setting.">
		The switch itself shows on or off; screen readers announce it from `aria-checked`.
	</Guideline>
	<Guideline kind="dont" name="switch/dont-state" title="A label that says the state.">
		"Enabled" changes on every click and never says what is enabled.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="switch" type="SwitchProps" include={["checked", "defaultChecked", "onCheckedChange", "name", "value", "required", "disabled", "readOnly"]}
	types={{ onCheckedChange: "(checked: boolean, details) => void" }}
>
	Native attributes pass through to the track, a `<span role="switch">` backed by a hidden input for forms.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the switch itself.

<StylingHooks
	slots={["switch", "switch-thumb"]}
	prefix="switch"
	attributes={[
		{ attr: "data-slot", value: '"switch" · "switch-thumb"' },
		{ attr: "data-checked", value: "present when on" },
		{ attr: "data-unchecked", value: "present when off" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-readonly", value: "present when read-only" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Space", description: "Turns the focused switch on or off." },
		{ key: "Enter", description: "Turns the focused switch on or off." },
		{ key: "Tab", description: "Moves to the next switch; each one is its own tab stop." },
	]}
	notes={[
		"It has role=\"switch\" and aria-checked, so screen readers say \"on\" or \"off\", not \"checked\".",
		"Clicking the label text flips it too, which gives a much bigger target than the track.",
		"When the effect isn't visible on screen, confirm it in a role=\"status\" message.",
		"A disabled switch keeps showing on or off, so people can still read the setting.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Checkbox", description: "For choices that apply when the form is sent.", href: "/docs/components/checkbox" },
		{ title: "Toggle", description: "A pressed button for formatting and view options.", href: "/docs/components/toggle" },
		{ title: "Radio group", description: "One choice out of a few.", href: "/docs/components/radio-group" },
	]}
/>


# Table (/docs/components/table)

<ComponentMeta file="display" pattern="WAI-ARIA table" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Table, TableCaption, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell" />

## Anatomy [#anatomy]

A native `<table>` inside a container that scrolls sideways when the table is too wide. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "table-container",
		tag: "div",
		note: "scrolls when wide",
		children: [
			{
				slot: "table",
				tag: "table",
				children: [
					{ slot: "table-caption", tag: "caption", note: "optional" },
					{ slot: "table-header", tag: "thead", children: [{ slot: "table-row", tag: "tr", row: true, children: [{ slot: "table-head", tag: "th" }, { slot: "table-head", tag: "th" }] }] },
					{ slot: "table-body", tag: "tbody", children: [{ slot: "table-row", tag: "tr", row: true, children: [{ slot: "table-cell", tag: "td" }, { slot: "table-cell", tag: "td" }] }] },
					{ slot: "table-footer", tag: "tfoot", note: "optional, totals" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="table/basic" compact />

<ExampleGrid>
	<Example name="table/with-caption" title="With a caption">
		A `TableCaption` names the table. Screen readers read it before the rows, and it also names the scroll area when the table gets too wide.
	</Example>
	<Example name="table/align" title="Numbers on the right">
		Pass `align="end"` to the header and the cells of number columns. Digits get the same width, so people can compare values at a glance.
	</Example>
	<Example name="table/totals" title="Totals row">
		Put the total in a `TableFooter`, below a stronger line. It stays apart from the data rows, so sorting or adding rows never moves it.
	</Example>
	<Example name="table/status" title="Status in a column">
		A badge per row is easier to scan than a sentence. Keep the words short and use the same ones in every row.
	</Example>
	<Example name="table/empty" title="No rows yet">
		Keep the headers and fill the body with one row that spans every column. Say why it is empty and give the next step.
	</Example>
	<Example name="table/interactive-sort" title="Sortable column">
		Click Revenue. The button flips the order, and `aria-sort` on the header tells screen readers which way the rows are sorted.
	</Example>
	<Example name="table/wide" title="Wide table on a phone" wide>
		On a narrow screen this table scrolls sideways. Only then the container becomes a named scroll area with one Tab stop, so keyboard users can scroll it with the arrow keys.
	</Example>
</ExampleGrid>

## In context [#in-context]

Tables usually sit in a card or a page section, with actions in the last column. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="table/context-invoices" title="Invoices with downloads" uses="Table · Badge · Button" wide />
	<Context name="table/context-users" title="Team members" uses="Table · Avatar · Badge" wide />
	<Context name="table/context-inventory" title="Stock list" uses="Table" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="table/do-tabular-nums" title="Align numbers to the right.">
		Units line up with units, so the biggest value stands out without reading every row.
	</Guideline>
	<Guideline kind="dont" name="table/dont-left-align-numbers" title="Numbers aligned to the left.">
		Decimals end up in different places, and people have to read each value to compare.
	</Guideline>
	<Guideline kind="do" name="table/do-caption" title="Name every table.">
		Use a `TableCaption`, or `aria-label` when the title is already on the page. People hear what the data is before the first row.
	</Guideline>
	<Guideline kind="dont" name="table/dont-unlabeled-table" title='Headers like "Column A".'>
		Screen readers read the header with each cell. A vague header makes every cell vague.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="TableProps" />

<Props file="display" type="TableCellProps">
	`TableHead` and `TableCell` take `align`. Every part also takes the attributes of its HTML element, like `colSpan` and `aria-sort`. `TableCaption` (a `<caption>`, first inside `Table`) and `TableFooter` (a `<tfoot>`) take the attributes of their elements.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the table itself.

<StylingHooks
	slots={["table-container", "table", "table-caption", "table-header", "table-body", "table-footer", "table-row", "table-head", "table-cell"]}
	attributes={[
		{ attr: "data-align", value: "start · end" },
		{ attr: "role", value: "region on table-container, only while it overflows" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves to buttons and links inside cells. When the table is too wide, the scroll area is one extra stop." },
		{ key: "← / →", description: "Scroll a wide table sideways while its scroll area has focus." },
	]}
	notes={[
		"TableHead adds scope=\"col\", so screen readers read the column header with each cell.",
		"A table that doesn't fit becomes a scroll area (role=\"region\") named by the caption or scrollLabel. A table that fits adds no Tab stop.",
		"Name every table with a TableCaption, or with aria-label when a heading already says what it is.",
		"Icon buttons in a row need a name that includes the row, like \"Download INV-4029\", not just \"Download\".",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Data table", description: "Sorting, filtering, selection and pages, for large sets of data.", href: "/docs/components/data-table" },
		{ title: "Data list", description: "Label and value pairs for the details of one record.", href: "/docs/components/data-list" },
		{ title: "Empty state", description: "A full message for a page or section that has nothing to show yet.", href: "/docs/components/empty-state" },
	]}
/>


# Tabs (/docs/components/tabs)

<ComponentMeta file="tabs" primitive="Base UI" pattern="WAI-ARIA Tabs" />

<Playground
	name="tabs/playground"
	component="Tabs"
	controls={[{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Tabs, TabsList, Tab, TabsPanel" />

## Anatomy [#anatomy]

A `Tab` and a `TabsPanel` with the same `value` belong together. The list is one stop in the Tab order; the arrow keys move between its tabs.

<Anatomy
	tree={{
		slot: "tabs",
		tag: "div",
		children: [
			{
				slot: "tabs-list",
				tag: "div",
				note: "role=tablist, scrolls when the tabs don't fit",
				row: true,
				children: [
					{ slot: "tab", tag: "button", note: "role=tab" },
					{ slot: "tab", tag: "button" },
					{ slot: "tab", tag: "button" },
				],
			},
			{ slot: "tabs-panel", tag: "div", note: "role=tabpanel, only the active one" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Click a tab, then try the arrow keys.

<Preview name="tabs/basic" compact />

<ExampleGrid>
	<Example name="tabs/vertical" title="Vertical">
		With `orientation="vertical"` the list stands beside the panel and ↑ ↓ move between tabs. It suits settings with more sections than fit in a row.
	</Example>
	<Example name="tabs/counts" title="With icons and counts">
		A count tells people where the work is before they click. Keep it short: the number becomes part of the tab's name.
	</Example>
	<Example name="tabs/overflow" title="Many tabs">
		When the tabs don't fit, the list scrolls sideways and keeps the active tab in view. Past eight or so, a sidebar or a select is easier to scan.
	</Example>
	<Example name="tabs/controlled" title="In the URL">
		Click a tab and watch the address. With `value` and `onValueChange` you can keep the tab in the URL, so a link or a reload opens the same view.
	</Example>
	<Example name="tabs/lazy" title="Load on first open">
		Open Activity. A hidden panel isn't rendered, so you can fetch its data the first time it opens and show a skeleton meanwhile.
	</Example>
	<Example name="tabs/activate-on-focus" title="Follow focus">
		By default the arrow keys only move focus and Enter or Space opens the tab. Add `activateOnFocus` when panels show instantly, as these numbers do.
	</Example>
	<Example name="tabs/disabled-reason" title="Disabled, with a reason">
		The arrow keys still reach a disabled tab but can't open it. Say why it's off and when it opens, linked with `aria-describedby` so it's read on focus.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="tabs/context-product" title="Product details" uses="Card · Tabs · DataList · Rating" />
	<Context name="tabs/context-order" title="Order page" uses="Card · Badge · Tabs · Timeline" />
	<Context name="tabs/context-member" title="Team member" uses="Card · Avatar · Tabs · Checkbox · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="tabs/do-views" title="Views of one thing.">
		Summary, orders and notes all describe the same customer, and people can read them in any order.
	</Guideline>
	<Guideline kind="dont" name="tabs/dont-steps" title="Steps of a task.">
		A checkout has an order and a next step. Tabs let people skip ahead and hide how far they've come; use a stepper.
	</Guideline>
	<Guideline kind="do" name="tabs/do-links" title="Links for pages.">
		Moving to another page is navigation: links with `aria-current="page"` keep the back button, new tabs and shared URLs working.
	</Guideline>
	<Guideline kind="dont" name="tabs/dont-page-nav" title="Tabs as site navigation.">
		Screen readers announce a tab list, so people expect the content to change in place, not the whole page.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="tabs"
	type="TabsProps"
	include={["value", "defaultValue", "onValueChange", "orientation"]}
	types={{ onValueChange: "(value, eventDetails) => void" }}
>
	`Tab` and `TabsPanel` take a `value` that pairs them. `Tab` also takes `disabled`.
</Props>

`TabsList` decides how the keyboard behaves:

<Props file="tabs" type="TabsListProps" include={["activateOnFocus", "loopFocus"]} />

`TabsPanel` can stay in the page while hidden:

<Props file="tabs" type="TabsPanelProps" include={["keepMounted"]} />

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the list itself.

<StylingHooks
	slots={["tabs", "tabs-list", "tab", "tabs-panel"]}
	prefix="tab"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical" },
		{ attr: "data-active", value: "on the active tab" },
		{ attr: "data-disabled", value: "on a disabled tab" },
		{ attr: "data-activation-direction", value: "left · right · up · down, which way the selection moved" },
	]}
>

```css
/* pill tabs on a tinted track, only in this card */
.billing [data-slot="tabs-list"] {
  --cml-tabs-list-bg: var(--cml-surface-sunken);
  --cml-tabs-list-radius: var(--cml-radius-surface);
  --cml-tab-radius: var(--cml-radius-surface);
  --cml-tab-active-bg: var(--cml-surface-raised);
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves focus into the list, to the active tab. Pressed again, it moves to the panel." },
		{ key: "← / →", description: "Move focus to the previous or next tab, wrapping at the ends. In a vertical list, ↑ and ↓." },
		{ key: "Home / End", description: "Move focus to the first or last tab." },
		{ key: "Enter / Space", description: "Opens the focused tab. With activateOnFocus, the tab opens as soon as it gets focus." },
	]}
	notes={[
		"Each tab has role=tab and aria-selected; each panel has role=tabpanel and is named by its tab through aria-labelledby.",
		"Name the list with aria-label or aria-labelledby, so people know which set of tabs they are in.",
		"The panel can take focus, so keyboard users reach its text even when it has no links or fields.",
		"A disabled tab keeps focus with aria-disabled, so people hear it exists; Enter and Space don't open it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Accordion", description: "Sections that open in place, more than one at a time.", href: "/docs/components/accordion" },
		{ title: "Toggle", description: "A toggle group switches a setting, not a view.", href: "/docs/components/toggle" },
		{ title: "Stepper", description: "For a task done in steps, in order.", href: "/docs/components/stepper" },
	]}
/>


# TagsInput (/docs/components/tags-input)

<ComponentMeta file="tags-input" primitive="Base UI" pattern="WAI-ARIA Combobox" />

<Playground
	name="tags-input/playground"
	component="TagsInput"
	controls={[
		{ prop: "allowCustom", default: true },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. Put it in a `Field` so the label names the input.

<Import names="TagsInput, Field, FieldLabel, FieldDescription" />

## Anatomy [#anatomy]

Chips and a text input share one box. Each chip has its own remove button, and suggestions open in a popup below.

<Anatomy
	keys={[
		{ label: '[data-slot="tags-input"]', color: "#8be36f" },
		{ label: '[data-slot="tag"] · [data-slot="tag-remove"]', color: "#ffcf7a" },
		{ label: '[data-slot="tags-input-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">design systems ✕</span>
	<span className="a-part">accessibility ✕</span>
	<span className="a-label">Add a topic</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="tags-input/basic" compact />

<ExampleGrid>
	<Example name="tags-input/suggestions" title="Pick from a list">
		Type "py". Without `allowCustom` only `suggestions` can be added, so every profile uses the same names and search finds them.
	</Example>
	<Example name="tags-input/custom" title="Suggestions and new tags">
		Type a label that isn't listed and press Enter. `emptyText` tells people that Enter creates it, so they don't wait for a match.
	</Example>
	<Example name="tags-input/limit" title="Limit and duplicates">
		Add "React" again, or a sixth skill. A repeated tag stays in the input without calling `onValueChange`, so catch it in `onKeyDown`; refuse the limit in `onValueChange` and say why in `FieldError`.
	</Example>
	<Example name="tags-input/paste" title="Paste a list">
		Paste "joao@acme.com, lia@acme.com". An `onPaste` handler splits on commas and line breaks, so a column copied from a spreadsheet becomes one chip per address.
	</Example>
	<Example name="tags-input/keyboard" title="Remove with the keyboard">
		Focus the input and press Backspace, or ← and Delete. Each remove button is named after its tag through `removeLabel`, in the page's language.
	</Example>
	<Example name="tags-input/form" title="In a form">
		Click save. With `name`, every tag is submitted as its own value, so `formData.getAll("labels")` returns the list.
	</Example>
	<Example name="tags-input/disabled" title="Disabled, with a reason">
		`disabled` locks the chips and the input. Say in the description why and until when, or people will think it's broken.
	</Example>
</ExampleGrid>

## In context [#in-context]

Tags live next to other fields. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="tags-input/context-invite" title="Invite people by email" uses="Card · Field · TagsInput · NativeSelect · Button" />
	<Context name="tags-input/context-article" title="Article tags" uses="Card · Field · Input · TagsInput · Switch · Button" />
	<Context name="tags-input/context-filters" title="Job search filters" uses="Fieldset · Field · TagsInput · Checkbox · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="tags-input/do-vocabulary" title="One spelling per tag.">
		Suggest the tags that exist, so filters and reports count them together.
	</Guideline>
	<Guideline kind="dont" name="tags-input/dont-variants" title="Free text with no suggestions.">
		People type the same tag three ways, and a filter for "bug" misses two of them.
	</Guideline>
	<Guideline kind="do" name="tags-input/do-short" title="One or two words.">
		Short tags fit in a row and scan at a glance.
	</Guideline>
	<Guideline kind="dont" name="tags-input/dont-sentences" title="Sentences as tags.">
		They fill the row, nobody can filter by them, and they belong in a comment.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="tags-input"
	type="TagsInputProps"
	include={["disabled"]}
	types={{ removeLabel: "(tag: string) => string" }}
>
	Other `<input>` attributes like `placeholder`, `type`, `onKeyDown` and `onPaste` go to the inline input.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the field itself.

<StylingHooks
	slots={["tags-input", "tag", "tag-remove", "tags-input-input", "combobox-popup", "combobox-item"]}
	prefix="tag"
	attributes={[
		{ attr: "data-slot", value: '"tags-input" · "tag" · "tag-remove" · "tags-input-input" · "combobox-popup" · "combobox-item"' },
		{ attr: "data-highlighted", value: "on the chip or suggestion under the keyboard" },
		{ attr: "data-popup-open", value: "on the input while suggestions are open" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "data-invalid", value: "on the input inside an invalid Field" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "Adds the highlighted suggestion, or the typed text with allowCustom. A tag already in the list stays in the input." },
		{ key: "↓ / ↑", description: "Opens the suggestions and moves the highlight." },
		{ key: "Backspace", description: "In the empty input, removes the last tag." },
		{ key: "← / →", description: "Moves focus between the chips and back to the input." },
		{ key: "Delete / Backspace", description: "On a focused chip, removes it." },
		{ key: "Esc", description: "Closes the suggestions." },
	]}
	notes={[
		"The input has role=\"combobox\"; inside a Field, FieldLabel names it, and the description and error are read with it.",
		"Each chip's remove button needs a name: removeLabel builds it from the tag, like \"Remove finance\". Translate it.",
		"When you refuse a tag (duplicate, limit, invalid email), show the reason as text in FieldError; a silent refusal looks like a broken key.",
		"The popup is portalled but keeps the skin through PortalScope, and contrast passes WCAG 2.2 AA in all 13 skins.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Combobox", description: "Pick one value from a long list.", href: "/docs/components/combobox" },
		{ title: "Chip", description: "Filter chips and removable chips outside a field.", href: "/docs/components/chip" },
		{ title: "Checkbox", description: "Several choices when all of them fit on screen.", href: "/docs/components/checkbox" },
	]}
/>


# Time field (/docs/components/time-field)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Spinbutton (one per segment)" />

<Playground
	name="time-field/playground"
	component="TimeField"
	controls={[
		{ prop: "granularity", options: ["hour", "minute", "second"], default: "minute" },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. `Time` is a time of day; `ZonedDateTime` adds a date and a time zone. Both are re-exported from the package.

<Import names="TimeField, Time, ZonedDateTime, Field, FieldLabel" />

## Anatomy [#anatomy]

The same parts as `DateField`: a box with one segment per part of the time, and literals like `:` between them.

<Anatomy
	keys={[
		{ label: '[data-slot="time-field"]', color: "#8be36f" },
		{ label: '[data-slot="date-input"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">input</span>
	<span className="a-label">10</span>
	<span className="a-label">00</span>
	<span className="a-label">AM</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="time-field/basic" compact />

<ExampleGrid>
	<Example name="time-field/window" title="Start and end">
		Change either time. Two controlled fields give you the length, and the end field turns invalid when it comes before the start.
	</Example>
	<Example name="time-field/business-hours" title="Within business hours">
		Set a time from 8:00 AM to 6:00 PM. `minValue` and `maxValue` mark anything outside invalid, and `FieldError` says the allowed range.
	</Example>
	<Example name="time-field/hour-cycle" title="12 or 24 hours">
		The locale picks the clock. `hourCycle` forces one, for a timetable or an audience that expects it.
	</Example>
	<Example name="time-field/granularity" title="Seconds">
		`granularity="second"` adds a segment for timestamps and durations. Use `"hour"` when only the hour matters.
	</Example>
	<Example name="time-field/time-zone" title="With a time zone">
		A `ZonedDateTime` shows its zone as a read-only segment, so people in other cities know whose 10 AM it is. `hideTimeZone` drops it.
	</Example>
	<Example name="time-field/placeholder-value" title="Placeholder value">
		An empty field starts from midnight. `placeholderValue` starts the arrows at a likely time without filling it in.
	</Example>
	<Example name="time-field/read-only" title="Read-only">
		`readOnly` keeps the time focusable and readable by screen readers. Say who sets it.
	</Example>
</ExampleGrid>

## In context [#in-context]

Times come with dates and schedules. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="time-field/context-hours" title="Opening hours" uses="Card · Switch · TimeField · Button" />
	<Context name="time-field/context-meeting" title="Meeting scheduler" uses="Card · DateField · TimeField · Button" />
	<Context name="time-field/context-reminder" title="Daily summary" uses="Card · Switch · TimeField · Checkbox" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="time-field/do-time-zone" title="Show the zone when people are in different places.">
		A `ZonedDateTime` prints it next to the time, so nobody joins an hour early.
	</Guideline>
	<Guideline kind="dont" name="time-field/dont-no-zone" title="A bare time for a global event.">
		Everyone reads "10:00 AM" in their own zone, and most of them are wrong.
	</Guideline>
	<Guideline kind="do" name="time-field/do-two-fields" title="Two labeled fields for a range.">
		Start and end are each validated and read on their own.
	</Guideline>
	<Guideline kind="dont" name="time-field/dont-free-text" title="A text box for times.">
		"10:30 to 10:45-ish" can't be parsed, sorted or checked against the clock.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="TimeFieldProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "placeholderValue", "granularity", "hourCycle", "hideTimeZone", "shouldForceLeadingZeros", "name", "autoFocus"]}
	types={{ value: "TimeValue | null", defaultValue: "TimeValue | null", onChange: "(value: TimeValue | null) => void", minValue: "TimeValue", maxValue: "TimeValue", placeholderValue: "TimeValue", granularity: "\"hour\" | \"minute\" | \"second\"", hourCycle: "12 | 24" }}
	describe={{ className: "Classes added to the root.", style: "Inline styles for the root.", disabled: "Disables every segment. Inside a `Field`, the field's `disabled` is used when this is not set.", readOnly: "Keeps the value focusable and readable, but not editable.", invalid: "Marks the field invalid. Inside a `Field`, the field's `invalid` is used when this is not set.", required: "Marks the field required for assistive tech.", locale: "BCP 47 locale for the clock and the AM/PM labels, such as `\"en-US\"` or `\"pt-BR\"`. Defaults to the nearest `I18nProvider` or the browser's language." }}
>
	`TimeValue` is `Time`, `CalendarDateTime` or `ZonedDateTime`; the value you pass is the type you get back in `onChange`. `validationBehavior` defaults to `"aria"`: an out-of-range time marks the field invalid but never blocks the form.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the field itself.

<StylingHooks
	slots={["time-field", "date-input", "date-segment"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"time-field" · "date-input" · "date-segment"' },
		{ attr: "data-invalid", value: "on the root and segments when invalid" },
		{ attr: "data-disabled · data-readonly", value: "on the root and segments when disabled · read-only" },
		{ attr: "data-placeholder", value: "on a segment with no value yet" },
		{ attr: "data-type", value: "a segment's part: hour · minute · second · dayPeriod · timeZoneName · literal" },
		{ attr: "data-focused", value: "on the segment that has focus" },
	]}
>

```css
/* a quieter time zone label */
[data-slot="time-field"] [data-type="timeZoneName"] {
  color: var(--cml-fg-muted);
  font-size: 0.875em;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "0–9", description: "Types into the focused segment and moves on when it is full." },
		{ key: "A · P", description: "Sets AM or PM in the period segment." },
		{ key: "Arrow Up · Arrow Down", description: "Adds or subtracts one, wrapping at the end of the segment." },
		{ key: "Arrow Left · Arrow Right", description: "Moves between segments." },
		{ key: "Page Up · Page Down", description: "Steps by a bigger amount, like 15 minutes." },
		{ key: "Backspace", description: "Clears the focused segment." },
	]}
	notes={[
		"Each segment is a spinbutton named by its part (hour, minute, AM/PM) and the field's label.",
		"The whole value is read as text, such as \"10:00 AM GMT-3\", time zone included.",
		"FieldDescription and FieldError are linked with aria-describedby, and an invalid field sets aria-invalid.",
		"Always pass locale: the server and the browser then format the same way, and the clock matches the page's language.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Date field", description: "Day, month and year, typed in segments.", href: "/docs/components/date-field" },
		{ title: "Date picker", description: "A date field with a calendar popover.", href: "/docs/components/date-picker" },
		{ title: "Field", description: "Label, description and error for a control.", href: "/docs/components/field" },
	]}
/>


# Timeline (/docs/components/timeline)

<ComponentMeta file="data-display" pattern="HTML ordered list" />

<Playground
	name="timeline/playground"
	component="TimelineItem"
	controls={[{ prop: "tone", options: ["neutral", "brand", "success", "warning", "danger"], default: "brand" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Timeline, TimelineItem, TimelineTitle, TimelineDescription, TimelineTime" />

## Anatomy [#anatomy]

An ordered list. Each item is a row with the indicator, the text and the time; the line between indicators is drawn by CSS. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "timeline",
		tag: "ol",
		children: [
			{
				slot: "timeline-item",
				tag: "li",
				row: true,
				children: [
					{ slot: "timeline-indicator", tag: "span", note: "aria-hidden", children: [{ slot: "timeline-dot", tag: "span" }] },
					{ slot: "timeline-body", tag: "div", children: [{ slot: "timeline-title", tag: "p" }, { slot: "timeline-description", tag: "p" }] },
					{ slot: "timeline-time", tag: "time" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="timeline/basic" compact />

<ExampleGrid>
	<Example name="timeline/tones" title="Tones">
		Use `tone` to make problems stand out in a long history. The color is visual only, so the title still has to say what happened.
	</Example>
	<Example name="timeline/custom-icons" title="Icons">
		An icon per kind of event helps people scan a long list. Pass it in `icon`, with `aria-hidden`: the title already says the same thing.
	</Example>
	<Example name="timeline/with-time" title="Machine-readable time">
		Pass `dateTime` next to `time` when software needs the exact date, like for sorting or adding it to a calendar. People still read the short form.
	</Example>
	<Example name="timeline/current-step" title="Current step">
		For a process still running, add `aria-current="step"` to the current item and leave future steps neutral. The badge shows it to everyone, not only by color.
	</Example>
	<Example name="timeline/rich-content" title="Links and avatars">
		Children go under the description, so an event can link to what it changed. Name the list with `aria-label` when the page has more than one.
	</Example>
	<Example name="timeline/interactive-filter" title="Filtering events">
		Pick Alerts. The list keeps its order, and a status line tells screen readers how many events are left, since the change happens away from the focus.
	</Example>
</ExampleGrid>

## In context [#in-context]

A timeline usually sits in a card or a side panel, under the record it belongs to. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="timeline/context-shipping" title="Order tracking" uses="Card · Timeline · Badge" wide />
	<Context name="timeline/context-ticket" title="Support ticket history" uses="Card · Timeline · Avatar · Badge" wide />
	<Context name="timeline/context-changelog" title="Changelog" uses="Card · Timeline · Badge" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="timeline/do-iso-time" title="Give every event a real date and time.">
		People need to know when something happened, and `dateTime` gives software the same answer.
	</Guideline>
	<Guideline kind="dont" name="timeline/dont-ambiguous-time" title='"A while ago" on every event.'>
		Vague times can't be compared, so no one can tell how long a step took.
	</Guideline>
	<Guideline kind="do" name="timeline/do-logical-order" title="Keep one order: oldest or newest first.">
		Oldest first tells a process step by step; newest first suits activity feeds. Pick one per list.
	</Guideline>
	<Guideline kind="dont" name="timeline/dont-mixed-tenses" title="Events out of order.">
		The list is an `<ol>`, so screen readers announce each position, and a wrong order tells the wrong story.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="TimelineItemProps"
	include={["tone", "icon", "title", "description", "time", "children"]}
	describe={{ children: "Extra content under the description, like a link, a badge or a TimelineTime with dateTime." }}
>
	`Timeline` takes the attributes of `<ol>`, and `TimelineItem` those of `<li>`, like `aria-current`. `TimelineTitle` and `TimelineDescription` take those of `<p>`, and `TimelineTime` those of `<time>`, like `dateTime`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the timeline itself.

<StylingHooks
	slots={["timeline", "timeline-item", "timeline-indicator", "timeline-dot", "timeline-body", "timeline-title", "timeline-description", "timeline-time"]}
	prefix="timeline"
	attributes={[{ attr: "data-tone", value: "neutral · brand · success · warning · danger (on item and indicator)" }]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "A timeline has no Tab stop. Tab only reaches links and buttons inside the events." }]}
	notes={[
		"Timeline is an <ol> with role=\"list\", so screen readers announce the number of events and the position of each one, also in Safari.",
		"The indicator has aria-hidden: its tone and icon are never read. Say the outcome in the title, like \"Health check failed\".",
		"The time prop renders a <time>; add dateTime when the exact date matters.",
		"Mark the current step of a running process with aria-current=\"step\" on its TimelineItem.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Progress", description: "Shows how far a task is, when the steps themselves don't matter.", href: "/docs/components/progress" },
		{ title: "Data list", description: "Label and value pairs for the details of one record.", href: "/docs/components/data-list" },
		{ title: "Badge", description: "A short status, like Delivered or Resolved, next to the timeline's title.", href: "/docs/components/badge" },
	]}
/>


# Toast (/docs/components/toast)

<ComponentMeta file="toast" primitive="Base UI" pattern="WAI-ARIA status" />

<Playground
	name="toast/playground"
	component="Toast"
	controls={[
		{ prop: "type", options: ["info", "success", "warning", "danger"], default: "info" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need.

<Import names="ToastProvider, useToast" />

### One provider for the whole app [#one-provider-for-the-whole-app]

Put `ToastProvider` once, near the root, inside your `StyleProvider`. It renders the corner where toasts stack and the live region that reads them out. Two providers mean two stacks that overlap and two voices for screen readers.

```tsx title="app/layout.tsx"
import { StyleProvider, ToastProvider } from "@camaleo/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<html lang="en">
			<body>
				<StyleProvider styleName="editorial">
					<ToastProvider closeLabel="Close">{children}</ToastProvider>
				</StyleProvider>
			</body>
		</html>
	);
}
```

Then call `useToast()` in any component below it:

```tsx
const toast = useToast();
toast.add({ title: "Preferences saved", type: "success" });
```

## Anatomy [#anatomy]

A corner of the screen (the viewport) that stacks the toasts. Each toast has the tone's icon, a title, an optional description and action, and a close button.

<Anatomy
	keys={[
		{ label: '[data-slot="toast-viewport"]', color: "#8be36f" },
		{ label: '[data-slot="toast"]', color: "#ffcf7a" },
		{ label: "title · description · action · close", color: "#7cc7ff" },
	]}
>
	<span className="a-part">viewport</span>
	<span className="a-part">toast</span>
	<span className="a-label">Preferences saved</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Each one brings its own `ToastProvider` only so it runs alone on this page; in your app, use the one at the root.

<Preview name="toast/basic" compact />

<ExampleGrid>
	<Example name="toast/tones" title="Tones">
		Click each one. The `type` picks the color and icon: info for progress, success when it worked, warning when it may not, danger when it failed.
	</Example>
	<Example name="toast/action-undo" title="With undo">
		Click Archive, then Undo. Offer undo for actions that are easy to reverse, instead of asking "Are you sure?" first.
	</Example>
	<Example name="toast/duration" title="Longer on screen">
		`timeout` is in milliseconds; the default is 5000. Give a longer message more time, so people can finish reading it.
	</Example>
	<Example name="toast/persistent" title="Stays until closed">
		`timeout: 0` keeps the toast until people act on it or close it. Use it when the message still matters later, like a new version to reload.
	</Example>
	<Example name="toast/loading" title="Loading, then done">
		Click Upload. `toast.promise()` shows a loading toast with a spinner, then turns it into the success or error toast when the promise settles. One toast tells the whole story.
	</Example>
	<Example name="toast/urgent" title="Urgent">
		`priority: "high"` interrupts the screen reader. Keep it for problems people must know about right now, like losing the connection.
	</Example>
	<Example name="toast/stacked-avoid" title="One toast for a batch">
		After a bulk action, sum it up in one toast: "12 contacts updated", not twelve toasts.
	</Example>
	<Example name="toast/a11y-polite" title="Read out without moving focus">
		Toasts are announced when the screen reader is free, and focus stays where it was, so people can keep typing.
	</Example>
</ExampleGrid>

## In context [#in-context]

Toasts confirm actions taken elsewhere on the page. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="toast/context-archive" title="Archive a conversation" uses="Card · Toast · Button" />
	<Context name="toast/context-upload" title="Export a file" uses="Card · Toast · Button" />
	<Context name="toast/context-copy" title="Copy an invite link" uses="Card · Toast · Button" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="toast/do-brief" title="Confirm what just happened.">
		A few words people can read at a glance: what was done and, if useful, where to find it.
	</Guideline>
	<Guideline kind="dont" name="toast/dont-block" title="Ask for a decision in a toast.">
		It disappears on its own, and keyboard users may never reach it. Use a dialog for choices people must make.
	</Guideline>
	<Guideline kind="do" name="toast/do-single" title="One toast for a bulk action.">
		"4 conversations archived" says it once and keeps the screen clear.
	</Guideline>
	<Guideline kind="dont" name="toast/dont-flood" title="One toast per item.">
		A stack of toasts covers the page, and screen readers read every one of them.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="toast" type="ToastProviderProps" include={["timeout", "limit"]}
	describe={{
		timeout: "Default time on screen, in milliseconds, for every toast. `0` keeps toasts until people close them.",
		limit: "How many toasts show at once. Older ones get `data-limited` and are hidden until a newer one closes.",
	}}
>
	`useToast()` returns `add`, `update`, `close`, `promise` and the `toasts` list. `add` takes `title`, `description`, `type`, `timeout`, `priority`, `actionProps` and `onClose`, and returns the toast's id. `type` is `info`, `success`, `warning` or `danger`; `loading` (a spinner) and `error` (same as `danger`) also work, and are what `promise` uses.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the viewport.

<StylingHooks
	slots={["toast-viewport", "toast", "toast-content", "toast-title", "toast-description", "toast-close"]}
	attributes={[
		{ attr: "data-tone", value: "info · success · warning · danger" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "F6", description: "Moves focus to the toast stack from anywhere on the page." },
		{ key: "Tab", description: "Moves between the action and close buttons of the toasts." },
		{ key: "Escape", description: "Closes the focused toast." },
	]}
	notes={[
		"Toasts are read out politely, after what the screen reader is saying. With priority: \"high\", they interrupt.",
		"A toast never takes focus, so it never interrupts typing.",
		"The timer pauses while the pointer is over the stack or focus is inside it.",
		"If a toast has an action, make sure people can do the same thing somewhere else on the page, or use timeout: 0. Not everyone reaches it in 5 seconds.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Alert", description: "A message that stays in the page until the situation changes.", href: "/docs/components/alert" },
		{ title: "AlertDialog", description: "Stops the flow to confirm something that can't be undone.", href: "/docs/components/alert-dialog" },
		{ title: "Progress", description: "Shows how far a long task has gone, in the page.", href: "/docs/components/progress" },
	]}
/>


# Toggle (/docs/components/toggle)

<ComponentMeta file="toggle" primitive="Base UI" pattern="WAI-ARIA Button (aria-pressed)" />

<Playground
	name="toggle/playground"
	component="Toggle"
	controls={[
		{ prop: "defaultPressed", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need.

<Import names="Toggle, ToggleGroup" />

## Anatomy [#anatomy]

A `Toggle` is one button with `aria-pressed`. A `ToggleGroup` wraps several and moves focus between them with the arrow keys.

<Anatomy
	keys={[
		{ label: '[data-slot="toggle-group"]', color: "#8be36f" },
		{ label: '[data-slot="toggle"][data-pressed]', color: "#ffcf7a" },
		{ label: "icon or label (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">B</span>
	<span className="a-part">I</span>
	<span className="a-label">U</span>
</Anatomy>

## Examples [#examples]

<Preview name="toggle/formatting" compact />

<ExampleGrid>
	<Example name="toggle/with-text" title="With a label">
		An icon and a short label. The label names the setting, not the state.
	</Example>
	<Example name="toggle/controlled" title="Controlled">
		Click it. `pressed` and `onPressedChange` let the rest of the screen react to the state.
	</Example>
	<Example name="toggle/group-single" title="One of many">
		A `ToggleGroup` lets only one stay pressed, like text alignment. Arrow keys move between the options.
	</Example>
	<Example name="toggle/group-multiple" title="Many of many">
		With `multiple`, any number can be pressed — bold, italic and underline at once.
	</Example>
	<Example name="toggle/with-tooltip" title="Icon only, with a tooltip">
		The `aria-label` is the tooltip text, so screen readers hear the same name sighted users see on hover.
	</Example>
	<Example name="toggle/disabled" title="Disabled">
		Keeps its pressed state visible, so people still see what is on.
	</Example>
</ExampleGrid>

## In context [#in-context]

<ContextGrid>
	<Context name="toggle/context-editor" title="Editor toolbar" uses="ToggleGroup · Toggle · Separator" />
	<Context name="toggle/context-view" title="View switcher" uses="ToggleGroup · Card" />
	<Context name="toggle/context-favorite" title="Favorite" uses="Toggle · Card" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="toggle/do-stable-label" title="Keep the label the same.">
		The pressed look carries the state; screen readers announce it from `aria-pressed`.
	</Guideline>
	<Guideline kind="dont" name="toggle/dont-action" title="A toggle for a one-off action.">
		"Send" happens once. Use a `Button`.
	</Guideline>
	<Guideline kind="do" name="toggle/do-group" title="Group related options.">
		A `ToggleGroup` gives them one tab stop and arrow-key navigation.
	</Guideline>
	<Guideline kind="dont" name="toggle/dont-loose" title="Loose toggles that should be exclusive.">
		Two alignments pressed at once is a state that makes no sense.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="toggle" type="ToggleProps" include={["pressed", "defaultPressed", "onPressedChange", "value", "disabled", "render"]} types={{ render: "ReactElement | (props, state) => ReactElement" }} />

`ToggleGroup` takes `value`, `defaultValue` and `onValueChange` (arrays of the toggles' `value`), `multiple` and `orientation`.

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["toggle", "toggle-group"]}
	prefix="toggle"
	attributes={[
		{ attr: "data-slot", value: '"toggle" · "toggle-group"' },
		{ attr: "data-pressed", value: "present while pressed" },
		{ attr: "data-disabled", value: "present when disabled" },
		{ attr: "aria-pressed", value: '"true" · "false"' },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Space", description: "Presses or releases the toggle." },
		{ key: "Enter", description: "Presses or releases the toggle." },
		{ key: "Arrow keys", description: "In a ToggleGroup, move focus to the previous or next toggle." },
		{ key: "Home / End", description: "In a ToggleGroup, move focus to the first or last toggle." },
	]}
	notes={[
		"Icon-only toggles need an aria-label; the state comes from aria-pressed, so the label never changes.",
		"Give every ToggleGroup an aria-label that names the setting (\"Alignment\").",
		"The pressed look passes 3:1 against the unpressed one in every skin.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Button", description: "For actions that happen once.", href: "/docs/components/button" },
		{ title: "Switch", description: "On and off for settings that apply right away.", href: "/docs/components/switch" },
		{ title: "Toolbar", description: "Groups buttons and toggles with one tab stop.", href: "/docs/components/toolbar" },
	]}
/>


# Toggletip (/docs/components/toggletip)

<ComponentMeta file="toggletip" primitive="Base UI" pattern="Button + non-modal region" />

<Playground
	name="toggletip/playground"
	component="ToggletipContent"
	controls={[
		{ prop: "align", options: ["start", "center", "end"], default: "center" },
		{ prop: "hideArrow", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Toggletip, ToggletipTrigger, ToggletipContent, ToggletipTitle, ToggletipDescription, ToggletipClose" />

## Anatomy [#anatomy]

The trigger is a round button (`toggletip-trigger`). The tip renders in a portal, wrapped in a scope that keeps the skin, mode and brand of the page around the button.

<Anatomy
	tree={{
		slot: "toggletip-positioner",
		tag: "div",
		note: "in a portal",
		children: [
			{
				slot: "toggletip-popup",
				tag: "div",
				note: "role=region, takes focus",
				children: [
					{ slot: "toggletip-arrow", tag: "div", note: "aria-hidden" },
					{ slot: "toggletip-title", tag: "h2", note: "names the region" },
					{ slot: "toggletip-description", tag: "p" },
					{ slot: "toggletip-close", tag: "button", note: "optional" },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Click a "?" button, or Tab to it and press Enter.

Which one? A **Tooltip** names a control in a few words, on hover. A **HoverCard** previews where a link goes, on hover. A **Toggletip** explains a term on click, so it is the one that works on touch and that screen readers read.

<Preview name="toggletip/basic" compact />

<ExampleGrid>
	<Example name="toggletip/form-label" title="Next to a field label">
		Put the button after the label, not inside it, so the field's name stays "Billing email" and the help is one click away.
	</Example>
	<Example name="toggletip/table-header" title="In a table header">
		Explain how a metric is calculated without a footnote. `align="end"` keeps the tip inside a right-aligned column.
	</Example>
	<Example name="toggletip/settings-row" title="In a settings row">
		Say what a switch really does, with the date or the amount, before people turn it on.
	</Example>
	<Example name="toggletip/a11y-name" title="Named after the topic">
		Each button says "More about …" and the topic. In a screen reader's list of buttons, five plain "Info" buttons are impossible to tell apart.
	</Example>
	<Example name="toggletip/with-link" title="With a link inside">
		Open it with the keyboard: focus goes to the tip and Tab reaches the link, so it works without a mouse. One link at most, to the full explanation.
	</Example>
	<Example name="toggletip/title-close" title="Title and close button">
		Click it. The title names the tip for screen readers, and `ToggletipClose` gives touch users a clear way out. Pass a translated `aria-label`.
	</Example>
	<Example name="toggletip/alignment" title="Alignment" wide>
		`align` lines the tip up with the start, center or end of the button. `side` picks the side it opens on; it flips when there is no room.
	</Example>
</ExampleGrid>

## In context [#in-context]

Toggletips explain terms right where people meet them. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="toggletip/context-pricing" title="Plan comparison" uses="Table · Toggletip" />
	<Context name="toggletip/context-form" title="Loan simulator" uses="Card · Field · Input · Button · Toggletip" />
	<Context name="toggletip/context-settings" title="Security settings" uses="Card · Switch · Label · Toggletip" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="toggletip/do-toggletip" title="A toggletip for explanations.">
		It opens on a click or a tap, so phones, keyboards and screen readers all get the text.
	</Guideline>
	<Guideline kind="dont" name="toggletip/dont-tooltip" title="A tooltip for explanations.">
		It needs hover or focus, so it never opens on a phone, and screen readers skip it.
	</Guideline>
	<Guideline kind="do" name="toggletip/do-short" title="One or two sentences.">
		Enough to understand the term and carry on filling the form.
	</Guideline>
	<Guideline kind="dont" name="toggletip/dont-long" title="A whole policy in a tip.">
		Three paragraphs don't fit a small box. Write it on the page, or link to a help article.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="toggletip" type="ToggletipContentProps">
	`Toggletip` takes `open`, `onOpenChange` and `defaultOpen`. `ToggletipTrigger` needs an `aria-label` such as "More about the interest rate". `ToggletipClose` takes `aria-label` (default "Close tip"; translate it).
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the tip itself.

<StylingHooks
	slots={["toggletip-trigger", "toggletip-positioner", "toggletip-popup", "toggletip-arrow", "toggletip-title", "toggletip-description", "toggletip-close"]}
	prefix="toggletip"
	attributes={[
		{ attr: "data-popup-open", value: "on the trigger while the tip is open" },
		{ attr: "data-side", value: "bottom · top" },
		{ attr: "data-align", value: "start · center · end" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "On the button, opens the tip and moves focus to the tip itself, so its text is read first. Tab then reaches a link or close button inside." },
		{ key: "Space", description: "Same as Enter." },
		{ key: "Tab", description: "Inside the tip, moves to its next link or button. Past the last one, focus goes on to what follows the button and the tip closes." },
		{ key: "Escape", description: "Closes the tip and returns focus to the button." },
	]}
	notes={[
		"Focus moves into the tip when it opens, so screen readers read it: a region named by its title and described by its text. It isn't a live region, so nothing is announced while focus stays elsewhere.",
		"The button has no visible text. Give it an aria-label that names the topic, such as \"More about the interest rate\". Without a ToggletipTitle, pass aria-label to ToggletipContent too.",
		"A click or tap outside closes it, and the rest of the page stays usable: it isn't a dialog, so the button reports aria-expanded but no aria-haspopup.",
		"Focus lands on the tip itself, so screen readers read the explanation before any link or close button inside. Keep to one link, and keep the text short.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Tooltip", description: "A short label for an icon button, on hover or focus.", href: "/docs/components/tooltip" },
		{ title: "HoverCard", description: "A preview of a link's destination, on hover or focus.", href: "/docs/components/hover-card" },
		{ title: "Field", description: "Label, description and error for a form control.", href: "/docs/components/field" },
	]}
/>


# Toolbar (/docs/components/toolbar)

<ComponentMeta file="toolbar" primitive="Base UI" pattern="WAI-ARIA Toolbar" />

<Playground
	name="toolbar/playground"
	component="Toolbar"
	controls={[
		{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" },
		{ prop: "loopFocus", default: true },
		{ prop: "disabled", default: false },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="Toolbar, ToolbarGroup, ToolbarButton, ToolbarToggle, ToolbarLink, ToolbarInput, ToolbarSeparator" />

## Anatomy [#anatomy]

A `div` with `role="toolbar"`. Only one control in it is in the Tab order at a time; the arrow keys move that spot. A `ToggleGroup` inside joins the same order when its toggles render through `ToolbarButton`.

<Anatomy
	tree={{
		slot: "toolbar",
		tag: "div",
		note: "role=toolbar, data-orientation",
		row: true,
		children: [
			{
				slot: "toolbar-group",
				tag: "div",
				note: "role=group",
				row: true,
				children: [
					{ slot: "toolbar-toggle", tag: "button", note: "aria-pressed" },
					{ slot: "toolbar-button", tag: "button" },
				],
			},
			{ slot: "toolbar-separator", tag: "div", note: "role=separator" },
			{ slot: "toolbar-link", tag: "a" },
			{ slot: "input", tag: "input", note: "ToolbarInput" },
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Click into one, then use Tab and the arrow keys.

<Preview name="toolbar/basic" compact />

<ExampleGrid>
	<Example name="toolbar/table-actions" title="Actions for selected rows" wide>
		Select orders and press Export. The search field sits next to the toolbar, not inside it: it searches the table, not the selection, so it keeps its own Tab stop.
	</Example>
	<Example name="toolbar/vertical" title="Vertical tool palette">
		With `orientation="vertical"` the Up and Down arrows move focus. The tools are a `ToggleGroup`, so only one is pressed at a time.
	</Example>
	<Example name="toolbar/icon-tooltips" title="Icon buttons with names">
		Every icon-only button needs an `aria-label`. A tooltip with the same words shows that name to sighted people too.
	</Example>
	<Example name="toolbar/overflow" title="Overflow into More" wide>
		Narrow the window. Under 420 px only Reply and Reply all stay; everything else moves into the More menu instead of wrapping.
	</Example>
	<Example name="toolbar/disabled" title="Disabled but still reachable">
		Disabled toolbar buttons stay in the arrow-key order, so people find Undo and hear why it is off. Pass `focusableWhenDisabled={false}` to skip one.
	</Example>
	<Example name="toolbar/input" title="A field inside the toolbar">
		Type a page number and press Enter. `ToolbarInput` joins the arrow-key order; inside it the arrows move the caret and leave the field only at either end of the text.
	</Example>
	<Example name="toolbar/links" title="Links next to buttons">
		`ToolbarLink` goes to another page and `ToolbarButton` acts on this one; both share the same arrow-key order.
	</Example>
</ExampleGrid>

## In context [#in-context]

These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="toolbar/context-email" title="Email reader" uses="Card · Toolbar · Tooltip · Menu · Avatar" />
	<Context name="toolbar/context-files" title="File manager" uses="Card · Toolbar · ToggleGroup · Tooltip · Menu" />
	<Context name="toolbar/context-image" title="Image viewer" uses="Card · Toolbar · Tooltip" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="toolbar/do-group" title="Group related controls.">
		History, formatting and insert each get a `ToolbarGroup` with a name, split by separators.
	</Guideline>
	<Guideline kind="dont" name="toolbar/dont-flat" title="One long row in no order.">
		Bold next to Undo next to Image: people scan the whole row every time.
	</Guideline>
	<Guideline kind="do" name="toolbar/do-labels" title="Words for uncommon actions.">
		Bold and Undo are known by their icons. "Levels" and "Vignette" are not.
	</Guideline>
	<Guideline kind="dont" name="toolbar/dont-ambiguous" title="Icons only, for actions nobody recognises.">
		Screen readers hear the names, but everyone else has to guess, or hover each one.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="toolbar"
	type="ToolbarProps"
	include={["orientation", "loopFocus", "disabled", "aria-label"]}
	types={{ "aria-label": "string", orientation: "\"horizontal\" | \"vertical\"" }}
	describe={{
		orientation: "Which arrow keys move focus: Left and Right, or Up and Down. Also lays the toolbar out as a column.",
		loopFocus: "Whether the arrow keys wrap from the last control to the first.",
		disabled: "Disables every control in the toolbar.",
		"aria-label": "Names the toolbar, for example \"Text formatting\".",
	}}
>
	`ToolbarToggle` takes `pressed` and is controlled: flip it in `onClick`. `ToolbarButton` takes `disabled` and `focusableWhenDisabled` (default `true`). `ToolbarGroup` takes `disabled` and an `aria-label`. `ToolbarInput` takes the props of `<input>`; name it with `aria-label`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the toolbar itself.

<StylingHooks
	slots={["toolbar", "toolbar-group", "toolbar-button", "toolbar-toggle", "toolbar-link", "toolbar-separator"]}
	prefix="toolbar"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical" },
		{ attr: "aria-pressed · data-pressed", value: "on a pressed ToolbarToggle" },
		{ attr: "data-disabled", value: "on a disabled control" },
		{ attr: "data-focusable", value: "on a disabled control that stays focusable" },
	]}
>

```css
/* bigger targets in the drawing app */
.canvas-tools [data-slot="toolbar"] {
  --cml-toolbar-btn-size: 2.5rem;
}
```

</StylingHooks>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves into the toolbar, to the control that had focus last, and then out of it. The whole toolbar is one Tab stop." },
		{ key: "Right Arrow / Left Arrow", description: "Moves to the next or previous control, toggles in a ToggleGroup included. From the last one it wraps to the first (loopFocus)." },
		{ key: "Down Arrow / Up Arrow", description: "The same, in a toolbar with orientation=\"vertical\". Left and Right do nothing there." },
		{ key: "Enter / Space", description: "Activates the button, presses or releases the toggle, or opens the menu with focus on its first item." },
		{ key: "Home / End", description: "Moves to the first or last control. In a ToolbarInput they move the caret instead." },
		{ key: "Escape", description: "In a menu opened from the toolbar, closes it and puts focus back on its button." },
	]}
	notes={[
		"Name every toolbar with aria-label (\"Text formatting\") and every ToolbarGroup or ToggleGroup that holds a set (\"Alignment\").",
		"ToolbarToggle sets aria-pressed, so screen readers hear \"Bold, toggle button, pressed\". Keep the label the same in both states.",
		"Disabled buttons stay in the arrow-key order with aria-disabled, so people still find them. Say why with aria-describedby.",
		"Name a ToolbarInput with aria-label. A field that serves the whole page, such as a search, reads better next to the toolbar, with its own Tab stop.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Toggle", description: "A button that stays pressed, and groups of them.", href: "/docs/components/toggle" },
		{ title: "Menu", description: "Where the actions that don't fit go.", href: "/docs/components/menu" },
		{ title: "Tooltip", description: "Shows the name of an icon button on hover and focus.", href: "/docs/components/tooltip" },
	]}
/>


# Tooltip (/docs/components/tooltip)

<ComponentMeta file="popover" primitive="Base UI" pattern="WAI-ARIA Tooltip" />

<Playground
	name="tooltip/playground"
	component="TooltipContent"
	controls={[
		{ prop: "side", options: ["top", "bottom", "left", "right"], default: "top" },
		{ prop: "align", options: ["start", "center", "end"], default: "center" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the client.

<Import names="TooltipProvider, Tooltip, TooltipTrigger, TooltipContent" />

## Anatomy [#anatomy]

A trigger and a popup with an arrow. The popup renders in a portal, so a parent with `overflow: hidden` doesn't cut it.

<Anatomy
	keys={[
		{ label: '[data-slot="tooltip-popup"]', color: "#8be36f" },
		{ label: '[data-slot="tooltip-arrow"]', color: "#ffcf7a" },
		{ label: "content (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">arrow</span>
	<span className="a-part">popup</span>
	<span className="a-label">Download invoice</span>
</Anatomy>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above. Screen readers don't read the tooltip, so on an icon button the `aria-label` must say exactly what the tooltip says.

<Preview name="tooltip/basic" compact />

<ExampleGrid>
	<Example name="tooltip/a11y-non-essential" title="Same text as the label">
		The tooltip shows sighted people the name a screen reader hears. Write it once and use it for both `aria-label` and the tooltip.
	</Example>
	<Example name="tooltip/with-kbd" title="With a shortcut">
		Add a `Kbd` to teach the shortcut, and `aria-keyshortcuts` on the trigger so screen reader users learn it too.
	</Example>
	<Example name="tooltip/placements" title="Sides" wide>
		Point the tooltip where the action goes: up for "Move up", right for "Next". If there is no room, it flips to the other side.
	</Example>
	<Example name="tooltip/delay" title="Shared delay in a toolbar">
		Hover one button, then slide to the next. One `TooltipProvider` around the group waits for the first tooltip only, so the rest open right away.
	</Example>
	<Example name="tooltip/interactive-copy" title="Copy, then confirm">
		Click it. The tooltip changes to "Copied" for people who see it, and a hidden status message says "Link copied" to screen readers.
	</Example>
	<Example name="tooltip/disabled" title="On a disabled button">
		A disabled button gets no hover or focus, so its tooltip never opens. Use `focusableWhenDisabled` and link the reason with `aria-describedby`.
	</Example>
	<Example name="tooltip/truncated" title="Full text of a cut-off name">
		Show the full file name when it doesn't fit. Keep the whole name in the link text, so screen readers read it.
	</Example>
</ExampleGrid>

## In context [#in-context]

Tooltips name the buttons that only have an icon. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="tooltip/context-toolbar" title="Formatting toolbar" uses="Card · ButtonGroup · Tooltip · Kbd" />
	<Context name="tooltip/context-nav-rail" title="Navigation rail" uses="IconButton · Tooltip" />
	<Context name="tooltip/context-editor" title="Code editor actions" uses="Card · ButtonGroup · Tooltip" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="tooltip/do-short-text" title="A few words, the same as the label.">
		"Save changes" reads at a glance and is exactly what the screen reader says.
	</Guideline>
	<Guideline kind="dont" name="tooltip/dont-interactive-content" title="Links or buttons inside a tooltip.">
		It closes as soon as the pointer leaves, and keyboard users can't reach it. Use a popover instead.
	</Guideline>
	<Guideline kind="do" name="tooltip/do-keyboard-shortcut" title="Show the shortcut.">
		People learn it at the moment they use the action, without a help page.
	</Guideline>
	<Guideline kind="dont" name="tooltip/dont-essential-info" title="Rules only in a tooltip.">
		On a phone there is no hover, and screen readers don't read it. Put password rules in the field's description.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="popover" type="TooltipContentProps">
	`TooltipProvider` takes `delay` (ms before the first tooltip opens, default 600) and `closeDelay` (ms before it closes). `TooltipTrigger` takes the same two for a single tooltip, and `Tooltip` takes `disabled`, `open` and `onOpenChange`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the popup itself.

<StylingHooks
	slots={["tooltip-trigger", "tooltip-positioner", "tooltip-popup", "tooltip-arrow"]}
	attributes={[
		{ attr: "data-side", value: "top · bottom · left · right" },
		{ attr: "data-align", value: "start · center · end" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Focusing the trigger opens the tooltip after the delay." },
		{ key: "Escape", description: "Closes the tooltip. Focus stays on the trigger." },
	]}
	notes={[
		"Screen readers don't read the tooltip: nothing links it to the trigger. On an icon button, the aria-label must be the tooltip's text, word for word.",
		"Anything people need to know goes in the page, not only in a tooltip. Touch screens have no hover, so the tooltip never opens there.",
		"Disabled buttons get no hover or focus. Keep them focusable with focusableWhenDisabled, or say the reason next to the button.",
		"The pointer can move onto the tooltip without closing it, as WCAG 1.4.13 asks.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Popover", description: "A floating panel for links, forms or actions.", href: "/docs/components/popover" },
		{ title: "Toggletip", description: "Opens on click, so it also works on touch screens.", href: "/docs/components/toggletip" },
		{ title: "Kbd", description: "Shows a keyboard shortcut, in a tooltip or in the text.", href: "/docs/components/kbd" },
	]}
/>


# TreeView (/docs/components/tree-view)

<ComponentMeta file="tree-view" pattern="WAI-ARIA Tree View" />

<Playground
	name="tree-view/playground"
	component="TreeView"
	controls={[{ prop: "selectionMode", options: ["single", "multiple"], default: "single" }]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It runs on the client, because it keeps the open branches and the selection.

<Import names="TreeView, TreeItem" />

## Anatomy [#anatomy]

A list of items, where an item with children opens a nested group. Every part has a `data-slot` you can target from CSS.

<Anatomy
	tree={{
		slot: "tree-view",
		tag: "ul",
		children: [
			{
				slot: "tree-item",
				tag: "li",
				children: [
					{
						slot: "tree-item-row",
						tag: "div",
						row: true,
						children: [
							{ slot: "tree-item-chevron", tag: "span", note: "branches" },
							{ slot: "tree-item-spacer", tag: "span", note: "leaves" },
							{ slot: "tree-item-icon", tag: "span" },
							{ slot: "tree-item-label", tag: "span" },
							{ slot: "tree-item-meta", tag: "span", note: "optional" },
						],
					},
					{ slot: "tree-group", tag: "ul", note: "while open", children: [{ slot: "tree-item", tag: "li" }] },
				],
			},
		],
	}}
/>

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="tree-view/basic" compact />

<ExampleGrid>
	<Example name="tree-view/default-expanded" title="Open on the current item">
		Open the branches that lead to the selected item with `defaultExpandedValues`. People see where they are without clicking, and Tab lands on that item.
	</Example>
	<Example name="tree-view/multi-selection" title="Several items at once">
		Use `selectionMode="multiple"` when people act on a batch, like moving files. Space adds or removes one item and keeps the others.
	</Example>
	<Example name="tree-view/custom-icons" title="Icons for the kind of item">
		Pass `icon` when items are of different kinds, like servers and databases. The icon is hidden from screen readers, so the label must say everything.
	</Example>
	<Example name="tree-view/with-meta" title="One fact per row">
		Use `meta` for a short value, like a size or a count. Screen readers read it with the label, so keep it to a few characters.
	</Example>
	<Example name="tree-view/interactive-file-tree" title="React to the selection">
		Click a file or press Enter on it. Control `selectedValues` when another part of the page shows what was picked, like an editor or a preview.
	</Example>
	<Example name="tree-view/labelled" title="Named by its heading">
		Point `aria-labelledby` at the visible heading, so screen readers say what the tree holds. The tree is one Tab stop; arrow keys move inside it.
	</Example>
</ExampleGrid>

## In context [#in-context]

Trees usually sit in a sidebar or a card, next to the content they open. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="tree-view/context-filesystem" title="File explorer" uses="Card · TreeView · Badge" wide />
	<Context name="tree-view/context-categories" title="Category filter" uses="Card · TreeView · Button" wide />
	<Context name="tree-view/context-mail" title="Mail folders" uses="Card · TreeView · Badge" wide />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="tree-view/do-nested" title="Use a tree for items that nest.">
		Folders, categories and sections with subsections are what the open and close arrows are for.
	</Guideline>
	<Guideline kind="dont" name="tree-view/dont-flat-list" title="A tree for a flat list.">
		With no branches, the tree adds arrow keys and announcements for nothing. Use a list, links or a menu.
	</Guideline>
	<Guideline kind="do" name="tree-view/do-short-labels" title="Short labels, the path in the branches.">
		The branch above already says where the item is, so the label only needs its own name.
	</Guideline>
	<Guideline kind="dont" name="tree-view/dont-long-labels" title="The full path in every label.">
		Long labels get cut off on narrow screens, and screen readers repeat the same words on every row.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="tree-view" type="TreeViewProps" />

<Props file="tree-view" type="TreeItemProps">
	Every item needs a `value` that is unique in the whole tree, like its path: two items with the same value open and select together. `TreeView` also takes the attributes of `<ul>`, and `TreeItem` those of `<li>`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the tree itself.

<StylingHooks
	slots={["tree-view", "tree-item", "tree-item-row", "tree-item-chevron", "tree-item-spacer", "tree-item-icon", "tree-item-label", "tree-item-meta", "tree-group"]}
	prefix="tree"
	attributes={[
		{ attr: "data-selected", value: "on tree-item and tree-item-row, while selected" },
		{ attr: "data-expanded", value: "on a branch's tree-item, while open" },
		{ attr: "data-value", value: "the item's value, on tree-item" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Moves into the tree, on the selected item, and out of it. The whole tree is one stop." },
		{ key: "↓ / ↑", description: "Moves to the next or previous visible item." },
		{ key: "→", description: "Opens a closed branch. On an open branch, moves to its first child." },
		{ key: "←", description: "Closes an open branch. On a child, moves to its parent." },
		{ key: "Home / End", description: "Moves to the first or last visible item." },
		{ key: "Space", description: "Selects the item. With multiple selection, adds or removes it." },
		{ key: "Enter", description: "Does what Space does, and also opens or closes a branch." },
	]}
	notes={[
		"The tree is a role=\"tree\" list. Branches have aria-expanded and open a role=\"group\"; items have aria-selected, and multiple selection adds aria-multiselectable.",
		"Tab enters on the selected item, or on the first item when nothing selected is visible.",
		"Name the tree with aria-label, or aria-labelledby pointing at its heading.",
		"There is no type-to-find: with long lists, add a search field above the tree.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Accordion", description: "Sections that open and close, for content rather than a list of items.", href: "/docs/components/accordion" },
		{ title: "Data table", description: "Rows and columns with sorting and filtering, for flat records.", href: "/docs/components/data-table" },
		{ title: "Card", description: "The surface that usually holds a tree in a sidebar or a panel.", href: "/docs/components/card" },
	]}
/>


# Typography (/docs/components/typography)

<ComponentMeta file="typography" pattern="WAI-ARIA heading / paragraph" />

<Playground
	name="typography/playground"
	component="Heading"
	controls={[
		{ prop: "level", options: [1, 2, 3, 4], default: 2 },
		{ prop: "size", options: ["display", "lg", "md", "sm"], default: "lg" },
	]}
/>

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import what you need. It renders on the server.

<Import names="Heading, Text" />

## Anatomy [#anatomy]

Two separate elements: `Heading` renders `<h1>` to `<h4>`, and `Text` renders a `<p>`. Each has a `data-slot` you can target from CSS.

<Anatomy tree={{ slot: "heading", tag: "h1–h4", note: "data-size sets the look" }} />

<Anatomy tree={{ slot: "text", tag: "p", note: "data-variant · data-drop-cap" }} />

## Examples [#examples]

Every example is a real file you can copy. They all wear the skin, mode and brand from the bar above.

<Preview name="typography/basic" compact />

<ExampleGrid>
	<Example name="typography/heading-levels" title="Four sizes" wide>
		Use the largest size once, for the page hero. Then the large size for sections, the medium one for cards and panels, and the small one for groups inside them.
	</Example>
	<Example name="typography/outline" title="Level and size apart">
		These are an `h2` and two `h3` in a settings panel, but drawn small. The outline stays right for screen readers, and the panel doesn't shout.
	</Example>
	<Example name="typography/interactive-scale" title="Try the sizes">
		Click a size. The heading changes how it looks, but it stays an `h2`, so the page outline doesn't change.
	</Example>
	<Example name="typography/text-variants" title="Body and small text">
		Use body text for what people read. Use small text for what they scan or skip: dates, reading time, fine print.
	</Example>
	<Example name="typography/inline" title="Emphasis and links in a sentence">
		Use `<strong>` for the one fact people must not miss and `<em>` for stress. A `Link` inside `Text` keeps the paragraph's size.
	</Example>
	<Example name="typography/measure" title="Line length" wide>
		Limit paragraphs to about 65 characters per line with `maxInlineSize: "65ch"` on the container. Longer lines make it hard to find the start of the next one.
	</Example>
	<Example name="typography/drop-cap" title="Drop cap">
		Pass `dropCap` to the first paragraph of a long article. Keep it for editorial pages; in an app it only gets in the way.
	</Example>
</ExampleGrid>

## In context [#in-context]

Headings and text carry most of a page. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="typography/context-blog" title="Article opening" uses="Heading · Text" />
	<Context name="typography/context-hero" title="Landing page hero" uses="Heading · Text · Button" />
	<Context name="typography/context-legal" title="Terms of service" uses="Heading · Text" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="typography/do-separate-level-size" title="Pick the level from the outline, the size from the space.">
		An `h2` in a sidebar can use `size="sm"`. It looks small and still reads as a section to screen readers.
	</Guideline>
	<Guideline kind="dont" name="typography/dont-skip-levels" title="An h4 just to change the size.">
		Jumping from `h2` to `h4` leaves a gap in the outline, and people who navigate by headings think they missed a section.
	</Guideline>
	<Guideline kind="do" name="typography/do-readable-measure" title="Keep lines between 45 and 75 characters.">
		At that length the eye finds the next line easily, even in long texts.
	</Guideline>
	<Guideline kind="dont" name="typography/dont-long-lines" title="Paragraphs as wide as the screen.">
		On a large monitor a line can pass 150 characters, and people lose their place.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="typography" type="HeadingProps" />

<Props file="typography" type="TextProps">
	`Heading` and `Text` also take the attributes of their HTML element, like `id` and `className`.
</Props>

## Styling hooks [#styling-hooks]

Restyle it without forking: target the attributes, or set the tokens on a parent, a skin or the element itself.

<StylingHooks
	slots={["heading", "text"]}
	attributes={[
		{ attr: "data-size", value: "display · lg · md · sm" },
		{ attr: "data-variant", value: "body · small" },
		{ attr: "data-drop-cap", value: "present when dropCap is on" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "—", description: "Headings and paragraphs don't take focus. Screen reader users jump between headings with their own keys (H in NVDA and JAWS, the rotor in VoiceOver)." }]}
	notes={[
		"Use one h1 per page, then go down one level at a time. Never skip a level to get a smaller size: change size instead.",
		"A heading should say what the section is about. People often scan a list of headings before reading anything.",
		"Keep paragraphs around 65 characters wide, and let them wrap. Don't truncate text people need to read.",
		"Don't use a heading only for big text. If it doesn't start a section, use Text with your own style.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Link", description: "Links inside sentences and on their own line.", href: "/docs/components/link" },
		{ title: "Separator", description: "A line between sections when space alone isn't enough.", href: "/docs/components/separator" },
		{ title: "Code block", description: "Code samples with highlighting and a copy button.", href: "/docs/components/code-block" },
	]}
/>


# VisuallyHidden (/docs/components/visually-hidden)

<ComponentMeta file="visually-hidden" pattern="Visually hidden content (clip pattern)" />

## Installation [#installation]

Set up Camaleo once ([Installation](/docs/installation)), then import it. It has no state, so it renders on the server.

<Import names="VisuallyHidden" />

## Anatomy [#anatomy]

One `<span>` shrunk to 1 × 1 px and clipped. It stays in the page and in the accessibility tree, so screen readers and translation tools still get the text.

<Anatomy
	tree={{
		slot: "visually-hidden",
		tag: "span",
		note: "position: absolute · 1 × 1 px · clip",
	}}
/>

### Why not `display: none` or `hidden`? [#why-not-display-none-or-hidden]

`display: none`, `visibility: hidden` and the `hidden` attribute remove the element from the accessibility tree as well as from the screen: nobody gets the text. `aria-hidden="true"` does the opposite of what you want here: it stays on screen and is skipped by screen readers. VisuallyHidden is the one way to keep text for assistive technology only.

## Examples [#examples]

Every example is a real file you can copy. Turn on a screen reader (VoiceOver, NVDA or TalkBack) to hear the hidden text, or inspect the accessibility tree in your browser's dev tools.

<Preview name="visually-hidden/basic" compact />

<ExampleGrid>
	<Example name="visually-hidden/vs-display-none" title="Four ways to hide" wide>
		Only VisuallyHidden takes text off the screen and keeps it for screen readers. `display: none` and `hidden` hide it from everyone; `aria-hidden` hides it only from screen readers.
	</Example>
	<Example name="visually-hidden/icon-button" title="aria-label or hidden text">
		For an `IconButton`, `aria-label` is enough. When part of the name is visible, add the rest as hidden text: it is real text, so browser translation translates it too.
	</Example>
	<Example name="visually-hidden/live-status" title="Announcing a change">
		Add to the cart. The count changes on screen, and a hidden `role="status"`, rendered empty from the start, tells screen reader users what happened.
	</Example>
	<Example name="visually-hidden/skip-link" title="Skip link">
		Click the hint, then press Tab. A `SkipLink` sits at the top of the page and appears over it on focus: use it to jump to the main content.
	</Example>
	<Example name="visually-hidden/focusable" title="Shown on focus">
		Click the hint, then press Tab. With `focusable`, the "Skip to results" link appears in place while it has focus, and Enter jumps past the filters. Without it, the text stays hidden even when focused.
	</Example>
	<Example name="visually-hidden/table-caption" title="Table caption">
		When the layout makes a table's purpose obvious, a hidden `<caption>` still names it, and names the scroll region on phones.
	</Example>
	<Example name="visually-hidden/hidden-label" title="A label you can't see">
		A lone search box next to a search button can hide its label. It must still be a real `<label>`; a placeholder disappears as soon as someone types.
	</Example>
	<Example name="visually-hidden/symbols" title="Symbols in words">
		"★ 4.8 (312)" means nothing read aloud. Hide the symbols with `aria-hidden` and give screen readers the whole sentence instead.
	</Example>
</ExampleGrid>

## In context [#in-context]

Hidden text is everywhere in a good interface. These are whole pieces of UI you can copy, in the skin you picked.

<ContextGrid>
	<Context name="visually-hidden/context-invoices" title="Invoice table" uses="Card · Table · Link · IconButton · VisuallyHidden" />
	<Context name="visually-hidden/context-header" title="Store header" uses="SkipLink · Button · Badge · VisuallyHidden" />
	<Context name="visually-hidden/context-pricing" title="Plan comparison" uses="Table · VisuallyHidden" />
</ContextGrid>

## Guidelines [#guidelines]

<Guidelines>
	<Guideline kind="do" name="visually-hidden/do-context-links" title="Finish the sentence for repeated links.">
		On screen, "Edit" sits in its row. In a list of links, "Edit invoice #4821" still makes sense.
	</Guideline>
	<Guideline kind="dont" name="visually-hidden/dont-repeated-links" title="Three links called Edit.">
		Screen reader users who list the links hear "Edit, Edit, Edit" and can't tell which is which.
	</Guideline>
	<Guideline kind="do" name="visually-hidden/do-visible-labels" title="Visible labels when there's room.">
		Everybody benefits from a label: people with memory or attention difficulties, and anyone checking what they typed.
	</Guideline>
	<Guideline kind="dont" name="visually-hidden/dont-hidden-labels" title="Hiding labels to save space.">
		Once the fields are filled, nothing on screen says which is which.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="visually-hidden"
	type="VisuallyHiddenProps"
	include={["children", "focusable", "role", "style"]}
	types={{ children: "ReactNode", style: "CSSProperties" }}
	describe={{
		children: "The text to read. Keep a leading space when it continues visible text, as in \"Edit\" + \" invoice #4821\".",
		role: "Use `\"status\"` (polite) or `\"alert\"` (urgent) to announce changes. Render it empty first, then set the text.",
		style: "Merged after the hiding styles, so it can override them. Don't, unless you mean to show the text.",
	}}
>
	Every attribute of a `<span>` passes through, like `id` (to point `aria-describedby` at it) or `aria-live`.
</Props>

## Styling hooks [#styling-hooks]

There is nothing to style: the hiding styles are inline, so no stylesheet can undo them by accident. With `focusable` they come from the stylesheet instead, because inline styles can't react to focus.

<StylingHooks
	slots={["visually-hidden"]}
	attributes={[
		{ attr: "data-slot", value: '"visually-hidden"' },
		{ attr: "data-focusable", value: "with focusable; hidden while nothing inside has focus" },
	]}
/>

## Accessibility [#accessibility]

<KeyboardTable
	keys={[{ key: "Tab", description: "VisuallyHidden takes no focus itself. A link or button inside it only belongs there with focusable, which shows it while it has focus; without it, it would get focus while staying invisible." }]}
	notes={[
		"The text stays in the accessibility tree: it joins the accessible name of the link or button around it.",
		"Without focusable it stays hidden on focus. For the jump to the main content use SkipLink; for a link that appears in place, like \"Skip to results\", use focusable.",
		"For live messages, the role=\"status\" element must be in the page before the text changes, or screen readers miss it.",
		"Hidden text is for context that sighted people get from the layout. If everyone needs it, show it.",
	]}
/>

## Related [#related]

<RelatedComponents
	items={[
		{ title: "Button", description: "IconButton needs a name: aria-label or hidden text.", href: "/docs/components/button" },
		{ title: "Link", description: "Links that make sense out of context.", href: "/docs/components/link" },
		{ title: "Toast", description: "Visible messages that are also announced.", href: "/docs/components/toast" },
	]}
/>


# Theme customizer (/docs/customizer)

<Customizer />

## What each choice sets [#what-each-choice-sets]

Every choice writes `--cml-*` tokens, nothing else. Untouched choices keep the skin's own values and stay out of the file.

| Choice | Tokens |
| --- | --- |
| Base skin, mode, brand | `styleName`, `mode` and `brand` on the `StyleProvider`; `createBrand` turns the brand into `--cml-brand-*` |
| Control radius | `--cml-radius-control`, `-sm`, `-lg` and `--cml-radius-field`; the last stop is `var(--cml-radius-pill)` |
| Surface radius | `--cml-radius-surface`, and `--cml-radius-popover` at 80% of it |
| Border width | `--cml-border-width`, `--cml-field-border-width` |
| Control height | `--cml-control-height`, `-sm`, `-lg`, `--cml-field-height`, `--cml-item-height`, all moved by the same amount |
| Fonts | `--cml-font-body`, `--cml-font-display` |
| Shadows | `--cml-shadow-surface`, `--cml-shadow-popover`, `--cml-card-shadow` |
| Motion off | `--cml-motion-distance: 0px`, `--cml-motion-scale: 1`, `--cml-press-translate: 0px`, the values the library uses for reduced motion |

## Override or new skin [#override-or-new-skin]

**Override** writes your changes on `[data-style="<skin>"]`, outside any layer. The library's CSS is all in `cml.*` layers, so unlayered CSS wins without `!important`, including over tokens the skin never sets. Keep importing the skin's CSS and passing its name.

**New skin** writes a skin of its own in `@layer cml.style`, the layer the 13 skins use: the base skin's token values with your changes on top. It copies tokens only; the base skin's scoped rules (bevels, dividers, glass blur) stay with the base skin's name. When you want the base skin's exact look, export an override. The preview always runs the file you are about to export.

The contrast pairs under the preview are measured in the rendered preview, the same way the library's matrix test reads them: text and brand text at 4.5:1, the focus ring and control borders at 3:1. See [Brand color](/docs/guides/brand-color) for why text on the brand always passes, and [Create a skin](/docs/guides/create-a-skin) to take a new skin further.


# Accessibility (/docs/guides/accessibility)

<Learn>

- What you get from every component without extra work
- How the library is tested in all 13 skins, in light and dark, with five hard brand colors
- The measured contrast of each skin's text and control colors
- Where an authentic look and accessibility disagree, and which one wins

</Learn>

The target is WCAG 2.2 AA in every skin, in light and dark, with any brand color. A skin can change shape, depth, type and motion; it can't take away a name, a key or a focus ring.

## What every component guarantees [#what-every-component-guarantees]

- **Keyboard.** Each component follows a WAI-ARIA Authoring Practices pattern and gets its keyboard model from the primitive under it (Base UI, or React Aria for dates). Arrows move inside a widget, Tab moves between widgets, Escape closes popups and returns focus to the trigger.
- **Focus.** Focus is drawn with `outline`, never only `box-shadow`, so it survives forced colors. Its color, `--cml-focus-ring`, is tested at 3:1 or more against the surface in every skin.
- **Names.** Built-in buttons and regions have names (close, clear, show password, page 3…) that you can translate with `MessagesProvider`. Icon-only controls you build still need an `aria-label`.
- **Targets.** Checkboxes, radios, links in breadcrumbs and other small controls keep a pointer target of at least 24 × 24 px, even in dense skins.
- **Reduced motion.** It reduces, it doesn't remove: under `prefers-reduced-motion`, distances and scales go to zero, short fades stay, panels open at once, the skeleton shimmer stops and an indeterminate progress bar pulses in place.
- **Forced colors.** Components keep a transparent border that becomes visible in Windows high contrast, and selected states switch to system colors (`Highlight`, `CanvasText`).
- **Reduced transparency.** `glass` and `cupertino` swap their translucent surfaces for opaque ones under `prefers-reduced-transparency: reduce`, and in browsers without `backdrop-filter`.
- **Right to left.** Components flip with `DirectionProvider`; see [Languages & RTL](/docs/guides/i18n#right-to-left).

## How it is tested [#how-it-is-tested]

The tests live in `packages/react/test` and run in a real browser (Vitest browser mode with Playwright).

- **The matrix** (`matrix.test.tsx`) renders a showcase of every component in 13 skins × light and dark × 5 hard brand colors (`#2563eb`, `#facc15`, `#22d3ee`, `#ff7f50` and `#808080`): 130 scopes. In each one it runs axe with the WCAG 2.0, 2.1 and 2.2 A/AA rules, checks that the focus ring and control borders reach 3:1, that the danger, success, warning and info tones reach 4.5:1, and then opens 17 popups (dialog, menu, select, date picker, toast…) one by one to check that each keeps the skin through its portal and passes axe too. That is 2,340 runs.
- **Text over images.** axe can't measure text over gradients and glass, and reports it as "incomplete". The matrix measures those nodes on real pixels instead (`pixel-contrast.ts`): two screenshots, with and without the text, and the worst glyph pixel against the background behind it.
- **Keyboard** (`keyboard.test.tsx`): 30 tests that drive the components with real key presses, from Space on a checkbox to PageUp in a calendar.
- **The docs.** Every page of this site, with its live examples, is checked with axe in 4 skins, light and dark, at desktop, tablet and phone widths, in both languages.

## Contrast report [#contrast-report]

The table below is measured, not typed: `apps/docs/scripts/contrast-report.mjs` loads `tokens.css` and each skin's CSS in a browser, resolves the tokens with each of the five matrix brand colors, and keeps the **lowest** ratio of the five. Numbers are rounded down, so 4.499 shows as 4.49.

What it measures, all against the skin's page color `--cml-surface` unless noted:

- **Text, 4.5:1 or more:** `--cml-fg` (body text), `--cml-fg-secondary`, `--cml-fg-muted`, `--cml-accent-text` (brand-colored text and links), `--cml-accent-fg` on `--cml-accent` (text on a solid brand button), and the `--cml-danger`, `--cml-success` and `--cml-warning` tones.
- **Non-text, 3:1 or more:** `--cml-border-control` (the edge of fields and choices) and `--cml-focus-ring`.

It doesn't measure text on raised surfaces, hover states or glass panels over the backdrop; the matrix covers those on rendered components.

<ContrastTable
  label="Text on the page color, target 4.5:1"
  ids={["fg", "fgSecondary", "fgMuted", "accentText", "danger", "success", "warning"]}
/>

<ContrastTable
  label="Brand fill (target 4.5:1) and edges (target 3:1)"
  ids={["accentFg", "borderControl", "focusRing"]}
/>

Every pair meets its target in every skin and mode. Run `node scripts/contrast-report.mjs` in `apps/docs` after changing a skin to refresh the numbers.

## Authentic or accessible [#authentic-or-accessible]

Some styles fail contrast by nature: neumorphism has no edges, glass puts text on whatever is behind it, a classic desktop OS draws a 1 px dotted focus box. The project decided (decision 9 in the plan) that **every skin is accessible by default**, and that an authentic variant would be opt-in and labelled "doesn't guarantee AA". No authentic variant ships yet.

| Skin | The authentic look | What Camaleo does by default |
| --- | --- | --- |
| `neumorphism` | Controls shaped by light and shade only, no edges | A 1 px border of 3:1 or more on inputs and choices; buttons are named by their text |
| `glass` | Translucent panels over any background | Backdrop blobs kept light (dark: dark) enough that text holds 4.8:1 at their peak; opaque under reduced transparency |
| `clay` | Soft pastel pieces with no outline | Fields and choices keep an edge of 3:1 or more |
| `cupertino` | Frosted chrome on menus and popups | Dark glass at 94% opacity so text keeps 4.5:1; opaque fallback |
| `y2k` | Glossy "jelly" buttons with text over the shine | Text sits only on the flat accent; the gloss stays above and below it |
| `retro` | Dotted focus rectangle | Kept inside buttons, tabs and toggles (in the label color); fields get a solid 2 px ring outside the bevel |

<Callout kind="caution">

A token or rule you change can break what the tests guarantee. After any color change, rerun the matrix (`pnpm --filter @camaleo/react test`) or at least this report.

</Callout>

<Checklist>

- Icon-only buttons you add have an `aria-label`
- Custom colors come from tokens, so they keep their tested pairs
- Animations you add respect `prefers-reduced-motion`
- New popups keep the skin (use `PortalScope` for your own portals)
- The contrast report and the matrix still pass after a skin change

</Checklist>


# Brand color (/docs/guides/brand-color)

<Learn>

- How `createBrand` turns one color into 34 tokens
- Why text on the brand is always readable, for any color you pick
- How the same color lands in different skins, and which colors are hardest

</Learn>

## One prop [#one-prop]

Set `brand` on a `StyleProvider` to any CSS color: hex, `rgb()`, `oklch()`, a named color. Leave it out and it inherits from the parent provider; at the top, the default is blue `#2563eb`.

<FileCode file="app/providers.tsx" code={`
  <StyleProvider styleName="minimal" brand="#3fa34d">
    <App />
  </StyleProvider>
`} />

The brand bar at the top of this site does the same for every preview on the page. Pick a color there and come back.

## The 11-step scale [#the-11-step-scale]

`createBrand` (from `@camaleo/styles`) converts the color to OKLCH, keeps its hue and builds steps 50 to 950 at fixed lightness, from 0.97 down to 0.24. Light steps take a small share of the color's chroma, the middle steps all of it; anything outside sRGB is clamped back in. Try a color:

<Preview name="guide-brand/scale" />

Each step becomes three tokens, plus `--cml-brand` with the color you passed:

| Token | What it is |
| --- | --- |
| `--cml-brand-600` | The step's color |
| `--cml-brand-600-fg` | Black or white, whichever reads better on it |
| `--cml-brand-600-hover` | The step moved 0.09 in lightness, away from its text color |

You can call it yourself, for example to write the tokens into a static CSS file at build time:

<FileCode file="scripts/brand.ts" code={`
  import { createBrand } from "@camaleo/styles";

  const vars = createBrand("#3fa34d");
  // { "--cml-brand": "#3fa34d", "--cml-brand-50": "#…", "--cml-brand-50-fg": "#000000", … }
  const css = \`:root { \${Object.entries(vars).map(([k, v]) => \`\${k}: \${v};\`).join(" ")} }\`;
`} />

<Callout kind="caution">

`createBrand` throws on a string it can't parse. If the color comes from users, validate it first (or catch the error and fall back to a default).

</Callout>

## How contrast is guaranteed [#how-contrast-is-guaranteed]

Text on a step is never "the brand's text color": it is black or white, picked per step by WCAG contrast. Against any color, the better of black and white reaches at least **4.58:1**, so every `-fg` passes 4.5:1, whatever the input. Hover colors move away from that text color, so hovering never lowers contrast.

Skins don't use the raw scale; they map it to semantic tokens and pick the steps that work on their surfaces:

| Skin | `--cml-accent` (light / dark) |
| --- | --- |
| minimal, and skins that keep the default | 600 / 400 |
| cupertino | 600 in both modes |
| neubrutalism | 500 in both modes |
| material | 600 / 300 |
| progressive, y2k | 600 / 500 |
| retro | 800 / 600 |
| editorial | the ink color; the brand marks focus and selection |

Brand text on the page (links, the focus ring, info) uses `--cml-accent-text`, which is 700 in light mode and 300 in dark in the default skin. The matrix test checks that it stays at 4.5:1 on the surface, and that the focus ring and control borders stay at 3:1.

## The same color in 3 skins [#the-same-color-in-3-skins]

One brand, three skins: each one picks its own step, so a yellow that is a fill in one skin can be a dark gold in another. Switch the mode in the "preview in" bar too.

<Preview name="guide-brand/three-skins" />

## Hard colors [#hard-colors]

Most colors are easy. These five are the ones that break naive palettes, and the matrix test runs every skin, in light and dark, with each of them:

| Color | Why it is hard |
| --- | --- |
| Blue `#2563eb` | The default: black text up to step 500, white from 600 (5.3:1) |
| Yellow `#facc15` | Very light hue: step 600 is a dark gold (`#866c00`) and yellow text on white would fail |
| Cyan `#22d3ee` | Light and saturated: white on its step 600 is 4.86:1, the closest of the five to the floor |
| Coral `#ff7f50` | Black and white read almost the same around steps 500 and 600 (5.35 and 5.46:1) |
| Gray `#808080` | No chroma at all, so the scale is pure greys |

<Callout>

If your brand is a light color like yellow, expect skins that use step 500 or 600 as a fill to show it darker than your logo. That is the price of readable text; use your exact color in illustrations and marketing, not in controls.

</Callout>

<Checklist>

- The brand is set once, on the top provider (or on `<html>` with `styleScopeProps`)
- Colors that come from users are validated before they reach `createBrand`
- You change `--cml-accent`, not a brand step, when you want another shade
- You checked your color in light and dark, in every skin you ship

</Checklist>


# Create a skin (/docs/guides/create-a-skin)

<Learn>

- Which tokens make a look, and which you can leave at their defaults
- How to write the file: `@layer cml.style`, `light-dark()`, `@scope … to ([data-style])`
- How to test contrast the way the library tests its own 13 skins

</Learn>

## Watch one being built [#watch-one-being-built]

This is "sunset", the skin written on this page. Each step adds to the file; the demo runs it with the brand and mode of the "preview in" bar.

<CodeSwitch
  name="guide-tokens/invite"
  label="Build step"
  cumulative
  options={[
    { kicker: "Start", title: "Defaults", note: "a name with no tokens yet looks exactly like minimal.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
        }
      }` },
    { kicker: "Step 1", title: "Type and color", note: "fonts, surfaces, text and borders, each with a light and a dark value.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
          --cml-font-body: "Fraunces", Georgia, serif;
          --cml-surface: light-dark(#fff7ef, #1c1410);
          --cml-surface-raised: light-dark(#fffdf9, #261b15);
          --cml-fg: light-dark(#2b1a14, #f6e9df);
          --cml-fg-secondary: light-dark(#5a4034, #d9c4b6);
          --cml-fg-muted: light-dark(#7a5a4a, #b39a8a);
          --cml-border: var(--cml-fg);
          --cml-border-control: light-dark(#8a6a58, #9a7f6e);
          --cml-accent: light-dark(var(--cml-brand-700), var(--cml-brand-300));
          --cml-accent-fg: light-dark(var(--cml-brand-700-fg), var(--cml-brand-300-fg));
          --cml-accent-hover: light-dark(var(--cml-brand-700-hover), var(--cml-brand-300-hover));
        }
      }` },
    { kicker: "Step 2", title: "Shape and depth", note: "thicker borders, round controls and a hard offset shadow, added to step 1.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
          /* …step 1, then: */
          --cml-border-width: 2px;
          --cml-radius-control: 20px;
          --cml-radius-field: 12px;
          --cml-radius-surface: 24px;
          --cml-card-shadow: 6px 6px 0 var(--cml-border);
          --cml-shadow-popover: 4px 4px 0 var(--cml-border);
        }
      }` },
    { kicker: "Step 3", title: "A scoped rule", note: "structure a token can't express, limited to this skin and stopped at nested islands.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        /* …steps 1 and 2, then: */
        @scope ([data-style="sunset"]) to ([data-style]) {
          [data-slot="card-header"] {
            border-bottom: var(--cml-border-width) solid var(--cml-border);
          }
        }
      }` },
  ]}
/>

<Steps>

## Name it and open the layer [#name-it-and-open-the-layer]

Pick a lowercase name and write everything inside `@layer cml.style`, the layer the 13 skins use. That puts your skin above the defaults and the component rules, and leaves your app's unlayered CSS free to override it.

<FileCode file="sunset.css" code={`
  @layer cml.style {
    [data-style="sunset"] {
      /* tokens go here */
    }
  }
`} />

## Set the tokens that make the look [#set-the-tokens-that-make-the-look]

No token is required: anything you leave out keeps the `minimal` default. In practice a look comes from these groups, roughly in this order of impact:

| Group | Tokens to start with |
| --- | --- |
| Type | `--cml-font-body`, and `--cml-font-display` / `--cml-font-control` if they differ |
| Surfaces and text | `--cml-surface`, `--cml-surface-raised`, `--cml-fg`, `--cml-fg-secondary`, `--cml-fg-muted` |
| Lines | `--cml-border`, `--cml-border-control`, `--cml-border-width` |
| Accent | `--cml-accent`, `--cml-accent-fg`, `--cml-accent-hover`: which brand steps you use |
| Shape | `--cml-radius-control`, `--cml-radius-field`, `--cml-radius-surface` |
| Depth | `--cml-shadow-control`, `--cml-shadow-surface`, `--cml-shadow-popover`, `--cml-card-shadow` |
| Density | `--cml-control-height`, `--cml-field-height`, `--cml-surface-padding` |

Write every color as `light-dark(light, dark)` so one declaration covers both modes. For the accent, pick brand **steps**, never a fixed color, and always pair a step with its `-fg` and `-hover`: that is what keeps text readable for any brand. The [Tokens](/docs/guides/tokens) page lists all of them with their defaults.

<Callout>

Need a fill that is neither surface nor accent? Declare your own token next to the others (neubrutalism has `--cml-ink` and `--cml-highlight`) and use it in your scoped rules.

</Callout>

## Add scoped rules, if you must [#add-scoped-rules-if-you-must]

Some looks need structure a token can't express: a divider, a bevel, a different hover. Put those rules in `@scope` with your skin as the root and `to ([data-style])` as the limit, so they never reach a nested island in another skin.

<FileCode file="sunset.css" code={`
  @layer cml.style {
    @scope ([data-style="sunset"]) to ([data-style]) {
      [data-slot="card-header"] {
        border-bottom: var(--cml-border-width) solid var(--cml-border);
      }
    }
  }
`} />

<Callout kind="caution">

Every rule you add is a rule you must check in both modes, with reduced motion and in forced colors. Prefer a component token (they are listed under **Styling hooks** on each component page) over a rule.

</Callout>

## Use it [#use-it]

Import the file after `base.css` and pass the name. `styleName` takes any name your CSS targets, so TypeScript is happy without a cast:

<FileCode file="app/providers.tsx" code={`
  import "@camaleo/styles/base.css";
  import "./sunset.css";
  import { StyleProvider } from "@camaleo/react";

  <StyleProvider styleName="sunset" mode="system">
    <App />
  </StyleProvider>
`} />

## Test the contrast [#test-the-contrast]

The library runs every skin × light and dark × five hard brand colors (blue, yellow, cyan, coral, gray) through axe and a set of contrast checks. Do the same for yours. The checks read the computed tokens, so they need a real browser (Vitest browser mode or Playwright):

<FileCode file="sunset.test.tsx" code={`
  import "@camaleo/styles/base.css";
  import "./sunset.css";
  import { StyleProvider } from "@camaleo/react";
  import { wcagContrast } from "culori";
  import { expect, it } from "vitest";
  import { render } from "vitest-browser-react";
  import { Screens } from "./screens";

  // Resolves a token to a color by letting the browser compute it.
  function token(scope: Element, name: string) {
    const probe = document.createElement("span");
    probe.style.color = \`var(\${name})\`;
    scope.append(probe);
    const color = getComputedStyle(probe).color;
    probe.remove();
    return color;
  }

  for (const mode of ["light", "dark"] as const)
    for (const brand of ["#2563eb", "#facc15", "#22d3ee", "#ff7f50", "#808080"])
      it(\`sunset / \${mode} / \${brand}\`, async () => {
        // Your own screens, in the skin, mode and brand under test.
        const screen = await render(
          <StyleProvider styleName="sunset" mode={mode} brand={brand}>
            <Screens />
          </StyleProvider>,
        );
        const root = screen.container.firstElementChild as Element;
        const surface = token(root, "--cml-surface");
        expect(wcagContrast(token(root, "--cml-fg-muted"), surface)).toBeGreaterThanOrEqual(4.5);
        expect(wcagContrast(token(root, "--cml-border-control"), surface)).toBeGreaterThanOrEqual(3);
        expect(wcagContrast(token(root, "--cml-focus-ring"), surface)).toBeGreaterThanOrEqual(3);
      });
`} />

Check `--cml-danger`, `--cml-success`, `--cml-warning` and `--cml-info` against your surface too (4.5:1): their defaults were tuned for white and near-black, and a tinted surface can push them under. Sunset's warm surfaces keep them all above 4.7:1.

</Steps>

## The complete file [#the-complete-file]

The whole skin from this page, ready to copy:

<FileCode file="sunset.css" code={`
  /* Sunset: warm paper, ink outlines, round controls and a hard offset shadow. */
  @layer cml.style {
    [data-style="sunset"] {
      --cml-font-body: "Fraunces", Georgia, serif;

      --cml-surface: light-dark(#fff7ef, #1c1410);
      --cml-surface-raised: light-dark(#fffdf9, #261b15);
      --cml-fg: light-dark(#2b1a14, #f6e9df);
      --cml-fg-secondary: light-dark(#5a4034, #d9c4b6);
      --cml-fg-muted: light-dark(#7a5a4a, #b39a8a);
      --cml-border: var(--cml-fg);
      --cml-border-control: light-dark(#8a6a58, #9a7f6e);
      --cml-accent: light-dark(var(--cml-brand-700), var(--cml-brand-300));
      --cml-accent-fg: light-dark(var(--cml-brand-700-fg), var(--cml-brand-300-fg));
      --cml-accent-hover: light-dark(var(--cml-brand-700-hover), var(--cml-brand-300-hover));

      --cml-border-width: 2px;
      --cml-radius-control: 20px;
      --cml-radius-field: 12px;
      --cml-radius-surface: 24px;
      --cml-card-shadow: 6px 6px 0 var(--cml-border);
      --cml-shadow-popover: 4px 4px 0 var(--cml-border);
    }

    @scope ([data-style="sunset"]) to ([data-style]) {
      [data-slot="card-header"] {
        border-bottom: var(--cml-border-width) solid var(--cml-border);
      }
    }
  }
`} />

<Checklist>

- Text at least 4.5:1 and control borders and the focus ring at least 3:1, in light and dark
- The five hard brand colors tried in both modes
- The focus ring visible on every surface you added
- Scoped rules checked with reduced motion and forced colors
- The fonts loaded wherever the skin is used

</Checklist>


# Dark mode (/docs/guides/dark-mode)

<Learn>

- What `mode="light" | "dark" | "system"` does, and what inherits it
- Why there is no flash on first paint, and how to keep it that way with a saved choice
- How to color the browser chrome with `theme-color`

</Learn>

## Try it [#try-it]

This island sets `mode` on its own `StyleProvider`, whatever the "preview in" bar says. Pick **System** and change your OS setting: it follows without a reload.

<Preview name="guide-dark/modes" />

## How it works [#how-it-works]

Every color token is written with `light-dark()`: one value for each mode in a single declaration. The browser picks the side from `color-scheme`, and `data-mode` sets it:

<FileCode file="tokens.css (excerpt)" lang="css" code={`
  :root { color-scheme: light dark; }
  [data-mode="light"] { color-scheme: light; }
  [data-mode="dark"] { color-scheme: dark; }
  [data-mode="system"] { color-scheme: light dark; }

  :where(:root, [data-style]) {
    --cml-surface: light-dark(#ffffff, #09090b);
    --cml-fg: light-dark(#09090b, #fafafa);
  }
`} />

`color-scheme: light dark` means "follow `prefers-color-scheme`". `color-scheme` is inherited, so a provider without `mode` simply takes its parent's, and the page root follows the system with no script at all. Native parts (scrollbars, date pickers, autofill) follow too.

| `mode` | `data-mode` | Result |
| --- | --- | --- |
| left out | none | Inherits from the parent; at the root, follows the system |
| `"system"` | `system` | Follows the system, even inside a light or dark parent |
| `"light"` | `light` | Always light |
| `"dark"` | `dark` | Always dark |

<Callout>

Dialogs, menus and toasts render in a portal. They carry the provider's mode through React context, so a popup opened from a dark island is dark too.

</Callout>

<Steps>

## Pick a default [#pick-a-default]

For most apps, leave `mode` out or set `"system"` on the top provider: the page matches the OS from the first byte. Use a fixed mode for areas that must stay one way, such as a dark code panel or a light print preview.

<FileCode file="app/providers.tsx" code={`
  <StyleProvider styleName="minimal" mode="system">
    <App />
    <StyleProvider styleName="minimal" mode="dark">
      <CodePanel />
    </StyleProvider>
  </StyleProvider>
`} />

## Save the visitor's choice without a flash [#save-the-visitors-choice-without-a-flash]

A toggle that stores the choice in `localStorage` and applies it after hydration paints the wrong mode first. Render the saved mode on the server instead: keep it in a cookie and spread it on `<html>` with `styleScopeProps`, which is safe to call in a Server Component.

<FileCode file="app/layout.tsx" code={`
  import { cookies } from "next/headers";
  import { styleScopeProps } from "@camaleo/react/style-scope";

  export default async function RootLayout({ children }: { children: React.ReactNode }) {
    const saved = (await cookies()).get("mode")?.value;
    const mode = saved === "light" || saved === "dark" ? saved : "system";
    return (
      <html lang="en" {...styleScopeProps({ styleName: "minimal", mode })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

The toggle writes the cookie and the attribute; nothing has to re-render:

<FileCode file="mode-toggle.tsx" code={`
  "use client";

  export function setMode(mode: "light" | "dark" | "system") {
    document.cookie = \`mode=\${mode}; path=/; max-age=31536000; samesite=lax\`;
    document.documentElement.setAttribute("data-mode", mode);
  }
`} />

<Callout kind="caution">

Don't give your inner providers a `mode` if the root owns it: a fixed `mode` on a nested provider wins over the toggle. And reading `cookies()` makes the route render per request.

</Callout>

On a static site or a single-page app with no server, the only flash-free option is a tiny inline script in `<head>` that runs before the first paint:

<FileCode file="index.html" lang="html" code={`
  <script>
    try {
      document.documentElement.setAttribute("data-mode", localStorage.getItem("mode") || "system");
    } catch {}
  </script>
`} />

## Color the browser chrome [#color-the-browser-chrome]

`theme-color` tints the address bar and the task switcher on mobile browsers. Give it one value per scheme, using your skin's surface color. In Next, export it from the root layout:

<FileCode file="app/layout.tsx" code={`
  import type { Viewport } from "next";

  export const viewport: Viewport = {
    themeColor: [
      { media: "(prefers-color-scheme: light)", color: "#ffffff" },
      { media: "(prefers-color-scheme: dark)", color: "#09090b" },
    ],
  };
`} />

The media queries follow the system. If visitors can force a mode, the toggle should also set the `content` of both `theme-color` tags to the forced mode's color.

</Steps>

<Checklist>

- The top provider uses `"system"` or no `mode`
- A saved choice is rendered by the server, or applied by an inline script before paint
- Only areas that must stay one way have a fixed `mode`
- `theme-color` matches the skin's surface in both modes

</Checklist>


# FAQ (/docs/guides/faq)

<Learn>

- What it costs: JavaScript, CSS and fonts
- Where it runs: server rendering, Tailwind, mixed skins and browsers
- The licence, the trademarks and how to report a bug

</Learn>

## Does it tree-shake? How big is it? [#does-it-tree-shake-how-big-is-it]

The JavaScript does. `@camaleo/react` is ESM only, marked `"sideEffects": false`, and built one file per component, so a bundler keeps only what you import. Each component also has its own entry point (`@camaleo/react/button`) if you prefer explicit imports.

The CSS is split by skin, not by component. `base.css` holds the tokens and the structure of every component: about 28 kB gzipped, before minification. Each skin adds one file, between about 3 kB (`neumorphism`, `retro-pixel`) and 11 kB (`material`) gzipped. Skins you don't import cost nothing.

## Which skins need web fonts? [#which-skins-need-web-fonts]

None of them bundle fonts, and every font stack ends in a system font, so nothing breaks without them. To look as designed, load each skin's families: the table of fonts per skin, and how to load them with `next/font`, are in [Skins & switching](/docs/guides/skins#load-the-fonts).

## Does it work with Server Components and SSR? [#does-it-work-with-server-components-and-ssr]

Yes. Layout and display pieces are Server Components, the skin is set on `<html>` by a plain function, and dark mode needs no script. See [Server Components and SSR](/docs/guides/ssr).

## Can I mix skins on one page? [#can-i-mix-skins-on-one-page]

Yes, that is what `StyleProvider` is for. Each provider renders a `<div data-style>` and is an island: it starts from the defaults instead of inheriting its parent's look, and its popups keep its skin. Import the CSS of every skin you use. The brand color does flow into nested islands unless they set their own.

<FileCode file="app/page.tsx" code={`
  <StyleProvider styleName="editorial">
    <Article />
    <StyleProvider styleName="retro">
      <Guestbook />
    </StyleProvider>
  </StyleProvider>
`} />

## Do I need Tailwind? [#do-i-need-tailwind]

No. The skins are plain CSS in cascade layers and work in any React app. If you already use Tailwind CSS v4, see [Tailwind CSS](/docs/guides/tailwind) for the layer order and the token mapping.

## Which browsers are supported? [#which-browsers-are-supported]

The CSS uses a few recent features. These are the versions where each one shipped:

| Feature | Used for | Chrome / Edge | Safari | Firefox |
| --- | --- | --- | --- | --- |
| `light-dark()` | Every color, both modes | 123 | 17.5 | 120 |
| `@scope` | Each skin's structural rules | 118 | 17.4 | 146 |
| Relative colors (`oklch(from …)`) | Glass backdrop tinted by the brand | 119 | 18 | 128 |
| `@property` | `Stack` and `Grid` values that don't inherit | 85 | 16.4 | 128 |
| `corner-shape` | Squircle corners in `cupertino` | 139 | — | — |
| `backdrop-filter` | Glass in `glass` and `cupertino` | 76 | 18 | 103 |

`light-dark()` is the hard floor: without it, colors don't resolve. Without `@scope`, a skin keeps its tokens but loses its structural rules and looks half applied. `corner-shape` and `backdrop-filter` degrade on their own: corners stay round, and glass turns opaque through an `@supports` fallback.

## Can I use it in a commercial project? [#can-i-use-it-in-a-commercial-project]

Yes. Camaleo is open source under the MIT licence: use it, change it and ship it, keeping the copyright notice.

## Is it affiliated with Google or Apple? [#is-it-affiliated-with-google-or-apple]

No. `material` is inspired by Material Design and `cupertino` by Apple's Human Interface Guidelines. Camaleo isn't affiliated with or endorsed by Google or Apple, and uses none of their fonts, icons or trademarks (`cupertino` uses Inter, not SF Pro).

## How do I report a bug? [#how-do-i-report-a-bug]

Open an issue on [GitHub](https://github.com/GuilhermeDeitos/camaleo/issues). It helps a lot to include:

- the component, the skin, the mode (light or dark) and the brand color;
- your browser and its version, and React and Next.js versions if they matter;
- the smallest code that shows the problem, or the docs example that already does;
- for accessibility bugs, the assistive technology (screen reader, zoom, high contrast) and what you expected to hear or see.


# Forms (/docs/guides/forms)

<Learn>

- What `Field` connects for you, and what is left to your markup
- Two ways to validate: on the field, or with your own state
- When to add an `ErrorSummary`, and where focus goes after a failed submit
- How to plug in react-hook-form and zod without losing any of it

</Learn>

<Steps>

## Wire a field [#wire-a-field]

`Field` ties a label, a description and an error to the control inside it. `FieldLabel` becomes a `<label>` for the control, and `FieldDescription` and `FieldError` are linked with `aria-describedby`, so a screen reader reads the hint and the error when the control gets focus.

<FileCode file="signup.tsx" code={`
  import { Field, FieldDescription, FieldError, FieldLabel, Input } from "@camaleo/react";

  <Field validationMode="onBlur">
    <FieldLabel>Work email</FieldLabel>
    <Input type="email" autoComplete="email" required />
    <FieldDescription>We reply within one business day.</FieldDescription>
    <FieldError match="valueMissing">Enter your work email.</FieldError>
  </Field>
`} />

`Input`, `Textarea`, `NativeSelect`, `Select`, `Combobox`, `NumberField`, `Checkbox`, `Switch`, `Slider` and the date fields all join the `Field` they sit in. Group related fields with `Fieldset` and `FieldsetLegend`. For a checkbox or switch on its own, a plain `Label` around it is enough.

## Validate on the field [#validate-on-the-field]

`Field` runs the browser's constraint checks (`required`, `type="email"`, `minLength`…) and your own `validate` function. `FieldError` shows the message; `match` picks which failure it reports, and a `validate` result is shown as is.

`validationMode` sets when it checks. Base UI's default, `"onSubmit"`, is meant for its own `Form` component, which Camaleo doesn't wrap, so set `"onBlur"` or `"onChange"` on the `Field`, or let a form library decide (below).

<Preview name="field/validate" compact />

<FileCode file="username.tsx" code={`
  <Field
    validationMode="onChange"
    validate={(value) => (String(value ?? "").length < 3 ? "Use at least 3 characters." : null)}
  >
    <FieldLabel>Username</FieldLabel>
    <Input autoComplete="username" />
    <FieldError />
  </Field>
`} />

When the result comes from somewhere else (a server, a form library), set `invalid` on the `Field` and pass the same flag to `match` on `FieldError`, which then shows its children as they are. That is how the recipe below works.

<Callout kind="tip">

Write errors that say how to fix the problem: "Enter an email like ana@company.com", not "Invalid input". Each component page has a do/don't pair about it.

</Callout>

## Summarize the errors [#summarize-the-errors]

When a form has more than a few fields, a failed submit should land on an `ErrorSummary` at the top: a danger alert whose title says how many fields need fixing, with one link per error. Each link moves focus to its control.

<FileCode file="checkout.tsx" code={`
  const summary = useRef<HTMLDivElement>(null);

  // After a failed submit, focus the summary so it is read first.
  useEffect(() => {
    if (failedAttempts > 0) summary.current?.focus();
  }, [failedAttempts]);

  {errors.length > 0 && (
    <ErrorSummary
      ref={summary}
      tabIndex={-1}
      title={\`Fix \${errors.length} fields to continue.\`}
      errors={errors.map((e) => ({ target: e.id, message: e.message }))}
    />
  )}
`} />

`target` is the `id` of the control. Give each control an id from `useId()`, so two copies of the form on one page never collide.

## Use react-hook-form and zod [#use-react-hook-form-and-zod]

react-hook-form keeps the values and runs the schema; Camaleo shows the result. Wrap each control in a `Controller`, pass `fieldState.invalid` to the `Field`, and spread `field` on the control:

<FileCode file="request-demo.tsx" code={`
  const { control, handleSubmit } = useForm<Values>({
    resolver: zodResolver(schema),
    defaultValues: { email: "" },
    // The ErrorSummary takes focus, not the first invalid field.
    shouldFocusError: false,
  });

  <Controller
    name="email"
    control={control}
    render={({ field, fieldState }) => (
      <Field invalid={fieldState.invalid}>
        <FieldLabel>Work email</FieldLabel>
        <Input {...field} id={ids.email} type="email" autoComplete="email" />
        <FieldError match={fieldState.invalid}>{fieldState.error?.message}</FieldError>
      </Field>
    )}
  />
`} />

<Callout kind="caution">

Set `shouldFocusError: false` when the form has an `ErrorSummary`. Otherwise react-hook-form moves focus to the first invalid field first, and people who use a screen reader never hear the summary.

</Callout>

A `Checkbox` reports `checked` instead of `value`, so connect it by hand: `checked={field.value}`, `onCheckedChange={field.onChange}` and `ref={field.ref}`.

</Steps>

## A complete form [#a-complete-form]

Everything above in one form: five fields, a schema, the summary with focus, and a confirmation that takes focus when the form is gone. Send it empty, then fix the fields one by one. Open the Code tab for the whole file.

<Preview name="guideb-forms/complete" />

<Checklist>

- Every control has a visible label, not just a placeholder
- Each error says how to fix it, in the field and in the summary
- After a failed submit, focus lands on the summary; each link reaches its field
- `noValidate` on the `<form>`, so browser bubbles don't compete with your messages
- Ids come from `useId()`, and `autoComplete` is set on personal data

</Checklist>


# Languages & RTL (/docs/guides/i18n)

<Learn>

- How `MessagesProvider` translates built-in texts, and how to change a few of them
- Every message key, in English and Portuguese
- Which locale the date components use, and how to set it
- How `DirectionProvider` turns a page right to left in every skin

</Learn>

## Built-in texts [#built-in-texts]

Most text in a Camaleo interface is yours: labels, titles, button text. A few components also bring texts of their own, like a close button's name, an empty table's message or "Page 3" for a screen reader. Those are English by default.

Put one `MessagesProvider` near the root to change them. Pick a language below: only the component texts change.

<Preview name="guideb-i18n/messages" />

<FileCode file="app/layout.tsx" code={`
  import { MessagesProvider } from "@camaleo/react";

  <MessagesProvider locale="pt-BR">{children}</MessagesProvider>
`} />

`locale` picks a bundled set: `"en"` (the default) or `"pt-BR"`. A prop on the component always wins over the provider, so `<Pagination previousLabel="Back" />` keeps "Back".

## Change a few texts [#change-a-few-texts]

`messages` takes any subset of the keys. Each group you pass is merged over the set below it, so you only write what changes:

<FileCode file="app/layout.tsx" code={`
  <MessagesProvider
    locale="pt-BR"
    messages={{ drawer: { close: "Fechar painel" }, dataTable: { empty: "Nenhum pedido ainda." } }}
  >
    {children}
  </MessagesProvider>
`} />

Providers nest. An inner provider without `locale` starts from its parent's texts, which is handy for one area with its own wording:

<FileCode file="app/orders/layout.tsx" code={`
  <MessagesProvider messages={{ dataTable: { empty: "No orders match these filters." } }}>
    {children}
  </MessagesProvider>
`} />

For a language Camaleo doesn't bundle, write a full set typed as `Messages` and pass it as `messages`. The type makes sure no key is missing.

## Server or client [#server-or-client]

Some messages are functions, like `pagination.page(3)` → "Page 3". React can't pass functions from a Server Component to a client one, so:

- From a Server Component (a root layout), pass `locale` and string-only `messages`.
- To override a function, put the provider in a client component:

<FileCode file="app/messages.tsx" code={`
  "use client";
  import { MessagesProvider } from "@camaleo/react";

  export function AppMessages({ children }: { children: React.ReactNode }) {
    return (
      <MessagesProvider
        locale="pt-BR"
        messages={{ pagination: { page: (page) => \`Ir para a página \${page}\` } }}
      >
        {children}
      </MessagesProvider>
    );
  }
`} />

Read the texts in your own components with `useMessages()` (client) or `<Message pick="spinner.label" />` (server). See [Server Components and SSR](/docs/guides/ssr#the-message-helper).

## Every message key [#every-message-key]

This is the `Messages` interface from `packages/react/src/messages.tsx`, with the bundled `en` and `ptBR` values. Function keys show the result of a sample call.

| Key | English | Português |
| --- | --- | --- |
| `breadcrumb.label` | Breadcrumb | Trilha de navegação |
| `breadcrumb.more` | More pages | Mais páginas |
| `carousel.label` | Carousel | Carrossel |
| `carousel.previous` | Previous slide | Slide anterior |
| `carousel.next` | Next slide | Próximo slide |
| `carousel.play` | Play | Reproduzir |
| `carousel.pause` | Pause | Pausar |
| `carousel.indicators` | Choose slide | Escolher slide |
| `carousel.goToSlide(2)` | Go to slide 2 | Ir para o slide 2 |
| `codeBlock.copy` | Copy | Copiar |
| `codeBlock.copied` | Copied | Copiado |
| `codeBlock.label` | Code | Código |
| `combobox.clear` | Clear | Limpar |
| `combobox.showOptions` | Show options | Mostrar opções |
| `commandPalette.placeholder` | Type a command or search… | Digite um comando ou pesquise… |
| `commandPalette.empty` | No matching commands found. | Nenhum comando encontrado. |
| `dataTable.caption` | Data table | Tabela de dados |
| `dataTable.empty` | No records found. | Nenhum registro encontrado. |
| `dataTable.selectAll` | Select all rows | Selecionar todas as linhas |
| `dataTable.selectRow(0)` | Select row 1 | Selecionar linha 1 |
| `dataTable.pagination` | Table pagination | Paginação da tabela |
| `drawer.close` | Close | Fechar |
| `fileUpload.choose` | Choose files | Escolher arquivos |
| `image.failed` | Failed to load image | Não foi possível carregar a imagem |
| `image.unavailable` | Unavailable image | Imagem indisponível |
| `inputGroup.showPassword` | Show password | Mostrar senha |
| `inputGroup.hidePassword` | Hide password | Ocultar senha |
| `inputGroup.clear` | Clear search | Limpar busca |
| `numberField.decrease` | Decrease | Diminuir |
| `numberField.increase` | Increase | Aumentar |
| `otpField.cell(0, 6)` | Character 1 of 6 | Caractere 1 de 6 |
| `pagination.label` | Pagination | Paginação |
| `pagination.previous` | Previous | Anterior |
| `pagination.next` | Next | Próxima |
| `pagination.page(3)` | Page 3 | Página 3 |
| `progressCircle.label` | Progress | Progresso |
| `sidebar.collapse` | Collapse sidebar | Recolher menu lateral |
| `sidebar.expand` | Expand sidebar | Expandir menu lateral |
| `skipLink.label` | Skip to content | Pular para o conteúdo |
| `spinner.label` | Loading | Carregando |
| `splitter.handle` | Resize panel | Redimensionar painel |
| `table.scroll` | Table | Tabela |
| `tagsInput.remove("design")` | Remove design | Remover design |
| `toast.close` | Close | Fechar |
| `toggletip.close` | Close tip | Fechar dica |

<Callout kind="caution">

One text comes from a primitive, not from Camaleo: an indeterminate `Progress` is announced as "indeterminate progress" by Base UI, in English, whatever the provider says.

</Callout>

## Dates and times [#dates-and-times]

`MessagesProvider` doesn't touch dates. The date components (`Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `DateField`, `TimeField`) take a `locale` prop that sets the segment order, the month and weekday names, the first day of the week and the clock. The same date in three locales:

<Preview name="date-field/locales" compact />

Without `locale`, they use the nearest `I18nProvider` (re-exported by Camaleo), then the browser's language. Set it on the server, so the server and the browser format the same way:

<FileCode file="app/layout.tsx" code={`
  import { I18nProvider, MessagesProvider } from "@camaleo/react";

  <MessagesProvider locale="pt-BR">
    <I18nProvider locale="pt-BR">{children}</I18nProvider>
  </MessagesProvider>
`} />

## Right to left [#right-to-left]

The skins and the component CSS are written with logical properties (`margin-inline-start`, `inset-inline-end`, `border-start-start-radius`…), so the same CSS works in both directions. To turn a page or a section right to left, do three things together:

1. `dir="rtl"` on the element, for the browser's layout.
2. `lang` on the same element, so screen readers pick the right voice.
3. `<DirectionProvider direction="rtl">` around it, so the components flip their keyboard (arrows in tabs, sliders, menus) and their popups.

Switch the direction below, then pick other skins in the "preview in" bar: tabs, slider, switch and buttons all mirror, in every skin.

<Preview name="guideb-i18n/rtl" />

<FileCode file="app/[lang]/layout.tsx" code={`
  import { DirectionProvider } from "@camaleo/react";

  const dir = lang === "ar" ? "rtl" : "ltr";

  <html lang={lang} dir={dir}>
    <body>
      <DirectionProvider direction={dir}>{children}</DirectionProvider>
    </body>
  </html>
`} />

<Callout kind="caution">

A few app-structure rules still use physical sides and don't mirror yet: the `Sidebar` edge, its active-item bar and counts, shortcut hints in `Menubar` and `CommandPalette`, the line of a vertical `Stepper` and the `SkipLink` position. Check those parts by eye if you ship a right-to-left app.

</Callout>

Popups opened inside an RTL section stay RTL: the portal wrapper copies the direction. Your own icons that mean "forward" or "back" (arrows, chevrons) need flipping in RTL; icons that show a thing (a bell, a trash can) don't.

<Checklist>

- One `MessagesProvider` at the root, with the language of the page
- Function messages are overridden from a client component
- Date components get a `locale`, or sit inside an `I18nProvider`
- `dir`, `lang` and `DirectionProvider` change together
- Arrows and chevrons in your own content flip in RTL

</Checklist>


# Scoped overrides (/docs/guides/scoped-overrides)

<Learn>

- Three ways to limit an override: a token on an element, an `@scope` rule, a nested provider
- The order of the `cml.*` layers, and why your CSS wins without `!important`
- The pitfalls: islands, states you override by accident, `!important`, reduced motion

</Learn>

## Try it [#try-it]

The card has a "danger zone" (`<div className="danger-zone">`). Each option restyles only that area; the code shown with it is what runs.

<CodeSwitch
  name="guide-scope/settings"
  label="Override"
  options={[
    { kicker: "Start", title: "No override", note: "the skin as it ships.", file: "settings.tsx", code: `
      <div className="danger-zone">
        <Text>Danger zone</Text>
        <Button variant="outline">Transfer</Button>
        <Button variant="danger">Delete workspace</Button>
      </div>` },
    { kicker: "Tokens", title: "Tokens on the area", note: "the area's components read the new values; nothing outside it changes.", file: "app.css", live: true, code: `
      .danger-zone {
        --cml-button-outline-border: var(--cml-danger);
        --cml-button-outline-bg: transparent;
      }` },
    { kicker: "@scope", title: "A scoped rule", note: "full CSS, limited to the area and stopped at nested skins.", file: "app.css", live: true, code: `
      @scope (.danger-zone) to ([data-style]) {
        :scope {
          padding: 1rem;
          border: 1px dashed var(--cml-danger);
          border-radius: var(--cml-radius-surface);
        }
        [data-slot="text"]:first-child {
          color: var(--cml-danger);
        }
      }` },
    { kicker: "One skin", title: "Only in this skin", note: "the same rule, but only while the page wears the skin picked in the bar.", file: "app.css", live: true, code: `
      @scope ([data-style="$skin"]) to ([data-style]) {
        .danger-zone [data-slot="button"] {
          letter-spacing: 0.04em;
          text-transform: uppercase;
        }
      }` },
  ]}
/>

## Pick the narrowest tool [#pick-the-narrowest-tool]

| Tool | Use it for | Reaches |
| --- | --- | --- |
| A token on an element | Values: color, radius, size, spacing | That element and everything inside it |
| `@scope (…) to (…)` | Anything a token can't do | The scope root down to the limit you set |
| A nested `StyleProvider` | A different skin, mode or brand | Its subtree, popups included |

Start with tokens. A token keeps the skin's states working (hover, focus, disabled) because the skin still writes the rules; you only change the values they read.

<FileCode file="app.css" code={`
  /* Taller controls in the checkout only */
  .checkout {
    --cml-control-height: 2.75rem;
    --cml-field-height: 2.75rem;
  }
`} />

<Callout kind="caution">

The element must be **inside** the provider. Every `[data-style]` element declares all tokens again, so a class on a wrapper around the `StyleProvider` is overwritten before it reaches the components.

</Callout>

When the change is not a value (a border that isn't there, a different layout), write a rule inside `@scope`. Add `to ([data-style])` so it stops at nested skins, the way the skin files do:

<FileCode file="app.css" code={`
  @scope (.pricing) to ([data-style]) {
    [data-slot="card"] {
      border-style: dashed;
    }
  }
`} />

For a whole different look in one area, nest a provider. It is an island: it starts from clean tokens, and its popups keep its skin.

<FileCode file="docs-page.tsx" code={`
  <StyleProvider styleName="minimal">
    <Article />
    <StyleProvider styleName="retro" mode="dark">
      <Terminal />
    </StyleProvider>
  </StyleProvider>
`} />

## The layer order [#the-layer-order]

`base.css` declares four layers before anything else. Later layers win over earlier ones, and CSS that is not in any layer wins over all of them:

<FileCode file="@camaleo/styles/base.css" code={`
  @layer cml.tokens, cml.components, cml.style, cml.preferences;
`} />

| Layer | Holds |
| --- | --- |
| `cml.tokens` | Every token's default (the `minimal` values) on `:root` and `[data-style]` |
| `cml.components` | The component rules, mostly inside `:where()`, so they add no specificity |
| `cml.style` | The skin files: token values on `[data-style="name"]` and the skin's `@scope` rules |
| `cml.preferences` | Reduced motion and forced colors |
| your unlayered CSS | Wins over all of the above, whatever the specificity |

If your own CSS lives in a layer (a design system, a CSS framework), order the layers once, at the top of your entry stylesheet, before any import. A layer listed after `cml` wins over all of its sub-layers:

<FileCode file="app.css" code={`
  @layer cml, app;

  @import "@camaleo/styles/base.css";
  @import "@camaleo/styles/glass.css";

  @layer app {
    [data-style] { --cml-radius-surface: 20px; }
  }
`} />

<Callout>

Using Tailwind? Its utilities live in layers too, and which side wins depends on the same order. The [Tailwind CSS](/docs/guides/tailwind) guide has the line to add.

</Callout>

## Specificity pitfalls [#specificity-pitfalls]

- **Unlayered rules beat skin states.** `[data-slot="button"] { background: navy }` outside any layer also beats every skin's `:hover`, `[data-disabled]` and `:focus-visible` rules, so the button stops reacting. Change `--cml-accent` and `--cml-accent-hover` instead, or write the states yourself.
- **`!important` turns the layers upside down.** An important declaration in an earlier layer beats one in a later layer, and any layered important beats an unlayered one. You never need it to beat the library; leave it out.
- **Your CSS also beats `cml.preferences`.** If you add a transition or an animation, put it inside `@media (prefers-reduced-motion: no-preference)` yourself.
- **A scope without a limit leaks into islands.** `@scope (.pricing)` also styles a nested provider inside `.pricing`; add `to ([data-style])`.
- **A token set too high is lost.** On `:root` or outside the provider, it is overwritten by the provider's own declarations. Use `[data-style]` or an element inside.

<Checklist>

- Tokens first; a rule only when no token covers it
- Token overrides on an element inside the provider
- `@scope` rules end with `to ([data-style])`
- No `!important`; layered CSS listed after `cml` in one `@layer` statement
- Hover, focus and disabled still visible after your change, in light and dark

</Checklist>


# Skins & switching (/docs/guides/skins)

<Learn>

- Which CSS files and fonts each of the 13 skins needs
- What `styleName`, `mode` and `brand` do, and which of them inherit
- How to nest skins and switch them at runtime without losing state

</Learn>

## Try it [#try-it]

Type in the note, like it a few times, then pick another skin. The components re-render with new CSS; nothing is mounted again, so the text and the count stay.

<Preview name="guide-skins/switcher" />

<Steps>

## Import the CSS [#import-the-css]

`base.css` holds the tokens, the component rules and the layer order. Import it once, then one file per skin you use. `minimal` is the default and needs no file of its own.

<FileCode file="app/layout.tsx" code={`
  import "@camaleo/styles/base.css";
  import "@camaleo/styles/neubrutalism.css";
  import "@camaleo/styles/editorial.css";
`} />

<Callout>

If people can pick the skin, import every skin you offer up front. A skin whose file is missing falls back to the `minimal` defaults, with no error.

</Callout>

## Load the fonts [#load-the-fonts]

Fonts are not bundled. Each skin names its families in `--cml-font-*` tokens with system fallbacks, so it still works without them, just less like itself. Load only the ones of the skins you ship:

| Skin | Fonts |
| --- | --- |
| minimal | Inter |
| swiss | Archivo |
| editorial | Newsreader (text), Fraunces (titles), Inter (controls and labels) |
| progressive | Figtree |
| material | Roboto Flex |
| cupertino | Inter |
| glass | Plus Jakarta Sans |
| neumorphism | Manrope |
| clay | Nunito, Fredoka (titles) |
| neubrutalism | Space Grotesk |
| retro | IBM Plex Sans |
| retro-pixel | Pixelify Sans, Press Start 2P (large titles, basic Latin only) |
| y2k | Exo 2, Audiowide (large titles) |

The CSS asks for the families by name, so a stylesheet link or a self-hosted `@font-face` works as is. With `next/font`, point the token at the font's variable:

<FileCode file="app/fonts.css" code={`
  /* app/layout.tsx: const grotesk = Space_Grotesk({ subsets: ["latin"], variable: "--font-grotesk" }) */
  [data-style="neubrutalism"] {
    --cml-font-body: var(--font-grotesk), system-ui, sans-serif;
  }
`} />

## Wrap the app [#wrap-the-app]

`StyleProvider` renders a `<div>` with `data-style`, `data-mode` and the brand tokens inline. Everything inside it, including dialogs and menus rendered in a portal, wears the skin.

<FileCode file="app/providers.tsx" code={`
  import { StyleProvider } from "@camaleo/react";

  export function Providers({ children }: { children: React.ReactNode }) {
    return (
      <StyleProvider styleName="neubrutalism" mode="system" brand="#3fa34d">
        {children}
      </StyleProvider>
    );
  }
`} />

| Prop | Values | Inherits from a parent provider? |
| --- | --- | --- |
| `styleName` | One of the 13 names; `minimal` by default | No: a nested provider without it is `minimal` |
| `mode` | `light`, `dark` or `system` | Yes, when left out (the root follows the system) |
| `brand` | Any CSS color | Yes, when left out |

</Steps>

## The 13 skins [#the-13-skins]

Every skin renders the same DOM: the matrix test compares the markup of all 13 and fails if one differs. Only CSS changes, which is why a switch is cheap.

| Skin | In one line |
| --- | --- |
| minimal | Neutral and quiet, the defaults every other skin starts from |
| swiss | One grotesque, 1px ink rules, square corners, no shadows |
| editorial | Paper, ink and hairlines, with magazine serifs |
| progressive | An installable-app look: warm grey canvas, 44px touch targets |
| material | Tonal surfaces, pill buttons, filled and outlined fields |
| cupertino | Grouped grey background, white cells, continuous corners |
| glass | Frosted translucent layers over a soft blurred backdrop |
| neumorphism | One surface shaped by light: raised actions, sunken inputs |
| clay | Puffy pastel shapes that look moulded from clay |
| neubrutalism | 2px ink outlines and hard, unblurred shadows |
| retro | Classic desktop chrome with four-colour bevels |
| retro-pixel | 8-bit: thick ink borders, stepped corners, pixel fonts |
| y2k | Glossy jelly buttons, brushed chrome and pinstripes |

`material` is inspired by Material Design and `cupertino` by the Human Interface Guidelines. Camaleo is not affiliated with Google or Apple and uses none of their fonts, icons or trademarks.

## Nesting [#nesting]

A nested `StyleProvider` is an island: every token is declared again on its element, so it starts from clean defaults instead of mixing with its parent. The parent's `mode` and `brand` still reach it unless you set them.

<Preview name="guide-skins/nested" />

## Switching at runtime [#switching-at-runtime]

Keep the skin in state and pass it down. Changing `styleName` changes one attribute on the same element, so React keeps every component and its state. Don't put the skin in a `key`: that remounts the tree and resets forms.

<FileCode file="skin-switcher.tsx" code={`
  "use client";
  import { useState } from "react";
  import { STYLE_NAMES, type StyleName, StyleProvider } from "@camaleo/react";

  export function App({ children }: { children: React.ReactNode }) {
    const [skin, setSkin] = useState<StyleName>("minimal");
    return (
      <StyleProvider styleName={skin}>
        <select aria-label="Skin" value={skin} onChange={(e) => setSkin(e.target.value as StyleName)}>
          {STYLE_NAMES.map((name) => <option key={name}>{name}</option>)}
        </select>
        {children}
      </StyleProvider>
    );
  }
`} />

## The whole page, from the server [#the-whole-page-from-the-server]

To skin `<html>` itself (page background, scrollbars), spread `styleScopeProps` on it. It is server-safe, so a root layout can call it without a client component.

<FileCode file="app/layout.tsx" code={`
  import { styleScopeProps } from "@camaleo/react/style-scope";

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="en" {...styleScopeProps({ styleName: "editorial", mode: "system" })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

<Callout kind="caution">

Popups render in a portal outside your tree. They keep the skin through React context, so render them inside a `StyleProvider` (or under an `<html>` with `styleScopeProps`), never in a separate React root.

</Callout>

<Checklist>

- `base.css` imported once, before the skin files
- One CSS file for every skin people can pick
- The fonts of those skins loaded
- The skin kept in state, never in a `key`

</Checklist>


# Server Components and SSR (/docs/guides/ssr)

<Learn>

- Which components are Server Components and which ones draw a `"use client"` boundary
- How to set the skin, mode and brand on `<html>` from a root layout
- How to keep a visitor's light or dark choice without a flash
- How built-in texts reach Server Components through `Message`

</Learn>

## Server and client components [#server-and-client-components]

Each component lives in its own file in `packages/react/src`, and the build keeps those files separate, so a `"use client"` line never leaks into a file that doesn't need it. You can import everything from `@camaleo/react` in a Server Component: React turns each client component into a boundary on its own.

These files have **no** `"use client"`. Their components render on the server only and ship no JavaScript:

| File | Components |
| --- | --- |
| `alert.tsx` | `Alert`, `AlertTitle`, `AlertDescription` |
| `app-shell.tsx` | `AppShell`, `AppShellHeader`, `AppShellBody`, `AppShellContent`, `AppShellFooter`, `SkipLink` |
| `data-display.tsx` | `Stat` and its parts, `DataList` and its parts, `Timeline` and its parts, `EmptyState` and its parts, `ProgressCircle` |
| `display.tsx` | `Badge`, `Kbd`, `Card` and its parts, `Table` and its parts, `Skeleton` |
| `layout.tsx` | `Box`, `Stack`, `Grid`, `Container`, `AspectRatio` |
| `spinner.tsx` | `Spinner` |
| `typography.tsx` | `Heading`, `Text` |
| `visually-hidden.tsx` | `VisuallyHidden` |
| `style-scope.ts` | `styleScopeProps()` (a plain function) |

Everything else is a client component: every interactive part (built on Base UI or React Aria), plus `StyleProvider`, `MessagesProvider` and `DirectionProvider`, which hold React context. Client components still render to HTML on the server; they just hydrate in the browser.

<Callout kind="tip">

`Table` stays a Server Component even though it scrolls: only its small scroll container (`table-scroll.tsx`) is a client component, and it only becomes a focusable region when the table overflows.

</Callout>

<Steps>

## Set the skin on `<html>` [#set-the-skin-on-html]

In the root layout, spread `styleScopeProps()` on `<html>`. It is a plain function, safe in a Server Component, that returns `data-style`, `data-mode` and the brand scale as inline custom properties. The skin is in the very first byte of HTML, so nothing waits for JavaScript.

<FileCode file="app/layout.tsx" code={`
  import "@camaleo/styles/base.css";
  import "@camaleo/styles/glass.css";
  import { styleScopeProps } from "@camaleo/react/style-scope";

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="en" {...styleScopeProps({ styleName: "glass", brand: "#3fa34d" })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

Import `base.css` once and the CSS of every skin you render. Dialogs, menus and toasts are portaled into `<body>`, so they inherit the skin from `<html>` with no extra work.

## Keep the visitor's mode without a flash [#keep-the-visitors-mode-without-a-flash]

Camaleo's colors use `light-dark()` and `data-mode` only sets `color-scheme`. Without `mode`, the page follows the system with pure CSS: there is no script that runs before paint, so there is nothing to flash.

When visitors pick light or dark themselves, keep the choice in a cookie and read it in the layout. The server renders the right `data-mode` on the first response.

<FileCode file="app/layout.tsx" code={`
  import { cookies } from "next/headers";
  import { styleScopeProps } from "@camaleo/react/style-scope";

  const MODES = ["light", "dark", "system"] as const;

  export default async function RootLayout({ children }: { children: React.ReactNode }) {
    const saved = (await cookies()).get("cml-mode")?.value;
    // Only trust known values: the cookie comes from the browser.
    const mode = MODES.find((m) => m === saved) ?? "system";
    return (
      <html lang="en" {...styleScopeProps({ styleName: "glass", mode })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

Write the cookie from a Server Function. Used as a form `action`, it returns the re-rendered page in the same round trip:

<FileCode file="app/actions.ts" code={`
  "use server";
  import { cookies } from "next/headers";

  export async function setMode(form: FormData) {
    const mode = form.get("mode");
    if (mode !== "light" && mode !== "dark" && mode !== "system") return;
    (await cookies()).set("cml-mode", mode, { maxAge: 60 * 60 * 24 * 365 });
  }
`} />

<FileCode file="app/mode-switch.tsx" code={`
  import { Button } from "@camaleo/react";
  import { setMode } from "./actions";

  export function ModeSwitch() {
    return (
      <form action={setMode}>
        <Button type="submit" name="mode" value="dark" variant="outline">
          Dark
        </Button>
      </form>
    );
  }
`} />

<Callout kind="caution">

`cookies()` is async in this version of Next.js, and reading it makes the route dynamic. If the page must stay static, leave `mode` out and let the system decide.

</Callout>

## Add islands with `StyleProvider` [#add-islands-with-styleprovider]

`StyleProvider` is a client component, but it renders its `<div data-style>` on the server like any other. A section in another skin is in the HTML from the start:

<FileCode file="app/page.tsx" code={`
  import { Button, StyleProvider } from "@camaleo/react";

  export default function Page() {
    return (
      <StyleProvider styleName="neubrutalism" mode="light">
        <Button>Get started</Button>
      </StyleProvider>
    );
  }
`} />

Popups opened inside the island keep its skin: `DialogContent` and the other portaled parts read the provider's scope from context and apply it again.

## Set the language from the server [#set-the-language-from-the-server]

`MessagesProvider` takes a bundled set by name, which is a plain string and crosses the server–client boundary without trouble:

<FileCode file="app/layout.tsx" code={`
  import { MessagesProvider } from "@camaleo/react";

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="pt-BR">
        <body>
          <MessagesProvider locale="pt-BR">{children}</MessagesProvider>
        </body>
      </html>
    );
  }
`} />

Overrides made only of strings work here too. Some messages are functions (`pagination.page`, `carousel.goToSlide`…), and functions can't be passed from a Server Component, so override those from a client component. The [Languages & RTL guide](/docs/guides/i18n) has every key.

</Steps>

## The `Message` helper [#the-message-helper]

Server Components can't read React context, so `Spinner`, `SkipLink` and `ProgressCircle` can't call `useMessages()`. Their default label is `<Message pick="…" />` instead: a tiny client component that prints one message from the nearest `MessagesProvider`. The rest of each component stays on the server.

You can use it in your own Server Components for the same three keys:

<FileCode file="app/loading.tsx" code={`
  import { Message } from "@camaleo/react";

  // A visible "Loading…" in the language of the nearest MessagesProvider.
  export default function Loading() {
    return (
      <p role="status">
        <Message pick="spinner.label" />…
      </p>
    );
  }
`} />

`pick` accepts `"skipLink.label"`, `"spinner.label"` and `"progressCircle.label"`. For any other text, use `useMessages()` in a client component.

<Checklist>

- View the page source: `<html>` (or your provider's `<div>`) already has `data-style`
- Every skin you render has its CSS imported in the root layout
- A mode read from a cookie is checked against the known values
- No layout got `"use client"` just to use Camaleo
- `MessagesProvider` in a Server Component gets `locale` or string-only `messages`

</Checklist>


# Tailwind CSS (/docs/guides/tailwind)

<Learn>

- Where Camaleo's layers go among Tailwind's, and why the order matters
- How to use the `--cml-*` tokens as Tailwind theme values
- How to reach a part of a component through its `data-slot`
- What to style with utilities, and what to leave to the skin

</Learn>

Camaleo doesn't need Tailwind: the skins are plain CSS. If your app already uses Tailwind v4, the two work together with a few lines in your main stylesheet. There is no plugin or preset to install.

<Steps>

## Order the layers [#order-the-layers]

All of Camaleo's CSS lives in four layers: `cml.tokens`, `cml.components`, `cml.style` and `cml.preferences`. Tailwind v4 uses `theme`, `base`, `components` and `utilities`. Layers declared first lose, so declare the whole order once, **before** the imports:

<FileCode file="app/globals.css" code={`
  @layer theme, base, cml, components, utilities;

  @import "tailwindcss";
  @import "@camaleo/styles/base.css";
  @import "@camaleo/styles/glass.css";
`} />

With this order:

- Tailwind's reset (Preflight, in `base`) sits **below** Camaleo, so it never flattens a skin's buttons or fields.
- Your utilities sit **above** Camaleo, so `className="mt-6 w-full"` on a component wins over its own spacing and width.
- Unlayered CSS you write still beats everything.

<Callout kind="caution">

Without the first line, the import order decides: Camaleo's layers come after Tailwind's and beat even your utilities, so `className="w-full"` on a `Button` may seem to do nothing.

</Callout>

## Turn tokens into theme values [#turn-tokens-into-theme-values]

Map the tokens you want as utilities in a `@theme inline` block. The names below use a `cml-` prefix so they never clash with Tailwind's palette:

<FileCode file="app/globals.css" code={`
  @theme inline {
    --color-cml-surface: var(--cml-surface);
    --color-cml-raised: var(--cml-surface-raised);
    --color-cml-fg: var(--cml-fg);
    --color-cml-fg-secondary: var(--cml-fg-secondary);
    --color-cml-border: var(--cml-border);
    --color-cml-accent: var(--cml-accent);
    --color-cml-accent-fg: var(--cml-accent-fg);
    --color-cml-accent-text: var(--cml-accent-text);
    --color-cml-danger: var(--cml-danger);
    --radius-cml-control: var(--cml-radius-control);
    --radius-cml-surface: var(--cml-radius-surface);
    --font-cml-body: var(--cml-font-body);
    --font-cml-display: var(--cml-font-display);
  }
`} />

Now `bg-cml-surface`, `text-cml-fg-secondary`, `border-cml-border`, `rounded-cml-surface` and `font-cml-display` exist, and each one follows the skin, the mode and the brand of the nearest `StyleProvider`:

<FileCode file="app/page.tsx" code={`
  <aside className="rounded-cml-surface border border-cml-border bg-cml-raised p-6">
    <h2 className="font-cml-display text-cml-fg">Your plan</h2>
    <p className="text-cml-fg-secondary">Renews on 12 November.</p>
  </aside>
`} />

<Callout kind="tip">

`inline` matters. Without it, Tailwind declares `--color-cml-surface` on `:root`, where it resolves once, to the root skin. With `inline`, the utility writes `var(--cml-surface)` itself, so an island in another skin gets its own value.

</Callout>

## Style the parts with `data-slot` [#style-the-parts-with-data-slot]

Every part of every component has a stable `data-slot`, and state comes as data attributes (`data-active`, `data-checked`, `data-disabled`…). Tailwind's data variants reach them directly:

<FileCode file="app/settings.tsx" code={`
  {/* A state of the element itself */}
  <Tab value="billing" className="data-active:font-semibold">Billing</Tab>

  {/* A part inside a component */}
  <Card className="[&_[data-slot=card-title]]:text-lg">…</Card>

  {/* A token, for this element only */}
  <Button className="[--cml-radius-control:0px]">Export</Button>
`} />

Each component page lists its slots, state attributes and tokens under **Styling hooks**.

</Steps>

## Don't fight the skin [#dont-fight-the-skin]

Utilities are for **your layout**: margins, widths, grid placement, gaps and the page around the components. Those don't change from one skin to another.

The look of a component (colors, radius, borders, shadows, fonts) belongs to the skin. If you paint a `Button` with `bg-blue-600 rounded-full shadow-lg`, it stops changing with the skin, ignores the brand and dark mode, and its contrast is no longer checked by the library's tests.

| Want | Instead of | Use |
| --- | --- | --- |
| A rounder control | `rounded-full` | `[--cml-radius-control:999px]` |
| The brand color | `bg-blue-600 text-white` | `bg-cml-accent text-cml-accent-fg` |
| Muted text | `text-gray-500` | `text-cml-fg-secondary` |
| A change in one skin only | `in-data-[style=retro]:…` | an `@scope` rule in CSS |

The [Scoped overrides](/docs/guides/scoped-overrides) guide shows how to write those rules.

<Callout kind="caution">

A variant like `in-data-[style=retro]:uppercase` matches any retro **ancestor**, including one outside a nested island in another skin. Camaleo's own skin rules use `@scope ([data-style="retro"]) to ([data-style])`, which stops at the next island.

</Callout>

## Dark mode [#dark-mode]

The tokens already switch with the mode (they use `light-dark()`), so `bg-cml-surface` needs no `dark:` variant. Tailwind's `dark:` follows the system by default. If you set `mode` yourself and need `dark:` for your own colors, point the variant at `data-mode`:

<FileCode file="app/globals.css" code={`
  @custom-variant dark (&:where([data-mode=dark], [data-mode=dark] *));
`} />

This variant only sees an explicit `mode="dark"`. With `mode="system"` or no mode, keep Tailwind's default, or use tokens.

<Checklist>

- `@layer theme, base, cml, components, utilities;` comes before every `@import`
- Tokens are mapped with `@theme inline`, not plain `@theme`
- Utilities on components only handle layout and spacing
- Skin-specific changes live in `@scope` rules, not in `in-data-[style=…]` variants
- Colors you add come from tokens, so they follow the mode and the brand

</Checklist>


# Tokens (/docs/guides/tokens)

<Learn>

- Where the tokens are declared, and why a `:root` override is not enough
- Which groups exist, from the brand scale to per-component tokens
- How to reach one part of one component with `data-slot`

</Learn>

## Three levels [#three-levels]

Start at the top and go further down only when you need to. Pick a level: the demo runs the code shown with it, in the skin, mode and brand of the "preview in" bar.

<CodeSwitch
  name="guide-tokens/invite"
  label="Customization level"
  options={[
    { kicker: "Start", title: "Default", note: "the skin exactly as it ships.", file: "app.tsx", code: `
      <StyleProvider styleName="$skin">
        <InviteCard />
      </StyleProvider>` },
    { kicker: "Level 1", title: "A token", note: "one line of CSS changes every control in every skin.", file: "app.css", live: true, code: `
      [data-style] {
        --cml-radius-control: 999px;
      }` },
    { kicker: "Level 2", title: "A scoped rule", note: "restyles one part, in this skin only. Switch skins and it is gone.", file: "app.css", live: true, code: `
      @scope ([data-style="$skin"]) to ([data-style]) {
        [data-slot="button"] {
          text-transform: uppercase;
          letter-spacing: 0.06em;
        }
      }` },
    { kicker: "Level 3", title: "Your own skin", note: "a whole design language in one file, with the same components.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
          --cml-font-body: "Fraunces", Georgia, serif;
          --cml-surface: light-dark(#fff7ef, #1c1410);
          --cml-surface-raised: light-dark(#fffdf9, #261b15);
          --cml-fg: light-dark(#2b1a14, #f6e9df);
          --cml-border: light-dark(#2b1a14, #f6e9df);
          --cml-border-width: 2px;
          --cml-radius-control: 20px;
          --cml-radius-surface: 24px;
          --cml-shadow-surface: 6px 6px 0 var(--cml-border);
        }
      }` },
  ]}
/>

## Where tokens live [#where-tokens-live]

`base.css` declares every token on `:root` **and on every element with `data-style`** (the `<div>` a `StyleProvider` renders). That is what makes a nested provider an island: it starts from the defaults instead of inheriting its parent's look. The defaults are the `minimal` skin.

A skin file only redefines tokens on `[data-style="<name>"]`, inside the `cml.style` layer. The library CSS is all layered, so **your unlayered CSS beats it** without `!important` or extra specificity.

<FileCode file="app.css" code={`
  /* Every skin, every provider on the page */
  [data-style] {
    --cml-radius-control: 999px;
  }

  /* One area: an element inside the provider */
  .checkout {
    --cml-control-height: 2.75rem;
  }
`} />

<Callout kind="caution">

A token set on `:root` or on a wrapper **outside** a `StyleProvider` does not reach its components: the provider's `data-style` element declares every token again. Use `[data-style]`, or set the token on an element inside the provider.

</Callout>

Colors use `light-dark()`, so one declaration covers both modes. The browser picks the side from `color-scheme`, which `data-mode` sets (see [Dark mode](/docs/guides/dark-mode)).

## The groups [#the-groups]

| Group | What it holds | For example |
| --- | --- | --- |
| Brand scale | The 11 steps made by `createBrand`, each with a text and a hover color. Set on `:root`, not per skin, so a brand set higher up reaches nested islands. | `--cml-brand-600`, `--cml-brand-600-fg` |
| Typography | Font families and sizes for body, controls, fields and labels; weights, case and letter spacing. | `--cml-font-body`, `--cml-font-size-control` |
| Color | Surfaces, text, borders, the accent (picked from the brand scale) and the status colors. | `--cml-surface`, `--cml-accent`, `--cml-danger` |
| Shape and depth | Border width, radii, shadows, the focus ring. | `--cml-radius-control`, `--cml-shadow-surface` |
| Form fields | Field height, padding and background; check, switch and slider sizes. | `--cml-field-height`, `--cml-switch-width` |
| Density | Control heights and paddings, surface padding, the layout step. | `--cml-control-height`, `--cml-space` |
| Motion | Durations, easing and the distance things move. | `--cml-duration-fast`, `--cml-ease-standard` |
| Per component | Unset by default; a skin sets only what it needs. | `--cml-button-outline-bg`, `--cml-tab-active-bg` |

<Callout>

Change the semantic token (`--cml-accent`, `--cml-surface`) rather than the brand step: each skin picks its own steps, so `--cml-accent` is step 600 in `minimal` and step 500 in `neubrutalism`.

</Callout>

## Per-component tokens [#per-component-tokens]

Component tokens are declared as `initial`, so a nested island never inherits them, and every rule that reads one has a fallback. Setting one changes that part only:

<FileCode file="app.css" code={`
  /* button.css reads var(--cml-button-outline-bg, var(--cml-surface-raised)) */
  [data-style] {
    --cml-button-outline-bg: transparent;
  }
`} />

Each component page lists the tokens it reads under **Styling hooks**, grouped into color, shape, type and its own. Start there instead of guessing.

## Styling hooks [#styling-hooks]

When no token covers what you want, target the part. Every component renders a `data-slot` with its part name, and the library writes it **after** your props, so it can't be replaced by accident. Variants and states are attributes too:

<FileCode file="app.css" code={`
  [data-slot="button"][data-variant="outline"] {
    border-style: dashed;
  }

  [data-slot="switch"][data-checked] {
    --cml-accent: var(--cml-success);
  }
`} />

To limit a rule to one skin or one area, wrap it in `@scope`: see [Scoped overrides](/docs/guides/scoped-overrides).

## All tokens [#all-tokens]

Read from `tokens.css` when the site is built. The last column shows the value in the skin picked in the "preview in" bar; a dash means the skin keeps the default.

<TokenTable />

<Checklist>

- Override with `[data-style]` or an element inside the provider, not `:root`
- Change semantic tokens (`--cml-accent`), not brand steps
- Keep your overrides unlayered, so they beat the library without `!important`
- Check text contrast (4.5:1) in light and dark after any color change

</Checklist>


# Documentation (/docs)

<HomeSearch label="Search components, tokens, guides…" />

## Start here [#start-here]

<HomeSteps>
	<HomeStep href="/docs/installation" title="Install">Two packages and one stylesheet, in Next.js or Vite.</HomeStep>
	<HomeStep href="/docs/guides/skins" title="Pick a skin">Load one or many, switch at runtime, set the brand color and dark mode.</HomeStep>
	<HomeStep href="/docs/guides/tokens" title="Make it yours">Tokens, scoped rules, or a fourteenth skin written from scratch.</HomeStep>
</HomeSteps>

## Components [#components]

<HomeCategories summary="{n} component pages in {g} groups, each with live examples, props and keyboard notes. The thumbnails wear the skin, mode and brand from the bar above." />

## Skins [#skins]

Open a skin for its fonts, tokens and when to use it. To dress every example in one, pick it in the bar above.

<HomeSkins current="previewing" own="Make your own" />

<HomeColumns>
<HomeColumn>

## Guides [#guides]

- [Dark mode without a flash](/docs/guides/dark-mode)
- [Brand color and contrast](/docs/guides/brand-color)
- [Forms with react-hook-form and zod](/docs/guides/forms)
- [Server Components and SSR](/docs/guides/ssr)
- [Right-to-left and date locales](/docs/guides/i18n)

</HomeColumn>
<HomeColumn>

## What's new [#whats-new]

- **Oct 30** Per-skin polish: vertical tabs in Material, glass table rows, Neubrutalism alerts.
- **Oct 30** Radio items and submenus in Menu, Stepper errors, table captions and footers.
- **Oct 30** English default texts with a `MessagesProvider` and a pt-BR pack.
- **Oct 28–30** A page for every component, with live examples in all 13 skins.

<HomeMore href="/docs/changelog">Full changelog</HomeMore>

</HomeColumn>
</HomeColumns>

<HomeNote>

**Using an AI assistant?** Every page has a Markdown version (add `.md` to its URL), [/llms.txt](/llms.txt) indexes the whole site and [/llms-full.txt](/llms-full.txt) has all of it in one file.

</HomeNote>


# Installation (/docs/installation)

<Learn>

- Which packages and CSS files to add
- How to pick a skin, a mode and a brand color for the whole app
- How to switch the components' built-in texts to Portuguese

</Learn>

<Steps>

## Install the packages [#install-the-packages]

`@camaleo/react` has the components; `@camaleo/styles` has the CSS and `createBrand`.

<FileCode file="terminal" lang="bash" code={`
  pnpm add @camaleo/react @camaleo/styles
`} />

## Import the CSS [#import-the-css]

Import `base.css` once, then one file per skin you use. `minimal` is the default and needs no file of its own.

<FileCode file="app/layout.tsx" code={`
  import "@camaleo/styles/base.css";
  import "@camaleo/styles/neumorphism.css";
`} />

Fonts are not bundled. Each skin's fonts are listed in [Skins & switching](/docs/guides/skins#load-the-fonts); without them the skin falls back to system fonts.

## Wrap the app [#wrap-the-app]

`StyleProvider` applies the skin, the mode and the brand color to everything inside it, popups included.

<FileCode file="app/providers.tsx" code={`
  import { Button, StyleProvider } from "@camaleo/react";

  <StyleProvider styleName="neumorphism" mode="system" brand="#7c3aed">
    <Button>Save</Button>
  </StyleProvider>
`} />

| Prop | Values |
| --- | --- |
| `styleName` | `minimal` (default), `swiss`, `editorial`, `progressive`, `material`, `cupertino`, `glass`, `neumorphism`, `clay`, `neubrutalism`, `retro`, `retro-pixel`, `y2k` |
| `mode` | `light`, `dark` or `system`. Left out, it inherits from the parent; at the root it follows the system, with no script |
| `brand` | Any CSS color. The library builds the scale and keeps text on it at 4.5:1 or more |

To skin the whole page from a Server Component, spread `styleScopeProps` on `<html>` instead:

<FileCode file="app/layout.tsx" code={`
  import { styleScopeProps } from "@camaleo/react/style-scope";

  <html lang="en" {...styleScopeProps({ styleName: "editorial" })}>
`} />

<Callout>

`material` is inspired by Material Design and `cupertino` by the Human Interface Guidelines. Camaleo is not affiliated with Google or Apple and uses none of their fonts, icons or trademarks.

</Callout>

## Set the component texts [#set-the-component-texts]

Components that show or announce text on their own (close buttons, "Page 3", empty states) speak English by default. For Brazilian Portuguese, wrap the app once with `MessagesProvider`:

<FileCode file="app/layout.tsx" code={`
  import { MessagesProvider } from "@camaleo/react";

  <MessagesProvider locale="pt-BR">{children}</MessagesProvider>
`} />

- `locale`: `"en"` or `"pt-BR"`, the sets bundled with the library. This is the form to use in a Server Component.
- `messages`: only the keys you want to change, merged over the locale, for example `messages={{ toast: { close: "Dismiss" } }}`. Some keys are functions (`pagination.page`), which only a client component can pass.
- A component's own prop (say `closeLabel`) still wins over both. More in [Languages & RTL](/docs/guides/i18n).

</Steps>

## Customize [#customize]

From least to most invasive:

1. **Tokens.** Set them on `[data-style]`, outside any layer, and they beat the library: `[data-style] { --cml-radius-control: 4px; }`. A plain `:root` doesn't reach inside a provider, because every provider declares the tokens again. See [Tokens](/docs/guides/tokens).
2. **Parts.** Target a component's `data-slot` and state attributes: `[data-slot="button"][data-variant="outline"] { … }`. To limit a rule to an area or a skin, see [Scoped overrides](/docs/guides/scoped-overrides).
3. **Markup.** Use `className`, `style` or the `render` prop to change the element a component renders.

<Checklist>

- `@camaleo/react` and `@camaleo/styles` installed
- `base.css` imported once, then a file for each skin you use
- The app wrapped in a `StyleProvider` (or `<html>` with `styleScopeProps`)
- `MessagesProvider` set if your app isn't in English

</Checklist>


# Clay (/docs/skins/clay)

<SkinHero id="clay" />

## Use it [#use-it]

<SkinUse id="clay" />

## When to use it [#when-to-use-it]

<SkinWhen id="clay" />

## Light and dark [#light-and-dark]

<SkinModes id="clay" />

## Components in Clay [#components-in-clay]

<SkinGallery id="clay" />

## Tokens [#tokens]

<SkinTokens id="clay" />

## Same family [#same-family]

<SkinFamily id="clay" />


# Compare side by side (/docs/skins/compare)

<SkinCompare />


# Cupertino (/docs/skins/cupertino)

<SkinHero id="cupertino" />

## Use it [#use-it]

<SkinUse id="cupertino" />

## When to use it [#when-to-use-it]

<SkinWhen id="cupertino" />

## Light and dark [#light-and-dark]

<SkinModes id="cupertino" />

## Components in Cupertino [#components-in-cupertino]

<SkinGallery id="cupertino" />

## Tokens [#tokens]

<SkinTokens id="cupertino" />

## Same family [#same-family]

<SkinFamily id="cupertino" />


# Editorial (/docs/skins/editorial)

<SkinHero id="editorial" />

## Use it [#use-it]

<SkinUse id="editorial" />

## When to use it [#when-to-use-it]

<SkinWhen id="editorial" />

## Light and dark [#light-and-dark]

<SkinModes id="editorial" />

## Components in Editorial [#components-in-editorial]

<SkinGallery id="editorial" />

## Tokens [#tokens]

<SkinTokens id="editorial" />

## Same family [#same-family]

<SkinFamily id="editorial" />


# Glass (/docs/skins/glass)

<SkinHero id="glass" />

## Use it [#use-it]

<SkinUse id="glass" />

## When to use it [#when-to-use-it]

<SkinWhen id="glass" />

## Light and dark [#light-and-dark]

<SkinModes id="glass" />

## Components in Glass [#components-in-glass]

<SkinGallery id="glass" />

## Tokens [#tokens]

<SkinTokens id="glass" />

## Same family [#same-family]

<SkinFamily id="glass" />


# All 13 skins (/docs/skins)

## Typographic [#typographic]

<SkinIndex family="typographic" />

## Platform [#platform]

<SkinIndex family="platform" />

## Soft depth [#soft-depth]

<SkinIndex family="soft" />

## Bold [#bold]

<SkinIndex family="bold" />


# Material (/docs/skins/material)

<SkinHero id="material" />

## Use it [#use-it]

<SkinUse id="material" />

## When to use it [#when-to-use-it]

<SkinWhen id="material" />

## Light and dark [#light-and-dark]

<SkinModes id="material" />

## Components in Material [#components-in-material]

<SkinGallery id="material" />

## Tokens [#tokens]

<SkinTokens id="material" />

## Same family [#same-family]

<SkinFamily id="material" />


# Minimal (/docs/skins/minimal)

<SkinHero id="minimal" />

## Use it [#use-it]

<SkinUse id="minimal" />

## When to use it [#when-to-use-it]

<SkinWhen id="minimal" />

## Light and dark [#light-and-dark]

<SkinModes id="minimal" />

## Components in Minimal [#components-in-minimal]

<SkinGallery id="minimal" />

## Tokens [#tokens]

<SkinTokens id="minimal" />

## Same family [#same-family]

<SkinFamily id="minimal" />


# Neubrutalism (/docs/skins/neubrutalism)

<SkinHero id="neubrutalism" />

## Use it [#use-it]

<SkinUse id="neubrutalism" />

## When to use it [#when-to-use-it]

<SkinWhen id="neubrutalism" />

## Light and dark [#light-and-dark]

<SkinModes id="neubrutalism" />

## Components in Neubrutalism [#components-in-neubrutalism]

<SkinGallery id="neubrutalism" />

## Tokens [#tokens]

<SkinTokens id="neubrutalism" />

## Same family [#same-family]

<SkinFamily id="neubrutalism" />


# Neumorphism (/docs/skins/neumorphism)

<SkinHero id="neumorphism" />

## Use it [#use-it]

<SkinUse id="neumorphism" />

## When to use it [#when-to-use-it]

<SkinWhen id="neumorphism" />

## Light and dark [#light-and-dark]

<SkinModes id="neumorphism" />

## Components in Neumorphism [#components-in-neumorphism]

<SkinGallery id="neumorphism" />

## Tokens [#tokens]

<SkinTokens id="neumorphism" />

## Same family [#same-family]

<SkinFamily id="neumorphism" />


# Progressive (/docs/skins/progressive)

<SkinHero id="progressive" />

## Use it [#use-it]

<SkinUse id="progressive" />

## When to use it [#when-to-use-it]

<SkinWhen id="progressive" />

## Light and dark [#light-and-dark]

<SkinModes id="progressive" />

## Components in Progressive [#components-in-progressive]

<SkinGallery id="progressive" />

## Tokens [#tokens]

<SkinTokens id="progressive" />

## Same family [#same-family]

<SkinFamily id="progressive" />


# Retro pixel (/docs/skins/retro-pixel)

<SkinHero id="retro-pixel" />

## Use it [#use-it]

<SkinUse id="retro-pixel" />

## When to use it [#when-to-use-it]

<SkinWhen id="retro-pixel" />

## Light and dark [#light-and-dark]

<SkinModes id="retro-pixel" />

## Components in Retro pixel [#components-in-retro-pixel]

<SkinGallery id="retro-pixel" />

## Tokens [#tokens]

<SkinTokens id="retro-pixel" />

## Same family [#same-family]

<SkinFamily id="retro-pixel" />


# Retro (/docs/skins/retro)

<SkinHero id="retro" />

## Use it [#use-it]

<SkinUse id="retro" />

## When to use it [#when-to-use-it]

<SkinWhen id="retro" />

## Light and dark [#light-and-dark]

<SkinModes id="retro" />

## Components in Retro [#components-in-retro]

<SkinGallery id="retro" />

## Tokens [#tokens]

<SkinTokens id="retro" />

## Same family [#same-family]

<SkinFamily id="retro" />


# Swiss (/docs/skins/swiss)

<SkinHero id="swiss" />

## Use it [#use-it]

<SkinUse id="swiss" />

## When to use it [#when-to-use-it]

<SkinWhen id="swiss" />

## Light and dark [#light-and-dark]

<SkinModes id="swiss" />

## Components in Swiss [#components-in-swiss]

<SkinGallery id="swiss" />

## Tokens [#tokens]

<SkinTokens id="swiss" />

## Same family [#same-family]

<SkinFamily id="swiss" />


# Y2K (/docs/skins/y2k)

<SkinHero id="y2k" />

## Use it [#use-it]

<SkinUse id="y2k" />

## When to use it [#when-to-use-it]

<SkinWhen id="y2k" />

## Light and dark [#light-and-dark]

<SkinModes id="y2k" />

## Components in Y2K [#components-in-y2k]

<SkinGallery id="y2k" />

## Tokens [#tokens]

<SkinTokens id="y2k" />

## Same family [#same-family]

<SkinFamily id="y2k" />


# Tabela de admin (/pt-br/docs/blocks/admin-table)

A tela que fica em "Configurações → Equipe" na maioria dos SaaS, dentro da estrutura do app: cabeçalho, barra lateral (só ícones no tablet, uma gaveta de menu no celular) e a área de conteúdo. Tudo funciona: filtre por função, time e situação, ordene qualquer coluna, selecione linhas em várias páginas, mude funções em lote, edite alguém numa gaveta, convide um membro novo e exclua com confirmação. As mudanças ficam no estado local até você recarregar a página.

<BlockPreview name="block-admin-table/screen" height={860} />

## Componentes [#componentes]

<BlockUses names="AppShell, Sidebar, DataTable, InputGroup, Select, Combobox, Menu, Drawer, AlertDialog, Toast, Badge, Avatar, Switch, EmptyState, Field, Button, Typography" />

## Comportamento [#comportamento]

- **Pesquisa e filtros.** O campo de pesquisa encontra nomes e e-mails enquanto você digita. Função e situação são `Select`s com a opção "Todas"; time é um `Combobox`, para você digitar e achar numa lista maior. No celular, os filtros vão para uma gaveta inferior, atrás de um botão Filtros que conta os ativos. Limpar filtros aparece quando algum filtro está ligado, e a linha acima da tabela diz quantos membros combinam.
- **Ordenação.** Toda coluna com dados ordena ao clicar: crescente, decrescente e de volta para sem ordem. A tabela começa ordenada por nome.
- **Seleção e ações em lote.** As linhas têm caixas de seleção, e a do cabeçalho seleciona todas as linhas que passam nos filtros, em todas as páginas. Com algo selecionado, aparece uma barra com Mudar função, Suspender e Excluir. Mudar um filtro limpa a seleção, para uma ação em lote nunca atingir linhas que você não está vendo.
- **Paginação.** Dez linhas por página. Um filtro novo volta para a página 1.
- **Menu da linha.** Editar, Suspender ou Reativar, e Excluir para um membro.
- **Editar e convidar numa gaveta.** O mesmo formulário edita um membro ou convida um novo. Ele confere o nome, o formato do e-mail e se ninguém mais usa aquele e-mail.
- **Excluir com confirmação.** Um `AlertDialog` diz quem vai ser excluído e o que acontece depois. Toda mudança termina com um toast.
- **Telas estreitas.** Abaixo de 720px as colunas Time e Último acesso saem; no celular, função e situação vão para baixo do nome. Se ainda não couber, a tabela rola para o lado.

## Acessibilidade [#acessibilidade]

- A tabela tem nome, e os cabeçalhos ordenáveis são botões que definem `aria-sort`, então o leitor de tela diz qual coluna está ordenada e em que sentido.
- Cada caixa de seleção e cada menu de linha leva o nome do membro ("Selecionar Aline Prado", "Ações para Aline Prado"); a contagem de selecionados e a linha "Mostrando 12 de 18" são regiões dinâmicas.
- A gaveta e o diálogo prendem o foco e o devolvem ao menu que os abriu. Depois de uma exclusão a linha some, então o foco vai para o título da página.
- Quando o formulário da gaveta tem erro, o foco vai para o primeiro campo com problema, e o erro é lido junto.

## Use o código [#use-o-código]

A aba Código mostra a tela inteira em um arquivo, com `@camaleo/react` e `lucide-react` como únicas dependências (o `DataTable` traz o TanStack Table junto). Os membros são dados fixos: troque pela sua API, e leve a filtragem e a paginação para o servidor quando a lista crescer (o `DataTable` aceita `pageCount`, `totalRows` e `sorting` controlado para isso).


# Entrar (/pt-br/docs/blocks/auth)

As telas de conta que quase todo produto precisa no primeiro dia, num arquivo só. Entrar e Criar conta são abas; Esqueceu a senha, o código de uso único depois do cadastro, o "confira seu e-mail" e o estado de conectado são visões do mesmo card. Em telas largas, um painel da marca com o depoimento de uma cliente fica ao lado do formulário; nas menores, o formulário aparece sozinho. Tudo valida, e o código de teste da etapa de verificação aparece abaixo do campo.

<BlockPreview name="block-auth/screen" height={860} />

## Componentes [#componentes]

<BlockUses names="Tabs, Field, InputGroup, OtpField, Checkbox, Link, Button, Card, Avatar, Typography" />

## Comportamento [#comportamento]

- **Entrar.** E-mail e senha são obrigatórios; a senha tem um botão para mostrar e ocultar. "Manter conectado" é uma caixa de seleção simples, que você liga à duração da sua sessão.
- **Criar conta.** Nome, e-mail, uma senha com três regras que vão sendo marcadas enquanto você digita (8 caracteres, uma letra e um número, diferente do e-mail) e a caixa dos termos. Enviar leva para a etapa do código.
- **Código de uso único.** Seis casas que aceitam digitação, Backspace e colar o código inteiro. Código incompleto e código errado têm erros diferentes. "Enviar novo código" espera 30 segundos entre um envio e outro, e o botão mostra a contagem.
- **Esqueceu a senha.** Pede o e-mail e responde do mesmo jeito exista a conta ou não, para o formulário não servir para descobrir quem tem conta.
- **Link mágico e chave de acesso.** Os dois botões abaixo do "ou" representam o login sem senha. Eles usam ícones genéricos de propósito: se você adicionar login com Google ou Apple, siga as regras de botão de cada provedor.

## Acessibilidade [#acessibilidade]

- Toda troca de etapa leva o foco para o título do card, então o leitor de tela anuncia "Confira seu e-mail" ou "Redefinir a senha" em vez de silêncio. Trocar de aba deixa o foco na aba, como o padrão de abas espera.
- Um envio com erro leva o foco para o primeiro campo com problema; o erro está ligado ao campo e é lido junto.
- As regras da senha são ditas uma vez, na descrição do campo. A lista que vai sendo marcada abaixo é só visual (`aria-hidden`), para não se repetir a cada tecla.
- O botão de mostrar senha troca de nome ("Mostrar senha", "Ocultar senha") em vez de usar `aria-pressed`. Cada casa do código depois da primeira se chama "Dígito 2 de 6" e assim por diante.
- O botão de reenviar usa `aria-disabled` durante a contagem, então continua com foco e na ordem do Tab.
- Todo campo tem `autocomplete` (`username`, `current-password`, `new-password`, `one-time-code`), para gerenciadores de senha e o preenchimento automático do código por SMS funcionarem.

## Use o código [#use-o-código]

A aba Código mostra a tela inteira em um arquivo, com `@camaleo/react` e `lucide-react` como únicas dependências. A função `wait` faz o papel do seu servidor de autenticação: troque pelas suas requisições, e troque o `DEMO_CODE` por uma verificação no servidor. Nunca decida no navegador se um código ou uma senha está certo.


# Checkout (/pt-br/docs/blocks/checkout)

Um checkout de uma página só, que mantém o resumo do pedido à vista enquanto a pessoa passa por endereço, frete, pagamento e revisão. Preencha, erre de propósito e clique em Continuar: cada etapa confere os próprios campos antes de deixar seguir. O cartão é de demonstração; nada é enviado.

<BlockPreview name="block-checkout/screen" height={940} />

## Componentes [#componentes]

<BlockUses names="Stepper, Card, Field, Select, RadioGroup, ErrorSummary, DataList, Badge, Button, Typography, Separator" />

## Comportamento [#comportamento]

- **Validação por etapa.** Continuar confere só os campos da etapa atual. Os erros aparecem depois da primeira tentativa e se atualizam enquanto você digita, então corrigir um campo apaga a mensagem sem outro clique.
- **CEP de acordo com o país.** A dica de formato e a verificação seguem o país escolhido: `01310-100` no Brasil, `94103` nos Estados Unidos, `1100-148` em Portugal, `M5V 2T6` no Canadá.
- **Cartão formatado ao digitar.** O número é agrupado de quatro em quatro e conferido pelo dígito de Luhn, a validade ganha a barra e não pode ter passado, e o código de segurança aceita 3 ou 4 dígitos. Os tokens de `autocomplete` (`cc-number`, `cc-exp`, `cc-csc`) deixam o navegador e o gerenciador de senhas preencherem.
- **O frete muda o total.** Os cards de opção são um `RadioGroup` de verdade: o resumo e o botão Pagar se atualizam com o preço do frete.
- **Cupom.** `CAMALEO10` dá 10% de desconto nos itens; qualquer outro código mostra um erro abaixo do campo.
- **Revisar e alterar.** A revisão lista o que foi preenchido, com um botão Alterar que volta para a etapa. Pagar mostra o carregamento, e a confirmação substitui o formulário.

## Acessibilidade [#acessibilidade]

- Depois de um Continuar com erro, o foco vai para o `ErrorSummary` no topo da etapa; cada link dele leva o foco ao campo.
- Quando a etapa muda, o foco vai para o título da etapa, que é lido como "Etapa 2 de 4: Frete". O `Stepper` marca a etapa atual com `aria-current="step"`, e as etapas concluídas dizem "concluída" para leitores de tela.
- Todo campo tem rótulo visível, e as dicas e os erros estão ligados a ele, então são lidos quando o campo recebe foco.
- O título da confirmação recebe o foco quando substitui o formulário, então quem usa teclado ou leitor de tela não se perde.

## Use o código [#use-o-código]

A aba Código mostra a tela inteira em um arquivo. Ela só precisa de `@camaleo/react` e `lucide-react`: a validação é uma função simples, que você pode trocar pela sua biblioteca de schema. Troque o carrinho e os preços fixos pelos seus dados, e mande os dados do cartão para os componentes do seu provedor de pagamento (Stripe Elements, Adyen, Pagar.me), não para o seu servidor: número de cartão nunca deve passar por ele.


# Dashboard de vendas (/pt-br/docs/blocks/dashboard)

<BlockPreview name="block-dashboard/screen" height={820} />

## Feito com [#feito-com]

<BlockUses names="AppShell, Sidebar, Drawer, SearchInput, IconButton, Avatar, ToggleGroup, Stat, Card, Meter, DataTable, Badge, NativeSelect, Heading, Text" />

## Comportamento [#comportamento]

- **Três layouts conforme a largura.** O shell mede a própria largura: menu lateral completo a partir de 1000px, trilho de ícones a partir de 640px e, abaixo disso, um botão de menu que abre a mesma navegação num `Drawer`. Experimente as larguras Tablet e Celular acima. No seu app, uma media query na janela faz o mesmo.
- **Filtro de período.** 7, 30 ou 90 dias muda os números, as variações e o gráfico; em 90 dias o gráfico passa a ter barras por semana.
- **Sem biblioteca de gráficos.** As barras são elementos simples com altura em porcentagem e cores `--cml-accent` e `--cml-brand-300`, então o gráfico acompanha o estilo e a cor da marca. As linhas de grade misturam `--cml-fg` com pouca opacidade, para continuarem discretas mesmo nos estilos de borda preta sólida. Troque pela sua biblioteca de gráficos quando precisar de eixos e tooltips.
- **Pedidos.** O filtro de canal restringe a `DataTable`; a tabela ordena por qualquer coluna, pagina de 5 em 5 e mostra um estado vazio quando o canal não tem pedidos.
- **Notícia boa e ruim.** Na taxa de reembolso, cair é bom: o `StatDelta` recebe `sentiment="positive"` com `trend="down"`, para a cor bater com o significado.

## Acessibilidade [#acessibilidade]

- Cabeçalho, menu lateral e conteúdo são um `header`, um `aside` com `nav` nomeado e o `main` da página. Nesta página o conteúdo vira `div`, porque a documentação já tem um `main`.
- As barras do gráfico ficam escondidas dos leitores de tela; a descrição do card diz em palavras o melhor dia e a receita dele.
- Os botões de período são um `ToggleGroup` com nomes completos ("Últimos 30 dias") como nome acessível, não só "30d".
- Os itens do menu no trilho mantêm o nome (e um `title` como dica), e a página atual tem `aria-current="page"`.


# Caixa de entrada (/pt-br/docs/blocks/inbox)

Uma caixa de entrada em três painéis: pastas, lista de conversas e mensagem. Ela segue a própria largura, não a da janela: no tablet as pastas viram um select acima da lista, e no celular a lista e a mensagem se revezam na tela. Teste cada largura com o seletor acima da visualização.

<BlockPreview name="block-inbox/screen" height={720} />

## Componentes [#componentes]

<BlockUses names="Toolbar, Checkbox, InputGroup, Select, EmptyState, Avatar, Badge, Kbd, Tooltip, Toast, Field, Button, Typography" />

## Comportamento [#comportamento]

- **Não lidas.** As conversas não lidas têm remetente e assunto em negrito e uma barra na cor de destaque. Abrir uma conversa marca como lida, e as contagens das pastas se atualizam.
- **Seleção.** Cada linha tem uma caixa de seleção, e a que fica acima da lista seleciona todas as linhas visíveis (mostra um traço quando só parte está marcada). A barra de ferramentas age sobre a seleção: Arquivar, Excluir e Marcar como lida ou não lida. Em Arquivo e Lixeira, Arquivar vira Mover para a caixa de entrada.
- **Desfazer.** Mover conversas mostra um toast com um botão Desfazer, que devolve tudo para onde estava.
- **Pesquisa.** O campo filtra a pasta atual por remetente, assunto e prévia enquanto você digita, sem ligar para acentos ("julia" encontra "Júlia"). Quando nada combina, um estado vazio avisa e oferece limpar a pesquisa.
- **Painel de leitura.** Com espaço para os dois painéis, a primeira conversa já começa aberta, e arquivar ou excluir a conversa aberta abre a seguinte. A mensagem mostra remetente, data e texto, com as mesmas ações numa barra e uma caixa de resposta que não deixa enviar vazio.
- **Escrever.** Escrever (na coluna das pastas, ou acima da lista em telas menores) abre uma mensagem nova no painel de leitura; ela confere o e-mail do destinatário e se a mensagem não está vazia.
- **Pastas vazias.** A caixa de entrada vazia diz que está tudo em dia; Arquivo e Lixeira dizem o que vai parar ali.

## Acessibilidade [#acessibilidade]

- A lista usa um único ponto de Tab: Tab entra na lista uma vez, na última linha visitada. <kbd>↑</kbd> e <kbd>↓</kbd> passam de linha em linha, <kbd>Home</kbd> e <kbd>End</kbd> vão para as pontas, <kbd>X</kbd> seleciona a linha em foco e <kbd>Enter</kbd> abre. Com teclado e espaço sobrando, as teclas aparecem abaixo da lista, ligadas a ela por `aria-describedby`; em telas de toque e no celular a dica some. A linha em foco ganha o anel de foco do estilo.
- As linhas não lidas começam com um "não lida" oculto, para o leitor de tela anunciar o estado e não só o negrito. A conversa aberta tem `aria-current`.
- Cada caixa de seleção leva o nome da conversa ("Selecionar Marina Costa: Guia da marca, versão 3"), e os botões de ícone das barras têm nome e tooltip.
- Quando linhas somem (arquivadas ou excluídas), o foco vai para o título da pasta em vez de se perder. No celular, abrir uma mensagem leva o foco ao assunto, e Voltar devolve o foco à linha.
- A contagem de selecionadas e os toasts são anunciados por regiões dinâmicas (live regions).

## Use o código [#use-o-código]

A aba Código mostra a tela inteira em um arquivo, com `@camaleo/react` e `lucide-react` como únicas dependências. As mensagens são dados fixos e a pasta de cada uma fica no estado local; troque os dois pela sua API. O hook `useWidth` no topo é o que faz o layout seguir a própria caixa, então ele também funciona dentro de um painel redimensionável.


# Exemplos (/pt-br/docs/blocks)

## Marketing [#marketing]

<BlockGallery group="marketing" />

## Aplicativo [#aplicativo]

<BlockGallery group="app" />

## Comércio [#comércio]

<BlockGallery group="commerce" />

## Conta [#conta]

<BlockGallery group="account" />


# Landing de produto (/pt-br/docs/blocks/landing)

<BlockPreview name="block-landing/screen" height={900} />

## Feito com [#feito-com]

<BlockUses names="Heading, Text, Badge, Button, Link, Menu, IconButton, Card, Stat, Progress, Rating, Avatar, Accordion, Field, Input, Separator" />

## Comportamento [#comportamento]

- **Cabeçalho.** A partir de 760px os links ficam no cabeçalho; abaixo disso eles vão para um `Menu` atrás de um botão, e só a chamada principal continua visível.
- **Hero.** A prévia do produto à direita é feita com os mesmos `Stat`, `Progress` e `Badge` que você usaria no app, então ela muda com o estilo. É decorativa e fica escondida dos leitores de tela.
- **Cor a partir dos tokens.** Os fundos do hero, dos ícones e da faixa final misturam `--cml-accent` com transparência, então uma nova cor de marca repinta a página.
- **Tamanhos que acompanham a largura.** Títulos e espaçamentos usam `clamp()` com unidades `cqi`, e todas as grades são `auto-fit`, então a página não precisa de breakpoints. Fora de um container de tamanho, `cqi` usa a viewport.
- **Cadastro.** O formulário final confere o e-mail ao enviar, mostra o erro abaixo do campo e se troca por uma confirmação.

## Acessibilidade [#acessibilidade]

- Um `h1` no hero, um `h2` por seção (o do depoimento fica escondido da tela) e `h3` nos cards, nas perguntas e nas colunas do rodapé.
- As navegações do cabeçalho e do rodapé têm nomes diferentes, e os links internos apontam para as seções pelo `id`.
- A nota é uma imagem só, chamada "Nota 5 de 5", e não cinco estrelas separadas.
- As perguntas usam `Accordion`, então cada pergunta é um botão dentro de um título, com `aria-expanded`.


# Preços (/pt-br/docs/blocks/pricing)

<BlockPreview name="block-pricing/screen" height={900} />

## Feito com [#feito-com]

<BlockUses names="Badge, Heading, Text, ToggleGroup, Toggle, Card, Button, Table, Accordion, VisuallyHidden" />

## Comportamento [#comportamento]

- **Mensal ou anual.** A chave de cobrança é um `ToggleGroup` com um valor só. Clicar de novo na opção ativa não a desliga, então a página nunca fica sem preço. No anual, aparece o valor por mês e, embaixo, o total do ano.
- **Um plano em destaque.** O plano mais escolhido ganha contorno na cor de destaque, botão sólido e um selo; os outros dois têm botões de contorno, para haver um próximo passo óbvio.
- **Tabela comparativa.** As linhas são recursos e as colunas são planos. Abaixo de 560px, uma escolha de plano mostra um plano por vez ao lado dos recursos, então nenhuma coluna fica escondida fora da tela.
- **Layout.** A página mede a própria largura: três planos lado a lado a partir de 700px e um por linha abaixo disso. Nunca dois mais um sobrando, que parece um plano faltando.

## Acessibilidade [#acessibilidade]

- Uma região viva, escondida da tela, diz "Mostrando preços anuais" quando a chave muda, porque os preços mudam em outro ponto da página.
- Cada botão de plano lê o nome do plano ("Testar por 14 dias, Equipe"), então uma lista de botões ainda faz sentido.
- Os ícones de check e traço da tabela ficam escondidos dos leitores de tela e levam o texto "Incluído" ou "Não incluído"; os nomes dos recursos são cabeçalhos de linha.
- Os gatilhos das perguntas são títulos `h3` abaixo do `h2` "Dúvidas sobre cobrança", definidos com `AccordionTrigger level`.


# Configurações da conta (/pt-br/docs/blocks/settings)

<BlockPreview name="block-settings/screen" height={820} />

## Feito com [#feito-com]

<BlockUses names="AppShell, Sidebar, Drawer, Tabs, Card, Avatar, Button, Field, Input, Textarea, NativeSelect, Switch, Separator, PasswordInput, OtpField, Badge, AlertDialog, Alert, Heading, Text" />

## Comportamento [#comportamento]

- **Dentro do app.** As configurações ficam no mesmo `AppShell` do dashboard de vendas: menu lateral a partir de 1000px, trilho de ícones a partir de 640px e um `Drawer` abaixo disso. As seções são abas; abaixo de 640px um select escolhe a seção, então nenhuma aba fica escondida fora da tela. Experimente a largura Celular acima.
- **Perfil.** Enviar foto abre o seletor de arquivos e mostra a imagem no `Avatar` na hora (uma URL de objeto; envie o arquivo ao servidor ao salvar). A bio conta os 160 caracteres que faltam. Salvar valida nome e e-mail e confirma numa linha de status.
- **Notificações.** Cada chave fica dentro de um rótulo que ocupa a linha toda, então o título e a dica também a alternam. Elas salvam na hora, como diz o rodapé.
- **Segurança.** O formulário de senha confere a senha atual, as regras da nova e se a confirmação bate. Ativar a verificação em duas etapas mostra a chave de configuração e um `OtpField`; Verificar exige os 6 dígitos e o selo passa para Ativada.
- **Zona de perigo.** Excluir conta abre um `AlertDialog` cujo botão de excluir fica desativado até você digitar `marina`. Confirmar troca o card por um aviso com opção de desfazer.

## Acessibilidade [#acessibilidade]

- As setas do teclado andam entre as abas e Enter abre uma. Cada seção começa com um `h2` escondido da tela (a aba ou o select já mostram o nome), e os cards dentro dela usam `h3`.
- Mensagens de salvo e de erro ficam em regiões `role="status"` ou ligadas aos campos com `FieldError`, então os leitores de tela as anunciam.
- As células do código se chamam "Dígito 2 de 6", e a primeira usa o rótulo do campo.
- O `AlertDialog` prende o foco, começa no primeiro controle e devolve o foco ao botão que o abriu quando fecha.


# Cadastro em etapas (/pt-br/docs/blocks/signup)

<BlockPreview name="block-signup/screen" height={820} />

## Feito com [#feito-com]

<BlockUses names="Stepper, Card, Avatar, Field, Input, PasswordInput, InputGroup, RadioGroup, NativeSelect, Checkbox, ErrorSummary, DataList, Button, Heading, Text, Link" />

## Comportamento [#comportamento]

- **Painel da marca.** A partir de 860px, um painel na cor da marca fica ao lado do formulário, com os motivos para se cadastrar e o depoimento de um cliente; em telas mais estreitas, o formulário fica sozinho, com o logo acima.
- **Validação por etapa.** Continuar confere só a etapa atual. Os erros aparecem depois do primeiro Continuar naquela etapa e se atualizam enquanto você digita, então um campo corrigido deixa de ficar vermelho na hora.
- **Resumo de erros.** Um Continuar com problemas mostra um `ErrorSummary` com um link por problema; cada link leva o foco ao campo. A etapa fica vermelha no Stepper até ser corrigida.
- **Endereço a partir do nome.** O endereço do espaço acompanha o nome ("Café Serra Azul" → `cafe-serra-azul`) até você editá-lo.
- **Revisão.** A última etapa lista tudo o que foi preenchido, com um botão Editar por seção que volta para ela. Os valores ficam guardados quando você anda entre as etapas.
- **Sucesso.** Criar o espaço troca o formulário por uma confirmação que repete o e-mail.

## Acessibilidade [#acessibilidade]

- Ao mudar de etapa, o foco vai para o título dela; num Continuar com erros, vai para o resumo, então o leitor de tela começa no lugar certo.
- O Stepper é uma lista ordenada; a etapa atual tem `aria-current="step"` e as concluídas dizem "concluída".
- Cada erro também aparece no `FieldError` do campo, ligado ao input, e o título do resumo diz quantos problemas há.
- O formulário usa `noValidate`, para os balões do navegador não competirem com o resumo; os valores de `autoComplete` deixam gerenciadores de senha preencherem a etapa da conta.


# Changelog (/pt-br/docs/changelog)

## 1.0 — Não lançada [#10--não-lançada]

A 1.0 vai ser a primeira versão no npm. Ela está sendo terminada agora: o site de documentação (este), uma última passada na biblioteca e a preparação da publicação. Até lá, os pacotes estão em `0.0.0` e as entradas abaixo são a história do repositório.

## Acabamento dos estilos [#acabamento-dos-estilos]

<p className="gb-when">30 out. 2026 · estilos</p>

- `material`: abas verticais ganham o indicador na lateral em vez do sublinhado embaixo.
- `glass`: as linhas entre etapas futuras de um `Stepper` continuam visíveis no modo claro.
- `neubrutalism`: texto direto num `Alert` mantém 4,5:1.
- `progressive`: o item de perigo realçado de um menu escuro chega a 4,5:1 (era 4,43:1).
- O × do `Drawer` fica na linha do título em todos os estilos, também quando há descrição.
- O preenchimento do `Slider` fica centrado na trilha (estava 1 px fora no `editorial`, `y2k`, `neumorphism` e `retro`).
- `retro`: o `AppShell` ganha bisel de janela. `neumorphism`: sombra clara mais suave.

## Menus, steppers, tabelas e mais [#menus-steppers-tabelas-e-mais]

<p className="gb-when">30 out. 2026 · biblioteca</p>

- **Overlays.** Itens de rádio e submenus no `Menu` e no `ContextMenu`, itens de checkbox no `ContextMenu`, e o Tab fecha o menu. O `Toggletip` não anuncia mais um diálogo. Um `DrawerBody` que rola recebe foco. Um `Popover` alto é limitado à tela. Os toasts mapeiam os tipos `loading` e `error` e respeitam o `limit`. O Ctrl+K não abre mais o `CommandPalette` a partir de outro campo de texto.
- **Exibição.** `sentiment` no `StatDelta`, para métricas em que cair é bom. `EmptyStateTitle` aceita `as`. O `ProgressCircle` anuncia o texto do valor. Novos `TableCaption` e `TableFooter`. Um card pode virar um link inteiro. O `CodeBlock` rola como região nomeada e realça comentários conforme a linguagem. O `Carousel` segue o padrão de abas.
- **Navegação.** O `Stepper` ganha `activeStep`, status de erro e um `StepSeparator` com estilo. Novo `ToolbarInput`, e Home/End nas barras de ferramentas. A lista de abas rola quando as abas não cabem. O `AccordionTrigger` aceita o nível do título. Novo `BreadcrumbEllipsis`.
- **Estrutura do app.** Novo `AppShellBody`, `render` no `AppShellContent` e no `SidebarItem`, Enter recolhe um painel do `Splitter`, o `ScrollArea` funciona só com `max-height`, o `VisuallyHidden` pode aparecer no foco.
- **Formulários.** Valores de `RadioGroup` e `Slider` tipados. O `Slider` passa o texto do valor aos thumbs e tem layout vertical. O `NativeSelect` entra no `Field`. O `NumberField` mostra teclado decimal para passos decimais. Os erros do `OtpField` chegam a todas as casas. O `TagsInput` não descarta mais uma tag repetida sem avisar o `onValueChange`. `Checkbox` e `Rating` põem o `id` no elemento focável.

## Tokens que faltavam, slots estáveis e textos traduzidos [#tokens-que-faltavam-slots-estáveis-e-textos-traduzidos]

<p className="gb-when">30 out. 2026 · biblioteca</p>

- Quatro tokens que os componentes usavam sem ninguém definir agora estão no `tokens.css`: `--cml-border-subtle`, `--cml-item-hover`, `--cml-surface-subtle` e `--cml-motion-duration`.
- O `data-slot` vem depois de `{...props}` em 183 lugares, então `render={<Button />}` mantém o slot e a aparência do botão.
- Novos `MessagesProvider`, `useMessages`, `Message` e os pacotes `en` e `ptBR`. Os textos embutidos de 23 componentes vêm dele; as props continuam vencendo. Veja [Idiomas e RTL](/pt-br/docs/guides/i18n).

## Uma página para cada componente [#uma-página-para-cada-componente]

<p className="gb-when">28–30 out. 2026 · docs</p>

Cada componente ganhou a própria página, em inglês e português: playground, de 6 a 9 exemplos ao vivo, composições reais, pares de faz/não faz, props geradas dos tipos, styling hooks e notas de teclado. Foram feitas grupo a grupo, de ações e formulários até layout e estrutura do app.

Escrever as páginas achou e corrigiu bugs pelo caminho, entre eles: horários de 12 horas quebrando a hidratação, um `Progress` indeterminado que parecia concluído, painéis do `NavigationMenu` abrindo vazios, setas do `CommandPalette` seguindo a ordem errada, `Stack` dentro de `Stack` herdando o espaçamento do pai e o foco caindo no `<body>` na última página de uma `Pagination`.

## O site de documentação [#o-site-de-documentação]

<p className="gb-when">27–28 out. 2026 · docs</p>

- Site bilíngue, com inglês na raiz e português em `/pt-br`.
- A barra "visualizar em": um estilo, um modo e uma marca para todos os previews, salvos entre visitas.
- Previews com aba de código que lê o próprio arquivo do exemplo, tabelas de props geradas dos tipos e um verificador de páginas que roda o axe em 4 estilos, nos dois modos, em três larguras e nos dois idiomas.
- O popup do `Drawer` envolvido na viewport, o que tirou um aviso do Base UI.

## Formulários avançados, datas, dados e estrutura do app [#formulários-avançados-datas-dados-e-estrutura-do-app]

<p className="gb-when">27 out. 2026 · biblioteca</p>

- **Formulário avançado:** `PasswordInput`, `SearchInput`, `InputGroup`, `OtpField`, `TagsInput`, `Dropzone` com `FileList`, `Rating`, `Chip` e `ErrorSummary`.
- **Datas**, sobre React Aria: `Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `DateField` e `TimeField`, ligados ao `Field`.
- **Exibição de dados:** `DataTable` (TanStack Table), `Stat`, `DataList`, `Timeline`, `EmptyState`, `ProgressCircle`, `Meter`, `Image`, `CodeBlock`, `TreeView` e `Carousel`.
- **Estrutura do app:** `Sidebar`, `AppShell`, `NavigationMenu`, `Menubar`, `ContextMenu`, `Toolbar`, `Stepper`, `CommandPalette`, `HoverCard`, `Toggletip` e `Splitter`.

## Mais nove estilos [#mais-nove-estilos]

<p className="gb-when">26–27 out. 2026 · estilos</p>

- `neubrutalism`, `retro` e `glass`; depois `swiss`, `progressive` e `clay`; depois `material`, `cupertino` e `y2k`. Treze estilos no total, cada um em claro e escuro.
- A matriz de contraste aprendeu a medir texto sobre gradiente e vidro em pixels reais. Na primeira execução, pegou a aba do glass escuro com 4,36:1 numa marca ciano.

## Os primeiros 50 componentes [#os-primeiros-50-componentes]

<p className="gb-when">26 out. 2026 · biblioteca</p>

Cerca de 50 componentes, em quatro grupos: ações e formulários, exibição e feedback (com os tons testados em 4,5:1), navegação e overlays, e as primitivas de layout (`Box`, `Stack`, `Grid`, `Container`, `AspectRatio`, `ScrollArea`, `Portal`, `DirectionProvider`). Cada um nos quatro primeiros estilos: `minimal`, `neumorphism`, `retro-pixel` e `editorial`.

## O contrato de estilo [#o-contrato-de-estilo]

<p className="gb-when">26 out. 2026 · biblioteca</p>

A ideia em que a biblioteca inteira se apoia, provada com quatro estilos o mais distantes possível: DOM fixo com nomes em `data-slot`, tokens em camadas de cascata (`cml.tokens`, `cml.components`, `cml.style`, `cml.preferences`), `StyleProvider` com ilhas aninhadas, e `Button`, `Dialog` e `Tabs` como primeiros componentes.

## Fundação [#fundação]

<p className="gb-when">26 out. 2026 · ferramentas</p>

O monorepo com pnpm e Turborepo: `@camaleo/react`, `@camaleo/styles`, Storybook, este app de docs e um app Next.js que confere a renderização no servidor.


# Accordion (/pt-br/docs/components/accordion)

<ComponentMeta file="accordion" primitive="Base UI" pattern="WAI-ARIA Accordion" />

<Playground
	name="accordion/playground"
	component="Accordion"
	controls={[{ prop: "multiple", default: false }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Accordion, AccordionItem, AccordionTrigger, AccordionPanel, Collapsible, CollapsibleTrigger, CollapsiblePanel" />

## Anatomia [#anatomia]

O `AccordionTrigger` coloca o botão dentro de um título, então as seções aparecem na lista de títulos do leitor de tela. É um `h3`; use `level` para encaixar no esquema da página, como `level={4}` abaixo do título de um card. O painel anima a altura; o espaçamento fica num elemento interno para nada pular. O `Collapsible` tem o mesmo gatilho e painel, sem o título.

<Anatomy
	tree={{
		slot: "accordion",
		tag: "div",
		children: [
			{
				slot: "accordion-item",
				tag: "div",
				children: [
					{
						slot: "accordion-header",
						tag: "h3",
						note: "level troca de h1 a h6",
						children: [
							{
								slot: "accordion-trigger",
								tag: "button",
								row: true,
								note: "aria-expanded",
								children: [{ slot: "disclosure-chevron", tag: "span", note: "ou disclosure-plus" }],
							},
						],
					},
					{ slot: "accordion-panel", tag: "div", note: "anima a altura", children: [{ slot: "accordion-panel-content", tag: "div" }] },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor da barra acima. Abra uma seção e depois experimente Tab e Enter.

<Preview name="accordion/basic" compact />

<ExampleGrid>
	<Example name="accordion/multiple" title="Várias abertas">
		Com `multiple`, abrir uma seção mantém as outras abertas. Use quando a pessoa lê as seções lado a lado; o `defaultValue` abre as que a maioria precisa.
	</Example>
	<Example name="accordion/settings-forms" title="Seções de um formulário">
		Divida configurações longas em seções preenchidas uma por vez. O `keepMounted` mantém no formulário os campos das seções fechadas, então o que foi digitado ainda é enviado.
	</Example>
	<Example name="accordion/expand-all" title="Abrir todas">
		Clique no botão. Com `value` e `onValueChange` você controla quais seções estão abertas, e um botão só abre ou fecha todas.
	</Example>
	<Example name="accordion/find-in-page" title="Achado pela busca da página">
		Aperte Ctrl+F e busque "nota fiscal". Com `hiddenUntilFound`, os painéis fechados continuam na página e abrem quando o navegador encontra o texto neles.
	</Example>
	<Example name="accordion/disabled-reason" title="Desativada, com o motivo">
		O Tab pula um título desativado, então deixe o motivo em texto visível ao lado: diga por que está fechado e quando abre.
	</Example>
	<Example name="accordion/collapsible-advanced" title="Opções avançadas">
		O `Collapsible` esconde opções de que a maioria nunca precisa, então o formulário fica curto e os padrões fazem o trabalho.
	</Example>
	<Example name="accordion/collapsible-show-more" title="Mostrar mais">
		Clique nele. Os itens extras aparecem logo acima do botão, onde a leitura parou, e o rótulo diz o que ele fará em seguida.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="accordion/context-help" title="Central de ajuda" uses="Card · SearchInput · Accordion · Button" />
	<Context name="accordion/context-filters" title="Filtros de produtos" uses="Accordion · Checkbox · RadioGroup · Badge" />
	<Context name="accordion/context-summary" title="Resumo do pedido" uses="Card · Collapsible · Separator · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="accordion/do-headers" title="Títulos que dizem o que há dentro.">
		Uma pergunta ou um assunto mostra se vale abrir, e fica claro numa lista de títulos.
	</Guideline>
	<Guideline kind="dont" name="accordion/dont-vague" title="Títulos vagos.">
		"Mais informações" e "Outros" obrigam a pessoa a abrir todas as seções para achar qualquer coisa.
	</Guideline>
	<Guideline kind="do" name="accordion/do-compare" title="O que se compara, lado a lado.">
		Preços e limites numa tabela só se leem de relance.
	</Guideline>
	<Guideline kind="dont" name="accordion/dont-compare" title="Esconder o que a pessoa compara.">
		Com um plano aberto por vez, a pessoa precisa lembrar o preço do outro.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="accordion"
	type="AccordionProps"
	include={["multiple", "value", "defaultValue", "onValueChange", "disabled", "keepMounted", "hiddenUntilFound"]}
	types={{ onValueChange: "(value, eventDetails) => void", value: "Value[]", defaultValue: "Value[]" }}
	describe={{ multiple: "Deixa várias seções abertas ao mesmo tempo.", value: "As seções abertas. Use com `onValueChange` para controlar o estado.", defaultValue: "As seções abertas no início, sem controlar o estado.", onValueChange: "Chamado quando uma seção abre ou fecha, com a lista das abertas.", disabled: "Desativa todas as seções.", keepMounted: "Mantém no DOM o conteúdo das seções fechadas.", hiddenUntilFound: "Deixa a busca do navegador achar o texto das seções fechadas e abri-las. Usa `hidden=\"until-found\"` e ignora `keepMounted`." }}
>
	O `AccordionItem` recebe um `value` e `disabled`. O `AccordionTrigger` recebe `level` (1 a 6, padrão 3) para o título em volta dele. `AccordionTrigger` e `AccordionPanel` recebem as props do seu elemento.
</Props>

O `Collapsible` abre e fecha um painel só:

<Props
	file="accordion"
	type="CollapsibleProps"
	include={["open", "defaultOpen", "onOpenChange", "disabled"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ open: "Se o painel está aberto. Use com `onOpenChange` para controlar o estado.", defaultOpen: "Se o painel começa aberto, sem controlar o estado.", onOpenChange: "Chamado quando o painel abre ou fecha.", disabled: "Desativa o gatilho." }}
/>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio accordion.

<StylingHooks
	slots={["accordion", "accordion-item", "accordion-header", "accordion-trigger", "accordion-panel", "accordion-panel-content", "collapsible-trigger", "collapsible-panel", "disclosure-chevron", "disclosure-plus"]}
	prefix="accordion"
	attributes={[
		{ attr: "data-open", value: "num item aberto e no seu painel" },
		{ attr: "data-panel-open", value: "no gatilho enquanto o painel está aberto" },
		{ attr: "data-disabled", value: "num item, gatilho e painel desativados" },
		{ attr: "data-starting-style · data-ending-style", value: "enquanto o painel abre e fecha" },
	]}
>

```css
/* um mais que vira menos, só na página de ajuda */
.ajuda [data-slot="accordion"] {
  --cml-accordion-chevron: none;
  --cml-accordion-plus: inline-block;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Vai para o próximo título, ou para os links e campos de um painel aberto." },
		{ key: "Shift + Tab", description: "Volta para o título ou controle anterior." },
		{ key: "Enter / Espaço", description: "Abre ou fecha a seção focada." },
	]}
	notes={[
		"Cada título é um botão dentro de um título (h3, ou o nível que você definir), com aria-expanded. Aberto, o aria-controls aponta para o painel, uma região com o nome do título.",
		"Não há setas entre os títulos: o padrão WAI-ARIA as removeu, e o Tab já passa de um título para o outro.",
		"O conteúdo de painéis fechados sai da página, então o Tab e a busca o pulam, a menos que você use keepMounted ou hiddenUntilFound.",
		"Um título desativado é um botão desativado: o Tab o pula, então o motivo precisa estar em texto visível.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Tabs", description: "Visões da mesma coisa, uma por vez.", href: "/pt-br/docs/components/tabs" },
		{ title: "Card", description: "Um contêiner para um resumo com as suas ações.", href: "/pt-br/docs/components/card" },
		{ title: "Tree view", description: "Itens aninhados que expandem, como pastas.", href: "/pt-br/docs/components/tree-view" },
	]}
/>


# AlertDialog (/pt-br/docs/components/alert-dialog)

<ComponentMeta file="alert-dialog" primitive="Base UI" pattern="WAI-ARIA Alert Dialog" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogTitle, AlertDialogDescription, AlertDialogClose, DialogActions" />

## Anatomia [#anatomia]

As mesmas partes do [Dialog](/pt-br/docs/components/dialog), então cada estilo cuida dos dois do mesmo jeito. O popup ganha `data-kind="alert"` e `role="alertdialog"`.

<Anatomy
	tree={{
		slot: "dialog-popup",
		tag: "div",
		note: "role=alertdialog · data-kind=alert",
		children: [
			{ slot: "dialog-title", tag: "h2", note: "a pergunta" },
			{ slot: "dialog-description", tag: "p", note: "o que vai acontecer" },
			{
				slot: "dialog-actions",
				tag: "div",
				row: true,
				children: [
					{ slot: "dialog-close", tag: "button", note: "Cancelar, recebe o foco" },
					{ slot: "dialog-close", tag: "button", note: "a ação" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Abra: o dialog usa o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="alert-dialog/basic" compact />

<ExampleGrid>
	<Example name="alert-dialog/delete-row" title="Excluir uma linha sem perder o foco">
		Clique em Excluir. A linha e o botão somem, então o `finalFocus` leva o foco para o título da lista e uma mensagem de status confirma.
	</Example>
	<Example name="alert-dialog/type-to-confirm" title="Digitar o nome para confirmar">
		Para os piores erros, como excluir um repositório, peça para digitar o nome. O botão fica desativado até o nome bater.
	</Example>
	<Example name="alert-dialog/blocking" title="Espera a requisição">
		Clique em Sair dos aparelhos. Enquanto a requisição roda, o Esc e o Cancelar não fazem nada, para a pessoa ver se deu certo antes de o dialog fechar.
	</Example>
	<Example name="alert-dialog/initial-focus" title="Foco no Cancelar">
		O foco vai para o primeiro elemento focável. Quando ele é uma caixa de seleção, aponte o `initialFocus` para o Cancelar, assim um Enter apressado não confirma.
	</Example>
	<Example name="alert-dialog/from-menu" title="Aberto de um menu">
		Deixe o dialog fora do menu e controle com `open`: o menu fecha, o dialog fica, e o `finalFocus` volta para o botão do menu.
	</Example>
	<Example name="alert-dialog/irreversible-send" title="Não é só para excluir">
		Tudo o que não tem volta merece uma confirmação, como enviar uma newsletter. Use um botão `solid` quando não for destrutivo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Confirmações protegem as ações que doem quando dão errado. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="alert-dialog/context-delete-project" title="Zona de perigo" uses="Card · Separator · AlertDialog" />
	<Context name="alert-dialog/context-discard-changes" title="Descartar alterações não salvas" uses="Card · Field · Textarea · AlertDialog" />
	<Context name="alert-dialog/context-cancel-plan" title="Cancelar uma assinatura" uses="Card · Badge · AlertDialog" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="alert-dialog/do-action-label" title="Diga a ação no botão.">
		"Excluir 3 arquivos" diz o que acontece. A pessoa responde sem reler a pergunta.
	</Guideline>
	<Guideline kind="dont" name="alert-dialog/dont-ok-label" title="&quot;Tem certeza?&quot; e &quot;OK&quot;.">
		Nenhum dos dois diz o que vai acontecer, então a pessoa clica sem ler.
	</Guideline>
	<Guideline kind="do" name="alert-dialog/do-interrupt" title="Só para decisões que justificam interromper.">
		Excluir um workspace que 12 pessoas usam vale a pausa.
	</Guideline>
	<Guideline kind="dont" name="alert-dialog/dont-info" title="Um alerta para dizer que deu certo.">
		"Salvo" não pede resposta. Interromper por isso ensina a dispensar alertas sem ler. Use um toast.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="alert-dialog" type="AlertDialogProps" include={["open", "defaultOpen", "onOpenChange"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ open: "Se o dialog está aberto. Use com `onOpenChange` para controlar o estado.", defaultOpen: "Se o dialog começa aberto, sem controlar o estado.", onOpenChange: "Chamado quando o dialog abre ou fecha. `eventDetails.reason` diz o motivo, por exemplo `escape-key`. Ignore a chamada para manter o dialog aberto enquanto uma requisição roda." }}
>
	Ele é sempre modal e nunca fecha com clique fora. As outras partes recebem as props do seu elemento, mais `render`.
</Props>

O `AlertDialogContent` decide para onde vai o foco:

<Props file="alert-dialog" type="AlertDialogContentProps" include={["initialFocus", "finalFocus"]}
	types={{ initialFocus: "boolean | RefObject | (openType) => HTMLElement | boolean", finalFocus: "boolean | RefObject | (closeType) => HTMLElement | boolean" }}
	describe={{ initialFocus: "O elemento que recebe o foco ao abrir. Por padrão, o primeiro elemento focável: ponha o Cancelar primeiro.", finalFocus: "O elemento que recebe o foco ao fechar. Por padrão, o gatilho. Defina quando o gatilho some depois da ação." }}
/>

## Styling hooks [#styling-hooks]

Ele usa os mesmos slots do dialog. Use `data-kind="alert"` para mudar só as confirmações.

<StylingHooks
	slots={["dialog-backdrop", "dialog-popup", "dialog-title", "dialog-description", "dialog-actions", "dialog-close"]}
	prefix="dialog"
	attributes={[
		{ attr: "data-kind", value: '"alert" no popup' },
		{ attr: "data-open", value: "presente quando aberto" },
		{ attr: "data-starting-style", value: "presente enquanto abre" },
		{ attr: "data-ending-style", value: "presente enquanto fecha" },
	]}
>

```css
/* mais estreito e centralizado, só nas confirmações */
[data-slot="dialog-popup"][data-kind="alert"] {
  text-align: center;
  inline-size: min(24rem, calc(100vw - 2rem));
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter / Space", description: "No gatilho, abre o dialog com o foco no primeiro botão, Cancelar." },
		{ key: "Tab", description: "Passa entre os botões. O foco fica dentro do dialog e dá a volta." },
		{ key: "Shift + Tab", description: "Volta, indo para o último botão depois do primeiro." },
		{ key: "Escape", description: "Fecha o dialog, como o Cancelar. O foco volta para o gatilho." },
	]}
	notes={[
		"O popup tem role=\"alertdialog\", com o nome do AlertDialogTitle e a descrição do AlertDialogDescription, então o leitor de tela lê a pergunta e a consequência juntas.",
		"Um clique fora não faz nada: o dialog pede uma resposta. O Esc ainda fecha, como um Cancelar.",
		"Ponha o Cancelar primeiro. O foco começa nele, então um Enter por hábito nunca exclui nada.",
		"Depois da ação, o gatilho pode ter sumido: defina o finalFocus e anuncie o resultado com role=\"status\".",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Dialog", description: "Uma janela para uma tarefa, como um formulário.", href: "/pt-br/docs/components/dialog" },
		{ title: "Toast", description: "Avisa que algo deu certo, sem interromper.", href: "/pt-br/docs/components/toast" },
		{ title: "Button", description: "A variante danger para ações destrutivas.", href: "/pt-br/docs/components/button" },
	]}
/>


# Alert (/pt-br/docs/components/alert)

<ComponentMeta file="alert" pattern="WAI-ARIA alert / status" />

<Playground
	name="alert/playground"
	component="Alert"
	controls={[
		{ prop: "tone", options: ["info", "success", "warning", "danger"], default: "info" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Alert, AlertTitle, AlertDescription" />

## Anatomia [#anatomia]

Uma caixa com um ícone escolhido pelo tom, um rótulo opcional e o conteúdo. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="alert"]', color: "#8be36f" },
		{ label: '[data-slot="alert-icon"] · [data-slot="alert-title"]', color: "#ffcf7a" },
		{ label: "descrição (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">icon</span>
	<span className="a-part">title</span>
	<span className="a-label">O login fica fora do ar de 2h00 às 2h15</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="alert/basic" compact />

<ExampleGrid>
	<Example name="alert/tones" title="Tons" wide>
		Escolha o tom pelo que a pessoa precisa fazer: nada (informação), nada mais (sucesso), agir em breve (atenção) ou agir agora para continuar (perigo).
	</Example>
	<Example name="alert/title-only" title="Só o título">
		Quando uma frase basta, deixe a descrição de fora. Um alerta curto é lido mais rápido e atrapalha menos.
	</Example>
	<Example name="alert/with-action" title="Com ação">
		Se dá para resolver, coloque o botão dentro do alerta. Assim a pessoa não precisa procurar a tela de configuração certa.
	</Example>
	<Example name="alert/in-form" title="Dentro de um formulário">
		Coloque o alerta logo acima do campo a que ele se refere. Assim a pessoa lê o risco antes de mudar o valor.
	</Example>
	<Example name="alert/dismissible" title="Com botão de fechar">
		Clique em fechar. Só feche avisos que a pessoa pode ignorar. O foco vai para o botão que aparece no lugar, então quem usa teclado não se perde.
	</Example>
	<Example name="alert/role-alert" title="Urgente ou discreto">
		Os tons de atenção e perigo recebem `role="alert"` e interrompem o leitor de tela. Os de informação e sucesso recebem `role="status"` e esperam a vez.
	</Example>
	<Example name="alert/custom-icon" title="Ícone próprio">
		Troque o ícone quando o seu produto tiver um mais claro, como um brilho para recursos de IA. O tom continua definindo a cor e o papel.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Um alerta fica perto do que ele fala. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="alert/context-billing" title="Pagamento recusado" uses="Card · Alert · Button" />
	<Context name="alert/context-maintenance" title="Status do serviço" uses="Card · Alert · Badge · Button" />
	<Context name="alert/context-sync-error" title="Documentos offline" uses="Card · Alert · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="alert/do-succinct" title="Use atenção quando dá para continuar.">
		Guarde o vermelho para o que realmente impede a pessoa de seguir. Assim ele não perde o sentido.
	</Guideline>
	<Guideline kind="dont" name="alert/dont-overuse-danger" title="Perigo num aviso de rotina.">
		Quando tudo é vermelho, as pessoas param de ler e deixam passar os erros de verdade.
	</Guideline>
	<Guideline kind="do" name="alert/do-actionable" title="Diga como resolver.">
		Explique o problema e dê o próximo passo, de preferência num botão.
	</Guideline>
	<Guideline kind="dont" name="alert/dont-missing-action" title="Um erro sem saída.">
		"Algo deu errado" deixa a pessoa travada e manda ela para o suporte.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="alert"
	type="AlertProps"
	describe={{
		tone: "Define a cor, o ícone e a urgência do anúncio. `warning` e `danger` interrompem o leitor de tela; `info` e `success` esperam.",
		label: "Texto curto de categoria, como \"Aviso\". Alguns estilos mostram ao lado do ícone ou no lugar dele.",
		icon: "Troca o ícone padrão do tom por outro.",
	}}
>
	`AlertTitle` e `AlertDescription` renderizam um `<p>` e aceitam os atributos dele, como `className` e `style`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio alerta.

<StylingHooks
	slots={["alert", "alert-icon", "alert-label", "alert-content", "alert-title", "alert-description"]}
	attributes={[
		{ attr: "data-tone", value: "info · success · warning · danger" },
		{ attr: "role", value: "alert (warning, danger) · status (info, success)" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa pelos botões e links dentro do alerta, na ordem de leitura. O alerta em si nunca recebe foco." },
	]}
	notes={[
		"Um alerta que aparece depois que a página carregou é lido em voz alta: na hora nos tons de atenção e perigo (role=\"alert\"), e depois da fala atual nos de informação e sucesso (role=\"status\").",
		"Um alerta que já está na página quando ela carrega não é anunciado. Coloque no topo do conteúdo a que ele se refere, para a pessoa encontrar enquanto lê.",
		"Quando a pessoa fechar um alerta, mande o foco para o que ficou no lugar, nunca para o topo da página.",
		"A cor nunca é o único sinal: cada tom tem seu ícone, e o título diz o que aconteceu.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Toast", description: "Retorno curto depois de uma ação, que some sozinho.", href: "/pt-br/docs/components/toast" },
		{ title: "ErrorSummary", description: "Lista todos os erros de um formulário depois do envio.", href: "/pt-br/docs/components/error-summary" },
		{ title: "Badge", description: "Um status em uma ou duas palavras, ao lado de um título ou numa tabela.", href: "/pt-br/docs/components/badge" },
	]}
/>


# AppShell (/pt-br/docs/components/app-shell)

<ComponentMeta file="app-shell" pattern="Regiões HTML: header, main, footer" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele não tem estado, então também renderiza no servidor.

<Import names="AppShell, AppShellHeader, AppShellBody, AppShellContent, AppShellFooter, SkipLink" />

## Anatomia [#anatomia]

Uma coluna da altura da tela, com as áreas seguras dos celulares com entalhe como espaçamento. As partes são regiões comuns: o cabeçalho é o banner da página, o conteúdo é o `main` dela. Para ter uma barra lateral, ponha o `AppShellBody` abaixo do cabeçalho: uma linha com a `Sidebar` e o `AppShellContent`, em que o conteúdo ocupa o resto da largura, também ao lado de um trilho.

<Anatomy
	tree={{
		slot: "app-shell",
		tag: "div",
		note: "min-height: 100dvh",
		children: [
			{ slot: "skip-link", tag: "a", note: "aparece no foco" },
			{ slot: "app-shell-header", tag: "header", note: "banner" },
			{
				slot: "app-shell-body",
				tag: "div",
				note: "linha opcional, cresce",
				children: [
					{ slot: "sidebar", tag: "aside", note: "largura fixa" },
					{ slot: "app-shell-content", tag: "main", note: "id=main-content, cresce" },
				],
			},
			{ slot: "app-shell-footer", tag: "footer", note: "opcional" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo de verdade que você pode copiar, encolhido para caber no quadro. A página da documentação em volta já tem um `main`, então o `AppShellContent` de cada quadro recebe `render={<div />}` e um id do `useId`; no seu app, tire os dois.

<Preview name="app-shell/basic" compact />

<ExampleGrid>
	<Example name="app-shell/dashboard" title="Painel com uma faixa lateral" wide>
		O `AppShellBody` põe a barra lateral numa linha embaixo do cabeçalho. Aperte o botão no pé da faixa para mostrar os rótulos; o conteúdo ocupa o resto da largura.
	</Example>
	<Example name="app-shell/admin-table" title="Breadcrumb e busca no cabeçalho" wide>
		O cabeçalho diz onde você está e oferece um jeito de ir a qualquer lugar. Aperte Buscar: a paleta de comandos abre e leva a uma página.
	</Example>
	<Example name="app-shell/mail" title="Só a lista rola" wide>
		Dê `overflow-y: auto` à área de conteúdo e uma altura fixa à moldura. A busca e as caixas de e-mail ficam à vista enquanto as mensagens rolam.
	</Example>
	<Example name="app-shell/settings" title="Links das seções ao lado do formulário" wide>
		Um `SidebarNav` dentro do conteúdo lista as seções de uma página. Quando a moldura fica estreita, ele sobe para cima do formulário em vez de espremê-lo.
	</Example>
	<Example name="app-shell/skip-link" title="Link para pular primeiro" wide>
		Clique acima da moldura e aperte Tab. O `SkipLink` aparece, e o Enter leva o foco direto ao conteúdo, para quem usa teclado não passar por todos os links em toda página.
	</Example>
	<Example name="app-shell/responsive" title="Barra, faixa ou gaveta conforme a largura" wide>
		A moldura não muda sozinha: você escolhe um layout para cada largura. Estreite esta janela para ver a barra inteira virar uma faixa e depois um botão de menu com gaveta.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Telas do tamanho de um celular que você pode copiar, no estilo que escolheu. Cabeçalho e rodapé ficam parados; o meio rola.

<ContextGrid>
	<Context name="app-shell/context-chat" title="Chat de suporte" uses="AppShell · Input · IconButton · Avatar" />
	<Context name="app-shell/context-checkout" title="Finalizar compra" uses="AppShell · Button · Separator" />
	<Context name="app-shell/context-bank" title="App de banco com barra de abas" uses="AppShell · Card · Avatar" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="app-shell/do-one-scroll" title="Só o conteúdo rola.">
		Role a lista: o cabeçalho, com a busca e a conta, fica sempre a um clique.
	</Guideline>
	<Guideline kind="dont" name="app-shell/dont-header-scrolls" title="O cabeçalho rola junto.">
		Role esta. Quando a moldura inteira rola, a pessoa precisa voltar ao topo para chegar ao menu.
	</Guideline>
	<Guideline kind="do" name="app-shell/do-header-essentials" title="O que toda página precisa.">
		O nome do app, a busca, as notificações e a conta. As ações de uma página ficam na própria página.
	</Guideline>
	<Guideline kind="dont" name="app-shell/dont-crowded-header" title="Todas as ações no cabeçalho.">
		Botões que só funcionam numa página viram ruído em todas as outras e quebram linha em telas pequenas.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="app-shell"
	type="SkipLinkProps"
	describe={{
		targetId: "O `id` do elemento para onde ele pula, normalmente o `AppShellContent`.",
		children: "O texto do link, que aparece quando ele recebe o foco. Traduza.",
	}}
>
	`AppShell`, `AppShellHeader` e `AppShellFooter` aceitam as props de `div`, `header` e `footer`. O `AppShellBody` aceita as props de `div`. O `AppShellContent` aceita as props de `main`, e o `id` dele é `"main-content"` por padrão, o mesmo alvo que o `SkipLink` usa quando você não passa `targetId`. Mude os dois juntos e mantenha o id único. O `render` troca o `main` por outro elemento, como `render={<div />}` quando a página já tem um `main`; o id continua, então o link para pular segue funcionando.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou na própria moldura.

<StylingHooks
	slots={["app-shell", "skip-link", "app-shell-header", "app-shell-body", "app-shell-content", "app-shell-footer"]}
	prefix="app-shell"
>

```css
/* um cabeçalho mais alto e um conteúdo que rola sozinho */
.app [data-slot="app-shell"] {
  --cml-app-shell-header-height: 4rem;
  height: 100dvh;
}
.app [data-slot="app-shell-content"] {
  overflow-y: auto;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Do topo da página, a primeira parada é o link para pular, que aparece onde está." },
		{ key: "Enter", description: "No link para pular, leva o foco ao conteúdo, depois do cabeçalho e da barra lateral." },
		{ key: "Shift + Tab", description: "Volta pelos controles do cabeçalho." },
	]}
	notes={[
		"Tenha uma região de cada por página: um header como banner, um AppShellContent como main, um footer. Dentro de outras regiões eles viram caixas comuns, então não ponha a moldura dentro de um main.",
		"Dê nome às regiões de navegação (\"Principal\", \"Seções das configurações\") quando houver mais de uma, para que dê para diferenciá-las na lista de regiões do leitor de tela.",
		"Traduza o texto do link para pular. Dê tabIndex={-1} ao alvo se ele não for um main, para o foco conseguir chegar lá.",
		"Quando só o conteúdo rola, ele precisa ter algo focável ou receber tabIndex={0}, para quem usa teclado conseguir rolar.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Sidebar", description: "A navegação principal do app, na borda esquerda.", href: "/pt-br/docs/components/sidebar" },
		{ title: "Command palette", description: "Busca e executa qualquer coisa a partir de um botão no cabeçalho.", href: "/pt-br/docs/components/command-palette" },
		{ title: "Breadcrumb", description: "Mostra onde a página atual fica, no cabeçalho ou acima do título.", href: "/pt-br/docs/components/breadcrumb" },
	]}
/>


# AspectRatio (/pt-br/docs/components/aspect-ratio)

<ComponentMeta file="layout" pattern="CSS aspect-ratio + object-fit" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. Ele não tem estado, então renderiza no servidor.

<Import names="AspectRatio" />

## Anatomia [#anatomia]

Uma caixa com `position: relative` e overflow escondido. Um `img`, `video` ou `iframe` filho direto ocupa a caixa toda; o resto você sobrepõe com `position: absolute`.

<Anatomy
	tree={{
		slot: "aspect-ratio",
		tag: "div",
		note: "aspect-ratio vindo de ratio",
		row: true,
		children: [
			{ slot: "img · video · iframe", note: "ocupa tudo, object-fit: cover" },
			{ slot: "sua sobreposição", note: "opcional, position: absolute" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="aspect-ratio/basic" compact />

<ExampleGrid>
	<Example name="aspect-ratio/ratios" title="Escolha a proporção">
		Troque a proporção. `ratio` é a largura dividida pela altura, então escreva como fração: `16 / 9` para vídeo, `4 / 3` para fotos, `1` para quadrados, `3 / 4` para retratos.
	</Example>
	<Example name="aspect-ratio/cover-contain" title="cover ou contain">
		`cover`, o padrão, preenche a caixa e corta o que sobra. Use `objectFit: "contain"` na imagem quando todas as bordas importam, como num produto ou num logo.
	</Example>
	<Example name="aspect-ratio/card-grid" title="Cards com fotos de qualquer formato" wide>
		As três fotos são 16:9, 4:3 e 3:4. Cortadas na mesma proporção, os cards ficam da mesma altura e os títulos se alinham.
	</Example>
	<Example name="aspect-ratio/thumbnails" title="Grade de miniaturas">
		Miniaturas quadradas formam uma grade arrumada seja qual for a foto enviada. O `object-position` escolhe que parte da foto sobrevive ao corte.
	</Example>
	<Example name="aspect-ratio/map-embed" title="Embeds precisam de title">
		Um `iframe` ocupa a caixa como uma imagem. Dê a ele um `title` que diga o que tem dentro: é o nome do frame para o leitor de tela.
	</Example>
	<Example name="aspect-ratio/reserve-space" title="Espaço guardado durante o carregamento">
		Recarregue a foto. A caixa já tem altura antes de o arquivo chegar, então o texto de baixo não pula, e uma mensagem de status avisa quando a foto aparece.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Mídia quase nunca aparece sozinha. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="aspect-ratio/context-lesson" title="Aula de curso" uses="AspectRatio · IconButton · Progress · Button" />
	<Context name="aspect-ratio/context-listing" title="Anúncio de aluguel" uses="Card · AspectRatio · Badge · Button" />
	<Context name="aspect-ratio/context-store" title="Endereço da loja" uses="Card · AspectRatio · DataList · Link" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="aspect-ratio/do-same-ratio" title="Uma proporção por linha.">
		Fotos de qualquer formato ficam do mesmo tamanho, e os títulos se alinham.
	</Guideline>
	<Guideline kind="dont" name="aspect-ratio/dont-natural-ratio" title="Cada foto no seu formato.">
		A linha fica torta, e o olho segue os buracos em vez do conteúdo.
	</Guideline>
	<Guideline kind="do" name="aspect-ratio/do-contain-logo" title="contain para logos e produtos.">
		As bordas deles têm significado; mostre tudo, com um pouco de respiro.
	</Guideline>
	<Guideline kind="dont" name="aspect-ratio/dont-cover-logo" title="cover num logo largo.">
		O corte arranca o nome da marca, que é justamente o que importa.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="AspectRatioProps"
	describe={{
		ratio: "Largura dividida pela altura: `16 / 9` para vídeo, `4 / 3` para fotos, `1` para um quadrado.",
	}}
>
	Todos os atributos de uma `<div>` passam adiante, como `style` e `className`. Defina a largura (ou deixe a grade do pai definir); a altura sempre segue a proporção.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use o slot ou defina a custom property no seu CSS.

<StylingHooks
	slots={["aspect-ratio"]}
	prefix="aspect-ratio"
	attributes={[
		{ attr: "data-slot", value: '"aspect-ratio"' },
		{ attr: "--cml-aspect-ratio", value: "a proporção, como número" },
	]}
>

```css
/* vídeo mais largo em telas grandes, mais alto no celular */
.aula [data-slot="aspect-ratio"] {
  --cml-aspect-ratio: 4 / 3;
}
@media (min-width: 48rem) {
  .aula [data-slot="aspect-ratio"] {
    --cml-aspect-ratio: 16 / 9;
  }
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "A caixa não é interativa e não recebe foco. O Tab chega aos controles que você coloca dentro dela, como um botão de play." }]}
	notes={[
		"A caixa não acrescenta role nem nome. O que vai dentro ainda precisa de um: alt em toda imagem com significado, alt=\"\" na decoração.",
		"Todo iframe precisa de um title que diga o que ele mostra (\"Mapa: Rua Augusta, 1200\"); sem ele, o leitor de tela só anuncia \"frame\".",
		"Um botão de play sobre o pôster é um botão só com ícone: dê a ele um nome que inclua o título do vídeo.",
		"O corte do cover pode arrancar textos ou rostos. Não coloque informação nas bordas de uma imagem que pode ser cortada.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Image", description: "Uma foto com legenda, skeleton de carregamento e substituto.", href: "/pt-br/docs/components/image" },
		{ title: "Avatar", description: "Uma foto pequena e redonda de uma pessoa, com iniciais quando falha.", href: "/pt-br/docs/components/avatar" },
		{ title: "Carousel", description: "Vários slides num só lugar, um de cada vez.", href: "/pt-br/docs/components/carousel" },
	]}
/>


# Avatar (/pt-br/docs/components/avatar)

<ComponentMeta file="avatar" primitive="Base UI" pattern="WAI-ARIA img / group" />

<Playground
	name="avatar/playground"
	component="Avatar"
	controls={[
		{ prop: "size", options: ["sm", "md", "lg"], default: "md" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no navegador, porque espera a foto carregar.

<Import names="Avatar, AvatarGroup" />

## Anatomia [#anatomia]

Uma caixa redonda com a foto, ou com o substituto enquanto a foto carrega ou quando ela falha. O `AvatarGroup` sobrepõe vários deles.

<Anatomy tree={{ slot: "avatar-group", tag: "div", note: "opcional", row: true, children: [{ slot: "avatar", tag: "span", note: "foto ou substituto" }, { slot: "avatar", tag: "span", note: "foto ou substituto" }] }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="avatar/basic" compact />

<ExampleGrid>
	<Example name="avatar/with-image" title="Com foto">
		Sozinho, o avatar precisa dizer quem é. Coloque o nome da pessoa no `alt`, nunca "foto" ou "avatar".
	</Example>
	<Example name="avatar/beside-name" title="Ao lado do nome">
		Quando o nome está logo ao lado, esconda o avatar com `aria-hidden`. Senão o leitor de tela fala o nome duas vezes.
	</Example>
	<Example name="avatar/sizes" title="Tamanhos">
		Pequeno para comentários e listas compactas, médio para menus e cards, grande para o topo de um perfil. Use um tamanho só por lista.
	</Example>
	<Example name="avatar/fallback" title="Iniciais e ícone">
		Sem foto, duas iniciais já diferenciam as pessoas. Use o ícone para visitantes e contas sem nome. O `alt` dá nome ao avatar com a foto ou com o substituto na tela, então o leitor de tela fala o nome, não as iniciais. Quando o nome já aparece ao lado, deixe o `alt` vazio.
	</Example>
	<Example name="avatar/broken-image" title="Foto que não carrega">
		Se a foto falhar, as iniciais continuam no lugar. Sempre passe um `fallback`, para um link quebrado nunca deixar um círculo vazio.
	</Example>
	<Example name="avatar/group" title="Grupo com contagem">
		Mostre alguns rostos e um "+3" para o resto. Dê ao grupo um nome com o total, como "7 pessoas no…", e dê um nome ao "+3" também.
	</Example>
	<Example name="avatar/interactive-status" title="Presença">
		Clique no botão. O status é uma palavra num badge, não só um ponto verde, e uma região de status lê a mudança em voz alta.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O avatar põe um rosto ao lado do que a pessoa fez. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="avatar/context-comment" title="Comentário" uses="Card · Avatar" />
	<Context name="avatar/context-team-card" title="Card de alguém da equipe" uses="Card · Avatar · Button" />
	<Context name="avatar/context-activity" title="Histórico de atividades" uses="Card · Avatar" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="avatar/do-accessible-label" title="Diga o nome uma vez só.">
		Com o nome ao lado, o avatar é enfeite: esconda do leitor de tela.
	</Guideline>
	<Guideline kind="dont" name="avatar/dont-decorative-alt" title='"Foto de…" ao lado do nome.'>
		O leitor de tela fala "Foto de Mariana Lima, Mariana Lima". A repetição não acrescenta nada.
	</Guideline>
	<Guideline kind="do" name="avatar/do-contrast-fallback" title="Duas iniciais.">
		As iniciais do nome e do sobrenome diferenciam as pessoas, mesmo sem foto.
	</Guideline>
	<Guideline kind="dont" name="avatar/dont-missing-fallback" title="Um ponto de interrogação.">
		O "?" parece um erro e não diz nada sobre quem é.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="avatar"
	type="AvatarProps"
	describe={{
		src: "Endereço da foto. Enquanto ela carrega, ou se falhar, aparece o substituto.",
		alt: "O nome da pessoa, lido pelo leitor de tela com a foto ou com as iniciais. Deixe vazio quando o nome já aparece ao lado.",
		fallback: "O que aparece sem foto, enquanto ela carrega ou quando falha. Normalmente duas iniciais ou um ícone.",
		size: "`sm` para comentários e listas compactas, `md` para menus e cards, `lg` para o topo de um perfil.",
	}}
>
	Os outros atributos, como `role`, `aria-label` e `aria-hidden`, vão para o `<span>` de fora. O `AvatarGroup` renderiza um `<div role="group">` e precisa de um `aria-label`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio avatar.

<StylingHooks
	slots={["avatar", "avatar-group"]}
	attributes={[
		{ attr: "data-size", value: "sm · md · lg" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O avatar nunca recebe foco. Para abrir um perfil, coloque o avatar e o nome dentro de um link." }]}
	notes={[
		"Com alt, o avatar vira uma imagem só, com o nome da pessoa (role=\"img\"), seja a foto ou as iniciais. Ao lado de um nome visível, deixe o alt vazio para o nome não ser lido duas vezes.",
		"Ao lado de um nome visível, esconda o avatar com aria-hidden=\"true\", para o nome não ser lido duas vezes.",
		"Dê ao AvatarGroup um nome com o total (\"7 pessoas no projeto\") e dê um nome ao avatar \"+3\" também (\"e mais 3\").",
		"Presença precisa de uma palavra, não só de um ponto colorido. Quem não enxerga a cor também precisa saber quem está online.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Image", href: "/pt-br/docs/components/image", description: "Para fotos que são conteúdo, e não o rosto de alguém." },
		{ title: "Badge", href: "/pt-br/docs/components/badge", description: "Um status como Online ou Ausente, ao lado do nome." },
		{ title: "Card", href: "/pt-br/docs/components/card", description: "Guarda um perfil, um comentário ou alguém da equipe." },
	]}
/>


# Badge (/pt-br/docs/components/badge)

<ComponentMeta file="display" pattern="Static text" />

<Playground
	name="badge/playground"
	component="Badge"
	label="Ativo"
	controls={[
		{ prop: "variant", options: ["soft", "solid", "outline"], default: "soft" },
		{ prop: "tone", options: ["neutral", "info", "success", "warning", "danger"], default: "neutral" },
		{ prop: "dot", type: "boolean", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Badge" />

## Anatomia [#anatomia]

Um `<span>` com o texto e, se você pedir, um pontinho antes dele. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy tree={{ slot: "badge", tag: "span", note: "texto como children", children: [{ slot: "badge-dot", tag: "span", note: "com dot" }] }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="badge/basic" compact />

<ExampleGrid>
	<Example name="badge/variants" title="Variantes" wide>
		O fundo suave serve para o dia a dia. Guarde o preenchido para o badge que precisa chamar atenção na tela, e use o contorno quando houver muitos juntos.
	</Example>
	<Example name="badge/tones" title="Tons" wide>
		Escolha o tom pelo sentido: cinza para neutro, azul para informação, verde quando deu certo, amarelo quando pede atenção em breve e vermelho quando algo falhou.
	</Example>
	<Example name="badge/dot-status" title="Ponto de status">
		O ponto ajuda a achar um estado ao vivo, como online ou em reunião, numa lista. Quem dá o sentido é a palavra ao lado.
	</Example>
	<Example name="badge/with-icon" title="Com ícone">
		O ícone ajuda a bater o olho, mas a palavra precisa dizer tudo. Marque o ícone com `aria-hidden` para ele não ser lido duas vezes.
	</Example>
	<Example name="badge/count" title="Contagem com contexto">
		Quem ouve "Caixa de entrada 3" no leitor de tela não sabe 3 de quê. Coloque "não lidas" como texto escondido dentro do badge.
	</Example>
	<Example name="badge/truncate" title="Texto longo">
		Nomes digitados pelas pessoas podem ficar compridos. Limite a largura e corte com reticências. O nome inteiro continua na página para o leitor de tela e no `title` para quem usa mouse.
	</Example>
	<Example name="badge/in-table" title="Numa tabela" wide>
		Um badge por linha, numa coluna só dele, deixa a pessoa comparar os status de cima a baixo de relance.
	</Example>
	<Example name="badge/interactive-filter" title="Contagem nos filtros">
		Clique num filtro. O badge só mostra o número. Quem a pessoa aperta é o `Toggle` em volta, que também avisa se está ligado.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O badge fica ao lado do que ele descreve. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="badge/context-profile" title="Perfil de alguém da equipe" uses="Card · Avatar · Badge" />
	<Context name="badge/context-order" title="Status do pedido" uses="Card · Badge" />
	<Context name="badge/context-issue" title="Etiquetas de um chamado" uses="Card · Badge" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="badge/do-label" title="Diga o status com palavras simples.">
		"Pagamento confirmado" fica claro para todo mundo, com ou sem a cor.
	</Guideline>
	<Guideline kind="dont" name="badge/dont-color-only" title="Códigos internos.">
		"Status 200" faz sentido para quem programou, não para o cliente que está lendo.
	</Guideline>
	<Guideline kind="do" name="badge/do-succinct" title="Uma ou duas palavras.">
		Um badge curto é lido num relance e cabe no celular.
	</Guideline>
	<Guideline kind="dont" name="badge/dont-sentence" title="Uma frase dentro do badge.">
		Texto longo é cortado ou quebra o layout. Explicações vão no texto ou num Alert.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="display"
	type="BadgeProps"
	describe={{
		variant: "O peso visual: fundo suave no dia a dia, preenchido para destacar, contorno quando há muitos juntos.",
		tone: "A cor pelo sentido do status: neutro, informação, sucesso, atenção ou perigo.",
		dot: "Mostra um pontinho antes do texto, bom para estados ao vivo como online.",
	}}
>
	O `Badge` renderiza um `<span>` e aceita os atributos dele, como `className`, `style` e `title`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio badge.

<StylingHooks
	slots={["badge", "badge-dot"]}
	attributes={[
		{ attr: "data-variant", value: "soft · solid · outline" },
		{ attr: "data-tone", value: "neutral · info · success · warning · danger" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O badge é texto e nunca recebe foco. Para ele ser clicável, use um Chip ou coloque dentro de um botão ou link." }]}
	notes={[
		"A cor nunca é o único sinal: o texto diz o status, e quem não enxerga a cor entende do mesmo jeito.",
		"Um número sozinho precisa de contexto. Coloque o que ele conta como texto escondido (\"3 não lidas\") ou diga no nome do controle em volta.",
		"Um badge que muda enquanto a pessoa está na página não é anunciado. Quando a mudança importa, avise numa mensagem de status (role=\"status\").",
		"Para etiquetas que a pessoa seleciona ou remove, use o Chip: ele é um botão de verdade, com foco e nome.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Chip", href: "/pt-br/docs/components/chip", description: "Uma etiqueta que a pessoa seleciona, usa como filtro ou remove." },
		{ title: "Alert", href: "/pt-br/docs/components/alert", description: "Quando o status precisa de uma frase e, talvez, de uma ação." },
		{ title: "Avatar", href: "/pt-br/docs/components/avatar", description: "A foto ou as iniciais de uma pessoa, muitas vezes com um badge de status." },
	]}
/>


# Box (/pt-br/docs/components/box)

<ComponentMeta file="layout" pattern="Landmarks e listas do HTML" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. Ele não tem estado, então renderiza no servidor.

<Import names="Box" />

## Anatomia [#anatomia]

O Box é um elemento só, com `data-slot="box"` e nenhum estilo próprio. O que ele entrega é a tag: aqui uma seção tem um cabeçalho e uma lista, cada um um Box com um `as` diferente.

<Anatomy
	tree={{
		slot: "box",
		tag: "section",
		note: 'as="section", nomeada pelo título',
		children: [
			{ slot: "box", tag: "header", note: 'as="header"' },
			{ slot: "box", tag: "ul", note: 'as="ul"', children: [{ slot: "box", tag: "li", note: 'as="li", um por item' }] },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="box/basic" compact />

<ExampleGrid>
	<Example name="box/as-list" title="Uma lista de coisas">
		Três arquivos são uma lista, então renderize `ul` e `li`. O leitor de tela anuncia "lista, 3 itens" e a pessoa sabe quanto vem pela frente.
	</Example>
	<Example name="box/as-article" title="Um post que se sustenta sozinho">
		`as="article"` para conteúdo que faz sentido isolado, como um post ou um comentário. O `header` e o `footer` dentro dele não viram landmarks da página.
	</Example>
	<Example name="box/as-nav" title="Landmark de navegação">
		`as="nav"` com `aria-label` deixa quem usa leitor de tela pular direto para esses links. Marque a página atual com `aria-current="page"`.
	</Example>
	<Example name="box/as-search" title="Landmark de busca">
		Um formulário com `role="search"` vira um landmark que a pessoa alcança de qualquer lugar. Dê um nome quando a página tiver mais de uma busca.
	</Example>
	<Example name="box/ordered" title="Com ordem ou sem">
		Desligue e ligue. Passos que precisam acontecer em sequência são um `ol`; os números vêm do navegador e o leitor de tela diz "1 de 4".
	</Example>
	<Example name="box/tokens" title="Espaço e cor com tokens">
		O Box não tem props de padding nem de fundo. Estilize com tokens `var(--cml-…)` e ele muda com o estilo, como os componentes ao redor.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="box/context-settings" title="Formulário de preferências" uses="Box · Heading · Switch · Button" />
	<Context name="box/context-feed" title="Mural de novidades da equipe" uses="Box · Badge · Avatar · Separator" />
	<Context name="box/context-footer" title="Rodapé do site" uses="Box · Grid · Link · Separator" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="box/do-list" title="Lista renderizada como lista.">
		O leitor de tela conta os itens e deixa a pessoa pular o grupo inteiro.
	</Guideline>
	<Guideline kind="dont" name="box/dont-divs" title="Itens numa fileira de divs.">
		Parece igual, mas o leitor de tela lê três palavras soltas, sem pista de que andam juntas.
	</Guideline>
	<Guideline kind="do" name="box/do-nav" title="nav para links que levam a outras páginas.">
		Quem pula entre landmarks espera encontrar ali a navegação do site ou da seção.
	</Guideline>
	<Guideline kind="dont" name="box/dont-nav" title="nav em volta de botões de filtro.">
		Filtros mudam a lista desta página; não são navegação. Um grupo simples (ou um Toolbar) mantém a lista de landmarks curta e honesta.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="BoxProps"
	types={{ as: '"div" | "section" | "article" | "nav" | "ul" | "li" | …' }}
	describe={{ as: "Elemento renderizado, para a semântica certa (por exemplo `as=\"ul\"`)." }}
>
	O `as` aceita `div`, `section`, `article`, `main`, `aside`, `header`, `footer`, `nav`, `ul`, `ol`, `li`, `span`, `form` e `figure`. Todas as outras props vão para esse elemento, então `aria-*`, `role`, `id` e eventos funcionam normalmente.
</Props>

## Styling hooks [#styling-hooks]

O Box não desenha nada, então o gancho é o atributo: estilize a partir de um elemento pai ou de uma classe.

<StylingHooks slots={["box"]} attributes={[{ attr: "data-slot", value: '"box"' }]}>

```css
/* um painel discreto para cada seção Box da página de preferências */
.settings [data-slot="box"]:where(section) {
  padding: var(--cml-surface-padding);
  border-radius: var(--cml-radius-surface);
  background: var(--cml-surface);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O Box não renderiza nenhum elemento interativo. O foco passa pelos filhos na ordem do DOM." }]}
	notes={[
		"Escolha a tag pelo conteúdo: uma seção com título, um artigo, uma lista. A tag é o que o leitor de tela anuncia; o visual vem do CSS.",
		"Uma section só vira landmark de região quando tem nome, então passe aria-labelledby com o id do título dela.",
		"main, header e footer só são landmarks da página no nível de cima. Use main uma vez por página e não coloque dentro de um layout que já tem um.",
		"Layout nunca carrega significado sozinho: se dois itens estão relacionados, diga isso na marcação (uma lista, um título), não só com espaço ou posição.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Stack", description: "Uma coluna ou linha com espaço da escala de espaçamento.", href: "/pt-br/docs/components/stack" },
		{ title: "Grid", description: "Colunas que se alinham, ou quantas couberem.", href: "/pt-br/docs/components/grid" },
		{ title: "Card", description: "Uma superfície com cabeçalho, conteúdo e rodapé.", href: "/pt-br/docs/components/card" },
	]}
/>


# Breadcrumb (/pt-br/docs/components/breadcrumb)

<ComponentMeta file="breadcrumb" pattern="WAI-ARIA Breadcrumb" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele não tem estado nem efeitos, então também renderiza no servidor; o `BreadcrumbLink` aceita a prop `render` para usar o link do seu roteador.

<Import names="Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis" />

## Anatomia [#anatomia]

Um landmark `nav` em volta de uma lista ordenada. Cada nível é um item; os separadores são itens próprios, escondidos do leitor de tela, e o último item é a página atual.

<Anatomy
	tree={{
		slot: "breadcrumb",
		tag: "nav",
		note: "aria-label",
		children: [
			{
				slot: "breadcrumb-list",
				tag: "ol",
				row: true,
				children: [
					{ slot: "breadcrumb-item", tag: "li", children: [{ slot: "breadcrumb-link", tag: "a" }] },
					{ slot: "breadcrumb-separator", tag: "li", note: "aria-hidden", children: [{ slot: "icon", tag: "svg" }, { slot: "breadcrumb-slash", tag: "span" }] },
					{ slot: "breadcrumb-item", tag: "li", children: [{ slot: "breadcrumb-ellipsis", tag: "span", note: "opcional, role=img ou um botão" }] },
					{ slot: "breadcrumb-item", tag: "li", children: [{ slot: "breadcrumb-page", tag: "span", note: "aria-current=page" }] },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor da marca escolhidos na barra acima.

<Preview name="breadcrumb/basic" compact />

<ExampleGrid>
	<Example name="breadcrumb/ecommerce" title="Caminho de categorias">
		Espelhe a árvore do catálogo, para que quem chegou numa categoria pela busca possa subir um nível e ver as categorias vizinhas.
	</Example>
	<Example name="breadcrumb/settings" title="Caminho nas configurações">
		É fácil se perder em telas de configuração profundas. A trilha termina no título da própria página, que o repete logo abaixo.
	</Example>
	<Example name="breadcrumb/collapsed" title="Níveis do meio recolhidos">
		Aperte o botão …. Deixe o primeiro nível e os dois últimos à vista e coloque o resto num `Menu` aberto por um `BreadcrumbEllipsis`; o nome dele diz quantos níveis esconde.
	</Example>
	<Example name="breadcrumb/with-icons" title="Com ícones">
		Uma casinha sozinha não diz nada ao leitor de tela. Dê nome a um link só de ícone com `VisuallyHidden` e marque todo ícone com `aria-hidden`.
	</Example>
	<Example name="breadcrumb/truncate" title="Nomes longos">
		Corte um nome longo na tela com reticências, nunca no texto: o leitor de tela continua lendo o nome inteiro, e o título abaixo mostra ele completo.
	</Example>
	<Example name="breadcrumb/slash" title="Separador de barra">
		Todo separador traz uma seta e uma barra. Defina `--cml-crumb-chevron: none` e `--cml-crumb-slash: inline` para caminhos de arquivo, em que a barra é a convenção.
	</Example>
	<Example name="breadcrumb/next-link" title="Com o link do Next.js">
		`render={<NextLink href="…" />}` mantém a navegação no cliente e o prefetch, e o link continua com o slot, o estilo e o anel de foco.
	</Example>
	<Example name="breadcrumb/phone" title="No celular">
		A lista quebra para uma segunda linha em vez de rolar para o lado. Quando ela ocuparia três linhas, recolha os níveis do meio.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Estas são partes inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="breadcrumb/context-product" title="Página de produto" uses="Breadcrumb · Badge · Button · Card" />
	<Context name="breadcrumb/context-files" title="Navegador de arquivos" uses="Breadcrumb · Table · Link · Badge" />
	<Context name="breadcrumb/context-settings" title="Formulário de configurações" uses="Breadcrumb · Field · Input · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="breadcrumb/do-hierarchy" title="Mostre onde a página mora.">
		O mesmo pedido fica sempre dentro de Pedidos, não importa como a pessoa chegou até ele.
	</Guideline>
	<Guideline kind="dont" name="breadcrumb/dont-history" title="Mostrar as páginas visitadas.">
		Para isso existe o botão Voltar. Uma trilha que muda a cada visita não ensina a estrutura.
	</Guideline>
	<Guideline kind="do" name="breadcrumb/do-current-last" title="Termine na página atual, como texto.">
		O `BreadcrumbPage` diz "você está aqui" com `aria-current="page"` e não é um link para si mesmo.
	</Guideline>
	<Guideline kind="dont" name="breadcrumb/dont-current-link" title="Fazer da página atual um link.">
		Parece outro lugar para ir, e seguir o link só recarrega a mesma página.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="breadcrumb"
	type="BreadcrumbProps"
	describe={{
		"aria-label": "Nome acessível do landmark `nav`. Traduza, e use um nome único quando a página tiver vários landmarks de navegação.",
	}}
>
	`BreadcrumbItem`, `BreadcrumbPage` e `BreadcrumbSeparator` aceitam as props do `li`, do `span` e do `li`. O `BreadcrumbLink` aceita as props de um `a`, mais `render` para usar o link do seu roteador. O `BreadcrumbEllipsis` representa níveis recolhidos: sozinho é uma imagem chamada "Mais páginas"; com `render={<button type="button" />}`, como gatilho de um menu, é um botão. Passe `aria-label` para dizer quantos níveis ele esconde.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou na própria trilha.

<StylingHooks
	slots={["breadcrumb", "breadcrumb-list", "breadcrumb-item", "breadcrumb-link", "breadcrumb-page", "breadcrumb-separator", "breadcrumb-slash", "breadcrumb-ellipsis"]}
	attributes={[
		{ attr: "aria-current", value: '"page" no breadcrumb-page' },
		{ attr: "--cml-crumb-chevron", value: "block · none" },
		{ attr: "--cml-crumb-slash", value: "none · inline" },
	]}
>

```css
/* barras em vez de setas no navegador de arquivos */
.files [data-slot="breadcrumb"] {
  --cml-crumb-chevron: none;
  --cml-crumb-slash: inline;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Vai para o próximo link da trilha. A página atual e os separadores são pulados." },
		{ key: "Enter", description: "Segue o link focado." },
		{ key: "Enter / Espaço / Seta para baixo", description: "No botão … de níveis recolhidos, abre o menu com o primeiro nível focado." },
		{ key: "Seta para baixo", description: "Nesse menu, vai para o próximo nível." },
		{ key: "Escape", description: "Fecha esse menu e devolve o foco ao botão …." },
	]}
	notes={[
		"É um landmark nav chamado \"Breadcrumb\". Traduza o nome com aria-label; o leitor de tela mostra ele na lista de landmarks da página.",
		"Os níveis são uma lista ordenada, então o leitor de tela diz quantos são. A página atual tem aria-current=\"page\" e é texto simples.",
		"Os separadores têm aria-hidden: o leitor de tela lê os nomes um depois do outro, sem \"barra\" ou \"maior que\" no meio.",
		"Sozinho, o BreadcrumbEllipsis é uma imagem chamada \"Mais páginas\" (das mensagens); como gatilho de menu é um botão com o mesmo nome, que o aria-label pode trocar.",
		"Os links têm pelo menos 24px de altura (WCAG 2.5.8). Um link só de ícone precisa de um nome em texto, por exemplo com VisuallyHidden.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Link", description: "Links no texto e soltos, com o seu roteador.", href: "/pt-br/docs/components/link" },
		{ title: "Menu", description: "Guarda os níveis que uma trilha longa recolhe.", href: "/pt-br/docs/components/menu" },
		{ title: "Pagination", description: "Avança pelas páginas de uma lista longa.", href: "/pt-br/docs/components/pagination" },
	]}
/>


# Button (/pt-br/docs/components/button)

<ComponentMeta file="button" primitive="Base UI" pattern="WAI-ARIA Button" />

<Playground
	name="button/playground"
	component="Button"
	label="Publicar"
	controls={[
		{ prop: "variant", options: ["solid", "outline", "ghost", "danger"], default: "solid" },
		{ prop: "size", options: ["sm", "md", "lg"], default: "md" },
		{ prop: "loading", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O estilo carregado cuida do visual.

<Import names="Button, IconButton, ButtonGroup" />

## Anatomia [#anatomia]

Um elemento com até três partes. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="button"]', color: "#8be36f" },
		{ label: '[data-slot="spinner"] · [data-slot="icon"]', color: "#ffcf7a" },
		{ label: "rótulo (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">spinner</span>
	<span className="a-part">icon</span>
	<span className="a-label">Publicar</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="button/variants" compact />

<ExampleGrid>
	<Example name="button/sizes" title="Tamanhos">
		`sm`, `md` e `lg` seguem as alturas de controle do estilo, então um formulário e seus botões sempre ficam alinhados.
	</Example>
	<Example name="button/with-icon" title="Com ícone">
		Ícone antes do rótulo para algo novo, depois dele para direção ou download. Marque com `data-slot="icon"` e `aria-hidden`.
	</Example>
	<Example name="button/icon-only" title="Só ícone">
		O `IconButton` exige `aria-label`. Use junto com um `Tooltip` para quem enxerga também ver o nome.
	</Example>
	<Example name="button/as-link" title="Como link">
		Navegação é link, não botão. `render={<a href="…" />}` com `nativeButton={false}` mantém o visual e entrega uma âncora de verdade.
	</Example>
	<Example name="button/saving" title="Salvando, depois salvo">
		Clique. O `loading` mantém a largura e o foco enquanto a requisição roda; uma mensagem de status anuncia o resultado.
	</Example>
	<Example name="button/confirm" title="Destrutivo, com confirmação">
		Clique. Uma ação `danger` abre um `AlertDialog`. A escolha segura vem primeiro e recebe o foco.
	</Example>
	<Example name="button/group" title="Em grupo">
		O `ButtonGroup` junta ações relacionadas com `role="group"`. Para navegar entre elas com as setas, use o `Toolbar`.
	</Example>
	<Example name="button/disabled-reason" title="Desativado, com o motivo">
		Nunca deixe a pessoa adivinhando. Diga o que falta e ligue com `aria-describedby`, ou mantenha o botão ativo e valide no envio.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Botão nunca aparece sozinho. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="button/context-pricing" title="Cartão de preço" uses="Card · Badge · Button" />
	<Context name="button/context-empty" title="Estado vazio" uses="EmptyState · Button" />
	<Context name="button/context-consent" title="Banner de consentimento" uses="Card · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="button/do-one-solid" title="Um botão sólido por área.">
		Ele mostra qual é a ação principal.
	</Guideline>
	<Guideline kind="dont" name="button/dont-many-solid" title="Três botões sólidos lado a lado.">
		Nada se destaca, então nada fica claro.
	</Guideline>
	<Guideline kind="do" name="button/do-verb" title="Comece com um verbo.">
		Diga o que acontece: "Emitir nota", "Salvar alterações".
	</Guideline>
	<Guideline kind="dont" name="button/dont-vague" title="Rótulos vagos.">
		"OK" e "Clique aqui" não dizem nada fora de contexto, nem para um leitor de tela que lista os botões.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="button" type="ButtonProps" include={["disabled", "render", "nativeButton", "focusableWhenDisabled"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ variant: "Peso visual: `solid` para a ação principal, `outline` para as secundárias, `ghost` para as discretas, `danger` para as destrutivas.", size: "Altura, espaçamento e tamanho do texto, da escala de controles do estilo. `icon` deixa o botão quadrado.", loading: "Mostra um spinner e desativa o botão, mantendo o foco nele.", disabled: "Desativa o botão e o tira da ordem de tabulação.", render: "Troca o elemento renderizado, por exemplo por um link, mantendo o comportamento.", nativeButton: "Se o elemento final é um `<button>` nativo. Use `false` quando o `render` não for um botão.", focusableWhenDisabled: "Se o botão continua focável quando desativado." }}
>
	O `IconButton` recebe as mesmas props, sem `size` e com `aria-label` obrigatório. Os atributos nativos de botão passam direto.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio botão.

<StylingHooks
	slots={["button"]}
	attributes={[
		{ attr: "data-slot", value: '"button"' },
		{ attr: "data-variant", value: "solid · outline · ghost · danger" },
		{ attr: "data-size", value: "sm · md · lg · icon" },
		{ attr: "data-loading", value: "presente durante o carregamento" },
		{ attr: "data-disabled", value: "presente quando desativado" },
	]}
>

```css
/* botão principal em pílula, só nesta seção */
.checkout [data-slot="button"][data-variant="solid"] {
  --cml-radius-control: 999px;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "Ativa o botão." },
		{ key: "Space", description: "Ativa o botão ao soltar." },
		{ key: "Tab", description: "Leva o foco até ele, inclusive durante o carregamento." },
	]}
	notes={[
		"Texto e anel de foco passam no WCAG 2.2 AA nos 13 estilos, claro e escuro, com qualquer cor de marca.",
		"Durante o carregamento ele marca aria-busy e continua focável, então quem usa teclado ou leitor de tela não perde o lugar.",
		"Renderizado como outro elemento pelo render, mantém o papel de botão e o comportamento de teclado.",
		"Respeita o movimento reduzido: o efeito de clique e o spinner ficam mais calmos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Toggle", description: "Um botão que fica pressionado.", href: "/pt-br/docs/components/toggle" },
		{ title: "Spinner", description: "Indicador de carregamento sozinho.", href: "/pt-br/docs/components/spinner" },
		{ title: "Dialog", description: "Confirme ou peça dados antes de agir.", href: "/pt-br/docs/components/dialog" },
	]}
/>


# Calendar (/pt-br/docs/components/calendar)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Grid" />

<Playground
	name="calendar/playground"
	component="Calendar"
	controls={[
		{ prop: "weekdayStyle", options: ["narrow", "short", "long"], default: "short" },
		{ prop: "firstDayOfWeek", options: ["sun", "mon"], default: "sun" },
		{ prop: "readOnly", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. As datas são objetos do `@internationalized/date`, reexportados pelo Camaleo.

<Import names="Calendar, CalendarDate, isWeekend" />

## Anatomia [#anatomia]

Um cabeçalho com o mês e duas setas, a grade de dias e um rodapé opcional. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="calendar"]', color: "#8be36f" },
		{ label: '[data-slot="calendar-title"] · [data-slot="calendar-nav-button"] · [data-slot="calendar-footer"]', color: "#ffcf7a" },
		{ label: '[data-slot="calendar-grid"] · [data-slot="calendar-cell"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">título</span>
	<span className="a-part">‹ ›</span>
	<span className="a-label">grade</span>
	<span className="a-part">rodapé</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="calendar/basic" compact />

<ExampleGrid>
	<Example name="calendar/controlled" title="Controlado, com resumo">
		Escolha um dia. `value` e `onChange` guardam a data no seu estado, e a frase abaixo escreve ela por extenso, com o dia da semana.
	</Example>
	<Example name="calendar/min-max" title="Mínimo e máximo">
		`minValue` e `maxValue` desativam os dias fora do período, e as setas param no primeiro e no último mês.
	</Example>
	<Example name="calendar/weekends" title="Fins de semana indisponíveis">
		`isDateUnavailable` com `isWeekend` segue o idioma. Dias indisponíveis continuam focáveis e são anunciados como indisponíveis, então diga o motivo no rodapé.
	</Example>
	<Example name="calendar/booked" title="Dias lotados">
		Devolva `true` para os dias que a sua API diz estarem cheios. O risco não é o único sinal: o rodapé explica em palavras.
	</Example>
	<Example name="calendar/first-day" title="Semana começando na segunda">
		O idioma define o primeiro dia: domingo no Brasil e nos EUA. `firstDayOfWeek="mon"` combina com um time que planeja em semanas ISO.
	</Example>
	<Example name="calendar/read-only" title="Somente leitura">
		`readOnly` mostra uma data confirmada que a pessoa ainda navega e lê, diferente de `disabled`, que tira o calendário da ordem do Tab.
	</Example>
	<Example name="calendar/focused-month" title="Abrir em outro mês">
		Sem valor, o calendário abre no mês de hoje. `defaultFocusedValue` abre no mês que a pessoa precisa, e renderiza igual no servidor e no navegador.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Calendários vivem em agendamentos e checkouts. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="calendar/context-appointment" title="Agendar consulta" uses="Card · Calendar · ToggleGroup · Button" />
	<Context name="calendar/context-delivery" title="Dia da entrega" uses="Card · Calendar · Button" />
	<Context name="calendar/context-payment" title="Agendar pagamento" uses="Card · Calendar · Badge · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="calendar/do-explain-unavailable" title="Diga por que os dias estão indisponíveis.">
		Uma linha curta no rodapé responde a dúvida antes de a pessoa sair clicando.
	</Guideline>
	<Guideline kind="dont" name="calendar/dont-unexplained" title="Dias indisponíveis sem motivo.">
		A pessoa testa um por um, e o leitor de tela só diz "indisponível".
	</Guideline>
	<Guideline kind="do" name="calendar/do-near-date" title="Calendário para datas das próximas semanas.">
		O mês na tela é o mesmo de onde a pessoa vai escolher.
	</Guideline>
	<Guideline kind="dont" name="calendar/dont-birth-date" title="Calendário para data de nascimento.">
		Chegar em 1994 leva centenas de cliques. Use um [Date field](/pt-br/docs/components/date-field) e deixe a pessoa digitar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="CalendarProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "firstDayOfWeek", "focusedValue", "defaultFocusedValue", "onFocusChange", "autoFocus"]}
	types={{ value: "DateValue | null", defaultValue: "DateValue | null", onChange: "(value: DateValue) => void", minValue: "DateValue | null", maxValue: "DateValue | null", isDateUnavailable: "(date: DateValue) => boolean", firstDayOfWeek: "\"sun\" | \"mon\" | \"tue\" | \"wed\" | \"thu\" | \"fri\" | \"sat\"", focusedValue: "DateValue | null", defaultFocusedValue: "DateValue | null", onFocusChange: "(date: CalendarDate) => void" }}
	describe={{ className: "Classes do elemento raiz.", style: "Estilos inline do elemento raiz.", disabled: "Desativa todos os dias e as setas, e tira a grade da ordem do Tab.", readOnly: "Mostra o valor sem deixar a pessoa mudar. Os dias continuam focáveis.", invalid: "Marca a seleção como inválida, para erros que vêm da sua aplicação.", locale: "Idioma BCP 47 dos nomes dos meses, dos dias da semana e do primeiro dia da semana, como `\"pt-BR\"`. Por padrão, o do `I18nProvider` mais próximo ou o do navegador.", weekdayStyle: "Como os dias da semana aparecem no cabeçalho: `\"narrow\"`, `\"short\"` (padrão) ou `\"long\"`.", previousLabel: "Nome acessível da seta do mês anterior. Por padrão, o \"Anterior\" traduzido do React Aria.", nextLabel: "Nome acessível da seta do próximo mês. Por padrão, o \"Próximo\" traduzido do React Aria.", footer: "Conteúdo abaixo da grade: a data escolhida, uma legenda ou um preço.", value: "A data escolhida (controlado).", defaultValue: "A data escolhida no início (não controlado).", onChange: "Chamada quando a pessoa escolhe um dia.", minValue: "A primeira data que pode ser escolhida.", maxValue: "A última data que pode ser escolhida.", isDateUnavailable: "Devolve `true` para os dias que não podem ser escolhidos, como fins de semana ou dias lotados.", firstDayOfWeek: "O dia que começa a semana. Por padrão, o do idioma.", focusedValue: "O dia focado (controlado). Define também o mês visível.", defaultFocusedValue: "O dia focado quando o calendário aparece (não controlado). Define o mês inicial.", onFocusChange: "Chamada quando o dia focado muda, inclusive ao trocar de mês.", autoFocus: "Foca o calendário ao montar." }}
>
	As datas são objetos `CalendarDate` do `@internationalized/date`, reexportados pelo Camaleo junto com `parseDate`, `today` e `isWeekend`. As outras props de calendário do React Aria passam direto, como `pageBehavior` e `createCalendar`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio calendário.

<StylingHooks
	slots={["calendar", "calendar-header", "calendar-title", "calendar-nav", "calendar-nav-button", "calendar-grid", "calendar-header-cell", "calendar-cell", "calendar-footer"]}
	prefix="calendar"
	attributes={[
		{ attr: "data-slot", value: '"calendar" · "calendar-header" · "calendar-grid" · "calendar-cell" · "calendar-footer"' },
		{ attr: "data-selected", value: "presente no dia escolhido" },
		{ attr: "data-today", value: "presente na data de hoje" },
		{ attr: "data-unavailable", value: "presente nos dias que o isDateUnavailable recusa" },
		{ attr: "data-disabled", value: "presente nos dias fora do mínimo/máximo, e na raiz quando desativado" },
		{ attr: "data-outside-month · data-focus-visible", value: "presente nos dias do mês seguinte ou anterior · no foco por teclado" },
	]}
>

```css
/* dias redondos, só no fluxo de reserva */
.booking [data-slot="calendar"] {
  --cml-calendar-cell-radius: 999px;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Setas", description: "Movem o foco um dia, ou uma semana para cima e para baixo." },
		{ key: "Home / End", description: "Levam o foco ao primeiro ou ao último dia do mês." },
		{ key: "Page Up / Page Down", description: "Vão para o mês anterior ou o próximo. Com Shift, um ano." },
		{ key: "Enter / Espaço", description: "Escolhe o dia focado." },
		{ key: "Tab", description: "Alterna entre as setas e a grade." },
	]}
	notes={[
		"A grade é um role=\"grid\" nomeado pelo aria-label mais o mês visível, então a pessoa ouve \"Data da consulta, outubro de 2026\".",
		"Cada dia é anunciado com a data completa e o estado: escolhido, hoje ou indisponível.",
		"Dias indisponíveis ficam riscados e continuam focáveis, então quem usa teclado chega até eles e entende por que não pode escolher.",
		"Ao trocar de mês, o novo mês é anunciado ao leitor de tela.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Range calendar", description: "Escolha uma data de início e uma de fim.", href: "/pt-br/docs/components/range-calendar" },
		{ title: "Date picker", description: "Um campo de data com este calendário num popover.", href: "/pt-br/docs/components/date-picker" },
		{ title: "Date field", description: "Digite a data, segmento por segmento.", href: "/pt-br/docs/components/date-field" },
	]}
/>


# Card (/pt-br/docs/components/card)

<ComponentMeta file="display" pattern="Static container" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter" />

## Anatomia [#anatomia]

Um cabeçalho com o título e uma descrição curta, o conteúdo e um rodapé para as ações. Use só as partes de que você precisa. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy tree={{ slot: "card", tag: "div", children: [{ slot: "card-header", tag: "div", children: [{ slot: "card-title", tag: "h3" }, { slot: "card-description", tag: "p" }] }, { slot: "card-content", tag: "div" }, { slot: "card-footer", tag: "div", note: "ações" }] }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="card/basic" compact />

<ExampleGrid>
	<Example name="card/with-footer" title="Com ações">
		Coloque os botões no `CardFooter`, com o principal por último. Assim a pessoa encontra as ações no mesmo lugar em todos os cards.
	</Example>
	<Example name="card/stretched-link" title="O card inteiro como link">
		Clique em qualquer parte do card. O link fica no título, então o leitor de tela fala um nome curto, e o `data-card-link` nele estica o link sobre o card. Não transforme o card num botão.
	</Example>
	<Example name="card/interactive-selection" title="Cards para escolher" wide>
		Clique num card ou use as setas. Cada card é o rótulo de um rádio, então clicar em qualquer parte escolhe a opção, e a legenda dá nome ao grupo.
	</Example>
	<Example name="card/media-card" title="Com imagem">
		Uma imagem no topo ajuda a reconhecer um guia ou um produto. Se ela só enfeita, esconda com `aria-hidden`.
	</Example>
	<Example name="card/variants" title="Compacto">
		Menos espaço interno para números de painel. Mantenha o título: é ele que diz a todo mundo o que o número significa.
	</Example>
	<Example name="card/empty" title="Ainda sem nada">
		Um card vazio continua com o título, explica por que está vazio e oferece o próximo passo, em vez de sumir da tela.
	</Example>
	<Example name="card/grid" title="Cards em grade" wide>
		Uma lista de cards é uma lista: use `ul` e `li`, para o leitor de tela dizer quantos são. A grade se ajusta sozinha no celular.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Cada card guarda um assunto. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="card/context-pricing" title="Plano de assinatura" uses="Card · Button" />
	<Context name="card/context-analytics" title="Número do painel" uses="Card · Badge · Link" />
	<Context name="card/context-account" title="Configuração de segurança" uses="Card · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="card/do-structured-parts" title="Use o cabeçalho e o conteúdo do card.">
		Eles cuidam do espaçamento e do estilo do título, e o card fica certo em todos os estilos.
	</Guideline>
	<Guideline kind="dont" name="card/dont-unstructured-divs" title="Divs soltas dentro do card.">
		O título deixa de ser um título de verdade, e o espaçamento quebra quando a pessoa troca de estilo.
	</Guideline>
	<Guideline kind="do" name="card/do-sections" title="Divida o card com uma linha.">
		Um separador divide o conteúdo e mantém uma caixa só em volta de um assunto.
	</Guideline>
	<Guideline kind="dont" name="card/dont-nested-cards" title="Um card dentro de outro.">
		Caixa dentro de caixa desperdiça espaço no celular e confunde o que pertence a quê.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="CardProps" describe={{}}>
	O `Card` e cada parte renderizam HTML simples e aceitam os atributos dele: `Card`, `CardHeader`, `CardContent` e `CardFooter` são `<div>`, `CardTitle` é `<h3>` e `CardDescription` é `<p>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou no próprio card.

<StylingHooks
	slots={["card", "card-header", "card-title", "card-description", "card-content", "card-footer"]}
	attributes={[{ attr: "data-card-link", value: "no link do título: estica o link sobre o card, que mostra o anel de foco" }]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "Passa pelos links, botões e campos dentro do card. O card em si nunca recebe foco." }]}
	notes={[
		"O CardTitle é um <h3>. Se a estrutura da página pedir outro nível, coloque outro título dentro dele ou use aria-level.",
		"Para um card clicável, coloque um link só no título e adicione data-card-link a ele. Envolver o card inteiro num link ou botão faz o leitor de tela ler tudo como um nome enorme.",
		"Outros links, botões e campos num card com data-card-link ficam acima do link esticado e continuam funcionando. Use poucos: o resto do card não pode ser selecionado como texto.",
		"Cards para escolher são rádios ou checkboxes com um rótulo que ocupa o card todo, dentro de um fieldset com legenda.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Link", href: "/pt-br/docs/components/link", description: "O link no título de um card clicável." },
		{ title: "Empty state", href: "/pt-br/docs/components/empty-state", description: "O que o card mostra quando ainda não tem nada." },
		{ title: "Stat", href: "/pt-br/docs/components/stat", description: "Um número com rótulo e tendência, para cards de painel." },
	]}
/>


# Carousel (/pt-br/docs/components/carousel)

<ComponentMeta file="carousel" pattern="WAI-ARIA Carousel" />

<Playground
	name="carousel/playground"
	component="Carousel"
	controls={[
		{ prop: "autoPlay", default: false },
		{ prop: "showAutoPlayToggle", default: true },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele roda no cliente, porque guarda o slide atual.

<Import names="Carousel, CarouselSlide" />

## Anatomia [#anatomia]

Uma `<section>` com os slides e, abaixo, uma fileira de controles. `CarouselSlide` é um layout opcional para cada slide; qualquer elemento serve. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "carousel",
		tag: "section",
		children: [
			{
				slot: "carousel-viewport",
				tag: "div",
				children: [
					{
						slot: "carousel-slide",
						tag: "div",
						note: "tabpanel, um por filho",
						children: [
							{
								slot: "carousel-slide-body",
								tag: "div",
								note: "CarouselSlide",
								row: true,
								children: [
									{
										slot: "carousel-slide-content",
										tag: "div",
										children: [
											{ slot: "carousel-slide-kicker", tag: "p" },
											{ slot: "carousel-slide-title", tag: "h3" },
											{ slot: "carousel-slide-description", tag: "p" },
										],
									},
									{ slot: "carousel-slide-aside", tag: "div", note: "badge" },
								],
							},
						],
					},
				],
			},
			{
				slot: "carousel-controls",
				tag: "div",
				row: true,
				children: [
					{
						slot: "carousel-actions",
						tag: "div",
						row: true,
						children: [
							{ slot: "carousel-button", tag: "button", note: "anterior" },
							{ slot: "carousel-button", tag: "button", note: "próximo" },
							{ slot: "carousel-autoplay", tag: "button", note: "reproduzir / pausar" },
						],
					},
					{ slot: "carousel-indicators", tag: "div", children: [{ slot: "carousel-indicator", tag: "button", note: "um por slide" }] },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="carousel/basic" compact />

<ExampleGrid>
	<Example name="carousel/indicators" title="Passos entre os quais a pessoa pula">
		Cada ponto é uma aba: o Tab chega à fileira uma vez, e as setas trocam de slide. Esconda o botão Reproduzir com `showAutoPlayToggle={false}` quando a pessoa lê no próprio ritmo.
	</Example>
	<Example name="carousel/play-button" title="Rotação que a pessoa inicia">
		Deixe `autoPlay` desligado e mantenha o botão Reproduzir: quem quer que os slides andem aperta nele, e Pausar para. A rotação nunca roda quando o sistema pede menos movimento.
	</Example>
	<Example name="carousel/with-kicker" title="Todas as partes de um slide">
		`CarouselSlide` organiza `kicker`, `title`, `description` e `badge`. Coloque a data ou a categoria no kicker, para o título caber no celular.
	</Example>
	<Example name="carousel/custom-slides" title="Conteúdo próprio no slide">
		Qualquer elemento pode ser um slide. Comece com um título, porque o nome do slide é só a posição, como "2 de 3".
	</Example>
	<Example name="carousel/interactive-tour" title="Reagir ao slide">
		Avance pelos passos e aperte Recomeçar. Controle `activeIndex` quando a página precisa saber o slide, como num contador de passos ou num botão de concluir.
	</Example>
	<Example name="carousel/slide-labels" title="Nomes no seu idioma">
		Sem tradução, o leitor de tela anuncia cada slide como "2 of 3, slide". Passe `slideLabel`, `slideRoleDescription` e os rótulos dos botões para ele dizer "Plano 2 de 3".
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Carrosséis costumam ficar num card ou numa seção da página, ao lado de conteúdo que está sempre visível. Estas são peças inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="carousel/context-onboarding" title="Tour de primeiros passos" uses="Card · Carousel · Button" wide />
	<Context name="carousel/context-testimonials" title="Avaliações de clientes" uses="Card · Carousel · Avatar" wide />
	<Context name="carousel/context-promotions" title="Ofertas da loja" uses="Card · Carousel · Badge · Button" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="carousel/do-few-slides" title="De três a cinco slides.">
		Pouca gente passa do terceiro slide, então um conjunto curto é visto e os pontos continuam fáceis de distinguir.
	</Guideline>
	<Guideline kind="dont" name="carousel/dont-many-slides" title="Um slide para cada recado.">
		Oito pontos parecem iguais, e os últimos slides só são vistos por quem clica em todos.
	</Guideline>
	<Guideline kind="do" name="carousel/do-slide-titles" title="Um título em cada slide.">
		Quem passa o olho, e quem usa leitor de tela e pula por títulos, sabe do que o slide trata antes de ler.
	</Guideline>
	<Guideline kind="dont" name="carousel/dont-no-titles" title="Slides que são só um parágrafo.">
		Sem título, a pessoa precisa ler o slide inteiro para saber se ele importa.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="carousel"
	type="CarouselProps"
	types={{ slideLabel: "(index, total) => string", goToSlideLabel: "(index) => string" }}
	describe={{
		activeIndex: "Índice do slide à mostra, a partir de 0 (controlado).",
		defaultIndex: "Índice do primeiro slide mostrado, a partir de 0 (não controlado).",
		onIndexChange: "Chamado com o novo índice quando o slide muda, por botão, ponto ou rotação.",
		autoPlay: "Começa a girar ao carregar. Nunca gira quando a pessoa prefere menos movimento, e só o botão Pausar para.",
		intervalMs: "Tempo de cada slide durante a rotação, em milissegundos.",
		showAutoPlayToggle: "Mostra o botão Reproduzir/Pausar, também com autoPlay desligado, para a pessoa iniciar a rotação.",
		previousLabel: "Nome do botão anterior, lido pelo leitor de tela.",
		nextLabel: "Nome do botão próximo, lido pelo leitor de tela.",
		playLabel: "Texto do botão de rotação quando parado.",
		pauseLabel: "Texto do botão de rotação quando girando.",
		indicatorsLabel: "Nome da fileira de pontos, lido pelo leitor de tela.",
		roleDescription: "Como o leitor de tela chama o componente (aria-roledescription). Traduza em páginas que não estão em inglês.",
		slideRoleDescription: "Como o leitor de tela chama cada slide, como \"plano\" ou \"foto\".",
		slideLabel: "Nome de cada slide a partir da posição (desde 1) e do total. Traduza em páginas que não estão em inglês.",
		goToSlideLabel: "Nome de cada ponto a partir da posição (desde 1).",
	}}
/>

<Props
	file="carousel"
	type="CarouselSlideProps"
	describe={{
		kicker: "Linha curta acima do título, como uma categoria ou uma data.",
		title: "Título do slide (um <h3>).",
		description: "Frase abaixo do título.",
		badge: "Elemento no fim do slide, como um Badge ou um Avatar.",
	}}
>
	Os dois aceitam os atributos do seu elemento: `Carousel` os de `<section>` (o `aria-label` padrão é "Carousel", então sempre passe um), `CarouselSlide` os de `<div>`, com os `children` depois da descrição.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio carrossel.

<StylingHooks
	slots={["carousel", "carousel-viewport", "carousel-slide", "carousel-slide-body", "carousel-slide-content", "carousel-slide-kicker", "carousel-slide-title", "carousel-slide-description", "carousel-slide-aside", "carousel-controls", "carousel-actions", "carousel-button", "carousel-autoplay", "carousel-indicators", "carousel-indicator"]}
	prefix="carousel"
	attributes={[
		{ attr: "data-active", value: "no slide à mostra e no ponto dele" },
		{ attr: "aria-selected", value: "true no ponto do slide à mostra" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa por anterior, próximo, Reproduzir/Pausar e pela fileira de pontos, que é uma parada só." },
		{ key: "Enter / Espaço", description: "Aperta anterior, próximo ou Reproduzir/Pausar." },
		{ key: "← / →", description: "Na fileira de pontos, mostra o slide anterior ou o próximo e leva o foco ao ponto dele. ↑ / ↓ também." },
		{ key: "Home / End", description: "Na fileira de pontos, mostra o primeiro ou o último slide." },
	]}
	notes={[
		"O carrossel é uma section com aria-roledescription. Ele segue o padrão de carrossel com abas: os pontos são abas, cada uma com aria-controls apontando para o seu slide, e cada slide é um role=\"tabpanel\" nomeado pela posição, como \"2 de 3\". Os slides ocultos saem da página com hidden.",
		"A rotação vem desligada e nunca roda com menos movimento. Ela espera enquanto o mouse ou o foco do teclado está no carrossel, e o botão Reproduzir/Pausar para de vez.",
		"O slide que a pessoa escolhe é anunciado (o viewport tem aria-live=\"polite\"); a rotação automática não. Comece cada slide com um título, para o anúncio ficar curto e claro.",
		"Os nomes padrão estão em inglês. Em outros idiomas, passe roleDescription, slideLabel, goToSlideLabel e os rótulos dos botões.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Card", description: "A superfície que costuma conter o carrossel numa seção da página.", href: "/pt-br/docs/components/card" },
		{ title: "Image", description: "Imagens responsivas com proporção fixa, para slides de fotos.", href: "/pt-br/docs/components/image" },
		{ title: "Accordion", description: "Seções que ficam todas na página, quando a pessoa precisa de todos os recados.", href: "/pt-br/docs/components/accordion" },
	]}
/>


# Checkbox (/pt-br/docs/components/checkbox)

<ComponentMeta file="checkbox" primitive="Base UI" pattern="WAI-ARIA Checkbox" />

<Playground
	name="checkbox/playground"
	component="Checkbox"
	controls={[
		{ prop: "defaultChecked", default: false },
		{ prop: "indeterminate", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Envolva cada checkbox num `Label` para o texto ser clicável e dar nome a ele.

<Import names="Checkbox, CheckboxGroup, Label" />

## Anatomia [#anatomia]

Um `Checkbox` é uma caixa com um indicador dentro. Um `CheckboxGroup` envolve vários checkboxes com rótulo e mantém os valores juntos.

<Anatomy
	keys={[
		{ label: '[data-slot="checkbox-group"]', color: "#8be36f" },
		{ label: '[data-slot="checkbox"] · [data-slot="checkbox-indicator"]', color: "#ffcf7a" },
		{ label: 'texto do [data-slot="label"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">checkbox</span>
	<span className="a-label">Novidades do produto</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="checkbox/basic" compact />

<ExampleGrid>
	<Example name="checkbox/group" title="Grupo com legenda">
		`Fieldset render={<CheckboxGroup />}` dá um nome às opções, então o leitor de tela anuncia "Quero receber e-mails sobre" antes de cada uma.
	</Example>
	<Example name="checkbox/select-all" title="Selecionar todos">
		Clique nos filhos. Com `allValues` no grupo e `parent` numa caixa, ela mostra o estado misto quando só algumas estão marcadas.
	</Example>
	<Example name="checkbox/with-description" title="Com descrição">
		Deixe o rótulo curto e explique a consequência embaixo, ligada com `aria-describedby` para ser lida depois do nome.
	</Example>
	<Example name="checkbox/required" title="Obrigatório, com erro">
		Envie sem marcar. Diga o que fazer na mensagem de erro, não só "Obrigatório"; o `Field` liga a mensagem ao checkbox.
	</Example>
	<Example name="checkbox/disabled" title="Desativado, com o motivo">
		Uma caixa desativada ainda mostra o que está incluído. Quando estiver desmarcada, diga por quê, para a pessoa saber como conseguir.
	</Example>
	<Example name="checkbox/table" title="Seleção de linhas" wide>
		Numa tabela, a linha é o rótulo; então dê a cada checkbox um `aria-label` que nomeie a linha.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Checkboxes vivem em formulários e listas. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="checkbox/context-signup" title="Cadastro com termos" uses="Card · Field · Input · Checkbox · Button" />
	<Context name="checkbox/context-filters" title="Painel de filtros" uses="Card · Fieldset · CheckboxGroup · Separator" />
	<Context name="checkbox/context-tasks" title="Checklist" uses="Card · CheckboxGroup · Checkbox" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="checkbox/do-many" title="Checkboxes para quantas opções a pessoa quiser.">
		Cada uma vale sozinha: dá para escolher nenhuma, uma ou todas.
	</Guideline>
	<Guideline kind="dont" name="checkbox/dont-exclusive" title="Checkboxes para opções que se excluem.">
		Mensal e anual ao mesmo tempo não faz sentido. Use um `RadioGroup`.
	</Guideline>
	<Guideline kind="do" name="checkbox/do-positive" title="Diga o que a marcação liga.">
		Caixa marcada deve significar sim: "Quero receber o resumo semanal".
	</Guideline>
	<Guideline kind="dont" name="checkbox/dont-negative" title="Rótulos negativos.">
		Uma marcação que quer dizer "não deixar de" obriga a pessoa a parar e reler.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="checkbox" type="CheckboxProps" include={["checked", "defaultChecked", "onCheckedChange", "indeterminate", "value", "parent", "name", "required", "disabled", "readOnly"]}
	types={{ onCheckedChange: "(checked: boolean, details) => void" }}
	describe={{ checked: "Se a caixa está marcada (controlado). Para não controlar, use `defaultChecked`.", defaultChecked: "Se a caixa começa marcada (não controlado).", onCheckedChange: "Chamada quando a caixa é marcada ou desmarcada.", indeterminate: "Estado misto: nem marcada, nem desmarcada. Anunciado como \"misto\".", value: "Identifica a caixa dentro de um `CheckboxGroup` e é o valor enviado no formulário.", parent: "Se a caixa controla os filhos de um `CheckboxGroup` (o \"selecionar todos\").", name: "Nome do campo no envio do formulário.", required: "Se a caixa precisa estar marcada para enviar o formulário.", disabled: "Ignora a interação e tira a caixa da ordem de tabulação.", readOnly: "Impede mudar o valor, mas mantém a caixa focável e legível." }}
>
	O `CheckboxGroup` recebe `value`, `defaultValue` e `onValueChange` (arrays com o `value` dos checkboxes), `allValues` para uma caixa pai, e `disabled`. Os atributos nativos passam direto.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio checkbox.

<StylingHooks
	slots={["checkbox", "checkbox-indicator", "checkbox-group"]}
	prefix="check"
	attributes={[
		{ attr: "data-slot", value: '"checkbox" · "checkbox-indicator" · "checkbox-group"' },
		{ attr: "data-checked", value: "presente quando marcada" },
		{ attr: "data-unchecked", value: "presente quando desmarcada" },
		{ attr: "data-indeterminate", value: "presente no estado misto" },
		{ attr: "data-disabled", value: "presente quando desativada" },
		{ attr: "data-invalid", value: "presente quando o Field está inválido" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Space", description: "Marca ou desmarca o checkbox com foco." },
		{ key: "Tab", description: "Vai para o próximo checkbox; cada um é uma parada de tabulação." },
	]}
	notes={[
		"A área de toque tem pelo menos 24 × 24 px (WCAG 2.5.8) em todos os estilos, mesmo quando a caixa visível é menor.",
		"Clicar no texto do rótulo marca a caixa, então envolva-a num Label ou ligue com htmlFor; o id fica na própria caixa, que um link do ErrorSummary também consegue focar.",
		"O estado misto é anunciado como \"misto\" pelo aria-checked, não só desenhado como um traço.",
		"Dentro de um Field, a descrição e o erro ficam ligados à caixa pelo aria-describedby.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Switch", description: "Liga e desliga ajustes que valem na hora.", href: "/pt-br/docs/components/switch" },
		{ title: "Radio group", description: "Uma escolha entre poucas.", href: "/pt-br/docs/components/radio-group" },
		{ title: "Field", description: "Rótulo, descrição e erro para qualquer controle.", href: "/pt-br/docs/components/field" },
	]}
/>


# Chip (/pt-br/docs/components/chip)

<ComponentMeta file="chip" primitive="Base UI" pattern="WAI-ARIA Button (toggle)" />

<Playground
	name="chip/playground"
	component="Chip"
	label="Só não lidas"
	controls={[
		{ prop: "defaultPressed", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O estilo carregado define o visual.

<Import names="Chip, ChipGroup" />

## Anatomia [#anatomia]

Um chip de filtro é um botão de alternância com um check que aparece quando pressionado. Um chip de entrada (com `onRemove`) é um span com um botão de remover no fim.

<Anatomy
	keys={[
		{ label: '[data-slot="chip"]', color: "#8be36f" },
		{ label: '[data-slot="chip-check"] · avatar · [data-slot="chip-remove"]', color: "#ffcf7a" },
		{ label: "rótulo (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">check</span>
	<span className="a-label">Em revisão</span>
	<span className="a-part">remover</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="chip/basic" compact />

<ExampleGrid>
	<Example name="chip/filter-count" title="Filtros com contagem">
		Pressione os chips. A contagem no rótulo mostra o que esperar, e uma linha com `role="status"` anuncia quantos resultados sobraram.
	</Example>
	<Example name="chip/single" title="Seleção única">
		O `multiple={false}` deixa um chip pressionado por vez, mas ainda dá para despressionar. Quando a escolha vazia não é permitida, use um radio group.
	</Example>
	<Example name="chip/removable" title="Removível">
		Remova uma etiqueta. O `onRemove` transforma o chip em chip de entrada, o `removeLabel` chama o botão de "Remover Urgente", e o foco fica na lista em vez de cair no corpo da página.
	</Example>
	<Example name="chip/avatar" title="Pessoas, com avatar">
		O `avatar` recebe um `Avatar` pequeno. As iniciais são decoração: o nome no chip e no `removeLabel` é o que a tecnologia assistiva lê.
	</Example>
	<Example name="chip/toggle" title="Sozinho">
		Um `Chip` sozinho é um botão de alternância com `aria-pressed`, bom para um filtro rápido como "Só não lidas" acima de uma lista.
	</Example>
	<Example name="chip/with-icon" title="Com ícone">
		Um ícone ajuda a percorrer um conjunto grande. Marque com `data-slot="icon"` e `aria-hidden`; o texto continua levando o significado.
	</Example>
	<Example name="chip/disabled" title="Desativado, com motivo">
		As setas pulam um chip desativado. Diga o motivo num texto ligado por `aria-describedby`, senão a pessoa acha que o filtro quebrou.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Chips ficam acima de resultados, em painéis de filtro e em diálogos de compartilhamento. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="chip/context-filters" title="Painel de filtros" uses="Card · ChipGroup · Chip · Button" />
	<Context name="chip/context-recipients" title="Compartilhar com pessoas" uses="Card · Field · Input · Chip · Avatar · Button" />
	<Context name="chip/context-applied" title="Filtros aplicados" uses="Chip · Button · Text" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="chip/do-short" title="De uma a três palavras.">
		Rótulos curtos mantêm a fileira fácil de percorrer e cabem no celular.
	</Guideline>
	<Guideline kind="dont" name="chip/dont-long" title="Frases dentro de chips.">
		Elas desmontam a fileira em linhas tortas e demoram mais para ler do que uma ou duas palavras.
	</Guideline>
	<Guideline kind="do" name="chip/do-filter" title="Chip filtra, botão age.">
		Pressionar um chip muda o que aparece; uma ação como "Exportar" continua sendo botão.
	</Guideline>
	<Guideline kind="dont" name="chip/dont-action" title="Chips como botões de ação.">
		Um chip anuncia "pressionado" ou "não pressionado", o que não faz sentido para "Excluir".
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="chip" type="ChipProps" include={["value", "pressed", "defaultPressed", "onPressedChange", "disabled", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement", onPressedChange: "(pressed, details) => void" }}
	describe={{
		avatar: "Aparece antes do texto, normalmente um `Avatar` pequeno.",
		onRemove: "Transforma o chip em chip de entrada (uma pessoa, um valor) com botão de remover, em vez de alternância. Sem ele, o chip é um filtro com check quando pressionado.",
		removeLabel: "Nome acessível do botão de remover (traduzível); o padrão é \"Remove {texto}\".",
		value: "Identifica o chip dentro de um `ChipGroup`.",
		pressed: "Se o chip está pressionado, quando você controla o estado.",
		defaultPressed: "Se o chip começa pressionado, quando ele guarda o próprio estado.",
		onPressedChange: "Chamada quando o chip é pressionado ou despressionado.",
		disabled: "Desativa o chip e o botão de remover.",
		render: "Troca o elemento renderizado, mantendo o comportamento.",
	}}
>
	O `ChipGroup` recebe `value`, `defaultValue` e `onValueChange` (arrays com os valores dos chips), `multiple` (`true` por padrão), `disabled` e `orientation`. Dê um nome a ele com `aria-label` ou `aria-labelledby`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio chip.

<StylingHooks
	slots={["chip", "chip-group", "chip-check", "chip-remove"]}
	prefix="chip"
	attributes={[
		{ attr: "data-slot", value: '"chip" · "chip-group" · "chip-check" · "chip-remove"' },
		{ attr: "data-variant", value: "filter · input" },
		{ attr: "data-pressed", value: "presente num chip de filtro pressionado" },
		{ attr: "data-disabled", value: "presente quando desativado" },
	]}
>

```css
/* chips quadrados, só nesta barra */
.report-filters [data-slot="chip"] {
  --cml-chip-radius: var(--cml-radius-control);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco para dentro do grupo, a um chip, e para fora. Num chip de entrada, chega ao botão de remover." },
		{ key: "Setas", description: "Movem entre os chips de um ChipGroup." },
		{ key: "Enter / Space", description: "Pressiona ou despressiona o chip focado, ou aciona o botão de remover." },
	]}
	notes={[
		"Um chip de filtro é um botão com aria-pressed, então o leitor de tela diz \"Abertos, botão de alternância, pressionado\".",
		"O ChipGroup tem role=\"group\" e precisa de um nome, como \"Status\", para os chips serem lidos como um conjunto.",
		"O check mostra o estado pressionado pela forma, não só pela cor.",
		"Ao remover um chip, leve o foco a um vizinho ou ao campo que adiciona chips, para quem usa teclado não cair no corpo da página.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Toggle", description: "Botão pressionado para barras de ferramentas, com ícones.", href: "/pt-br/docs/components/toggle" },
		{ title: "Tags input", description: "Digite para adicionar valores removíveis.", href: "/pt-br/docs/components/tags-input" },
		{ title: "Checkbox", description: "Várias opções num formulário, com rótulos.", href: "/pt-br/docs/components/checkbox" },
	]}
/>


# CodeBlock (/pt-br/docs/components/code-block)

<ComponentMeta file="code-block" primitive="HTML pre e code" pattern="Exemplo de código com botão de copiar" />

<Playground
	name="code-block/playground"
	component="CodeBlock"
	controls={[
		{ prop: "showLineNumbers", default: true },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele é um componente de cliente, por causa do botão de copiar.

<Import names="CodeBlock" />

## Anatomia [#anatomia]

Um cabeçalho com o nome do arquivo, a linguagem e o botão de copiar, e depois um `<pre>` que rola para o lado quando as linhas são longas. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "code-block",
		tag: "div",
		children: [
			{
				slot: "code-block-header",
				tag: "div",
				row: true,
				children: [
					{
						slot: "code-block-title",
						tag: "span",
						row: true,
						children: [
							{ slot: "code-block-filename", tag: "span", note: "opcional" },
							{ slot: "code-block-language", tag: "span", note: "opcional" },
						],
					},
					{ slot: "code-block-copy", tag: "button" },
				],
			},
			{
				slot: "code-block-pre",
				tag: "pre",
				note: "rola quando largo",
				children: [
					{
						slot: "code-block-code",
						tag: "code",
						children: [
							{
								slot: "code-block-line",
								tag: "span",
								row: true,
								children: [
									{ slot: "code-block-line-number", tag: "span" },
									{ slot: "code-block-line-content", tag: "span", children: [{ slot: "code-token", tag: "span" }] },
								],
							},
						],
					},
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a marca da barra acima.

<Preview name="code-block/basic" compact />

<ExampleGrid>
	<Example name="code-block/with-filename" title="Nome do arquivo e linguagem">
		Quando a pessoa precisa colar o código num arquivo específico, coloque o caminho em `filename`. O selo de `language` mostra a sintaxe de relance.
	</Example>
	<Example name="code-block/no-line-numbers" title="Comando de terminal">
		Desligue os números de linha num comando de uma linha só: não há o que apontar, e o comando se lê como uma peça única.
	</Example>
	<Example name="code-block/languages" title="JSON e outros formatos">
		O realce embutido colore strings, comentários e palavras-chave de JavaScript. Isso basta para JSON ou um comando de shell. O `language` também define os comentários: `#` para Bash, Python ou YAML, `//` para o resto.
	</Example>
	<Example name="code-block/custom-highlight" title="Linhas marcadas">
		Passe `highlight` para renderizar cada linha você mesmo, como as linhas de um diff. Mantenha o + e o - no texto, para a mudança não depender da cor.
	</Example>
	<Example name="code-block/long-lines" title="Linhas longas rolam">
		Linhas longas rolam para o lado em vez de quebrar, então o comando continua copiável como está. Quem usa teclado chega ao código com Tab e rola com as setas.
	</Example>
	<Example name="code-block/interactive-tabs" title="Um comando por gerenciador de pacotes">
		Escolha uma aba. As abas mostram um comando por vez e deixam a escolha clara, em vez de quatro blocos empilhados.
	</Example>
	<Example name="code-block/copy-status" title="Nomeie a cópia e anuncie">
		Diga em `copyLabel` o que o botão copia, como "Copiar comando de instalação". Depois da cópia, o `copiedLabel` aparece no botão e o leitor de tela também o anuncia.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Blocos de código costumam ficar num card ou num guia, logo depois da frase que os explica. Estas são peças inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="code-block/context-install" title="Passo de instalação" uses="Card · CodeBlock · Button" />
	<Context name="code-block/context-api" title="Endpoint de API" uses="Card · Badge · CodeBlock" />
	<Context name="code-block/context-config" title="Guia de configuração" uses="Card · CodeBlock" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="code-block/do-semantic-filename" title="Diga onde o código vai.">
		Um caminho como `app/blog/page.tsx` diz qual arquivo abrir antes de colar.
	</Guideline>
	<Guideline kind="dont" name="code-block/dont-unlabeled-block" title="Um trecho sem arquivo.">
		A pessoa precisa adivinhar se a linha vai numa página, num layout ou num arquivo de configuração.
	</Guideline>
	<Guideline kind="do" name="code-block/do-short-excerpt" title="Mostre só as linhas que importam.">
		Corte o resto com um comentário `// …`. A pessoa vê a mudança na hora e copia menos coisa por engano.
	</Guideline>
	<Guideline kind="dont" name="code-block/dont-huge-scroll" title="O arquivo inteiro para mudar uma linha.">
		A pessoa precisa caçar a linha certa, e o botão de copiar copia tudo.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="code-block"
	type="CodeBlockProps"
	include={["code", "language", "filename", "showLineNumbers", "copyLabel", "copiedLabel", "highlight"]}
	types={{ highlight: "(line, lineNumber) => ReactNode" }}
	describe={{
		code: "O código exibido. O botão de copiar copia exatamente esta string.",
		language: "Nome curto da linguagem, mostrado como selo no cabeçalho, como \"TSX\" ou \"Bash\". Também define os comentários do realce embutido: `#` para shell, Python, YAML e parecidas, `//` para as outras.",
		filename: "Caminho do arquivo mostrado no cabeçalho, como \"app/layout.tsx\".",
		showLineNumbers: "Mostra um número antes de cada linha. O leitor de tela pula os números, e eles ficam de fora ao selecionar o texto.",
		copyLabel: "Texto do botão de copiar, que também é o nome acessível dele. Diga o que ele copia quando houver vários blocos.",
		copiedLabel: "Texto que o botão mostra por 1,8 segundo depois do clique.",
		highlight: "Renderiza cada linha do seu jeito; recebe a linha e o número dela (a partir de 1). Substitui o realce embutido, que colore strings, comentários, palavras-chave de JavaScript e chamadas de função.",
	}}
>
	Os atributos nativos de `<div>` vão para a raiz. Não há prop para o `<pre>` nem um callback para a cópia.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio bloco.

<StylingHooks
	slots={[
		"code-block",
		"code-block-header",
		"code-block-title",
		"code-block-filename",
		"code-block-language",
		"code-block-copy",
		"code-block-pre",
		"code-block-code",
		"code-block-line",
		"code-block-line-number",
		"code-block-line-content",
		"code-token",
	]}
	prefix="code"
	attributes={[
		{ attr: "data-copied", value: "no botão de copiar, por 1,8 s depois do clique" },
		{ attr: "data-token", value: "comment · string · keyword · function, do realce embutido" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Vai para o botão de copiar e depois para o código, mas só quando o código é mais largo que o bloco. Código que cabe não ganha parada de Tab." },
		{ key: "Enter / Espaço", description: "Copia o código quando o botão de copiar está em foco." },
		{ key: "← / →", description: "Rolam as linhas longas para o lado quando o código está em foco." },
	]}
	notes={[
		"O texto do botão de copiar é o nome dele. Com vários blocos na página, faça copyLabel dizer o que ele copia.",
		"Depois de copiar, o botão mostra copiedLabel por 1,8 segundo, e uma mensagem de status anuncia a cópia. Se a área de transferência estiver bloqueada, nada muda e o código continua selecionável.",
		"Os números de linha têm aria-hidden, então o leitor de tela lê o código sem eles.",
		"Código mais largo que o bloco vira uma área de rolagem (role=\"region\") com o nome do arquivo, da linguagem ou \"Código\" (do MessagesProvider), para quem usa teclado poder rolar.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Kbd", href: "/pt-br/docs/components/kbd", description: "Uma tecla ou atalho dentro de uma frase, como Ctrl + C." },
		{ title: "Typography", href: "/pt-br/docs/components/typography", description: "Títulos e textos ao redor do código, incluindo código em linha." },
		{ title: "Card", href: "/pt-br/docs/components/card", description: "A superfície que guarda um exemplo de código e a explicação dele." },
	]}
/>


# Combobox (/pt-br/docs/components/combobox)

<ComponentMeta file="combobox" primitive="Base UI" pattern="WAI-ARIA Combobox" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe as partes que precisar, mais o `ComboboxEmpty` para a mensagem sem resultados. O estilo carregado cuida do campo e do popup.

<Import names="Combobox, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem" />

## Anatomia [#anatomia]

O `Combobox` guarda os itens e o valor; o `ComboboxInput` é o campo de texto com os botões de limpar e abrir; o conteúdo é um popup renderizado num portal. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="combobox-input-group"]', color: "#8be36f" },
		{ label: '[data-slot="combobox-clear"] · [data-slot="combobox-trigger"]', color: "#ffcf7a" },
		{ label: '[data-slot="combobox-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">Curitiba</span>
	<span className="a-part">✕</span>
	<span className="a-part">⌄</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="combobox/basic" compact />

<ExampleGrid>
	<Example name="combobox/empty" title="Sem resultados">
		Digite um nome que não existe. O `ComboboxEmpty` só aparece quando nada combina, então use para dizer o que fazer, não só "Nenhum resultado".
	</Example>
	<Example name="combobox/objects" title="Objetos como itens">
		Guarde o código, mostre o nome: `itemToStringLabel` preenche o campo, `itemToStringValue` vai para o formulário, `isItemEqualToValue` compara os dois.
	</Example>
	<Example name="combobox/controlled" title="Controlado">
		Escolha alguém. Com `value` e `onValueChange` o resto da tela acompanha a escolha na hora.
	</Example>
	<Example name="combobox/filter" title="Filtro próprio">
		Digite "gru" ou "galeao". Uma função `filter` pode buscar por código, apelido ou texto sem acento, do jeito que as pessoas digitam.
	</Example>
	<Example name="combobox/auto-highlight" title="Enter escolhe o primeiro">
		O `autoHighlight` destaca o primeiro resultado enquanto você digita, então uma busca curta e Enter bastam para etiquetas.
	</Example>
	<Example name="combobox/labels" title="Botões com nome">
		Os botões de limpar e abrir são ícones. Traduza os nomes com `clearLabel` e `triggerLabel`, e deixe-os específicos do campo.
	</Example>
	<Example name="combobox/validation" title="Obrigatório, com erro" wide>
		Dentro de um `Field`, o rótulo dá nome ao campo e o `FieldError` é lido junto; peça para escolher da lista, já que texto livre não vale.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O combobox costuma ser um campo entre vários. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="combobox/context-assign" title="Atribuir uma issue" uses="Card · Field · Combobox · Select · Button" />
	<Context name="combobox/context-delivery" title="Prazo de entrega" uses="Fieldset · Field · Combobox · Input · Button" />
	<Context name="combobox/context-timezone" title="Configuração de fuso" uses="Card · Switch · Field · Combobox" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="combobox/do-long-list" title="Listas longas que a pessoa sabe nomear.">
		Ninguém quer rolar 27 capitais; digitar "flo" é mais rápido.
	</Guideline>
	<Guideline kind="dont" name="combobox/dont-short-list" title="Busca para três opções.">
		Digitar é trabalho extra quando tudo cabe na tela; use um Select ou radios.
	</Guideline>
	<Guideline kind="do" name="combobox/do-hint" title="Diga o que digitar.">
		Um rótulo, um exemplo no placeholder e uma dica do que está coberto.
	</Guideline>
	<Guideline kind="dont" name="combobox/dont-generic" title="Só “Buscar…”.">
		Buscar o quê? Sem rótulo visível, a pessoa adivinha o escopo e o formato.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="combobox" type="ComboboxInputProps" include={["disabled", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ clearLabel: "Nome acessível do botão de limpar (traduzível).", triggerLabel: "Nome acessível do botão que abre a lista (traduzível).", disabled: "Desativa o campo e os botões.", render: "Troca o elemento renderizado do campo, mantendo o comportamento." }}
>
	Estas são as props do `ComboboxInput`; outros atributos de input, como `placeholder`, passam direto. O `Combobox` recebe as props da raiz do Base UI: `items`, `value`, `defaultValue`, `onValueChange`, `inputValue` / `onInputValueChange`, `filter`, `itemToStringLabel`, `itemToStringValue`, `isItemEqualToValue`, `autoHighlight`, `limit`, `multiple`, `disabled`, `required` e `name`. O `ComboboxList` recebe uma função de cada item; o `ComboboxItem` recebe `value` e `disabled`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio combobox.

<StylingHooks
	slots={["combobox-input-group", "combobox-input", "combobox-clear", "combobox-trigger", "combobox-popup", "combobox-item", "combobox-empty"]}
	prefix="combobox"
	attributes={[
		{ attr: "data-slot", value: '"combobox-input-group" · "combobox-input" · "combobox-clear" · "combobox-trigger" · "combobox-positioner" · "combobox-popup" · "combobox-list" · "combobox-item" · "combobox-empty"' },
		{ attr: "data-popup-open", value: "no campo e no botão enquanto a lista está aberta" },
		{ attr: "data-highlighted", value: "no item sob o teclado ou o mouse" },
		{ attr: "data-selected", value: "no item escolhido" },
		{ attr: "data-disabled", value: "no campo ou item desativado" },
		{ attr: "data-invalid", value: "no campo dentro de um Field inválido" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Digitar", description: "Filtra a lista e a abre." },
		{ key: "↓ / ↑", description: "Abre a lista e move o destaque; o foco continua no campo." },
		{ key: "Enter", description: "Escolhe o item destacado e fecha a lista." },
		{ key: "Esc", description: "Fecha a lista e mantém o que você digitou." },
		{ key: "Tab", description: "Sai do campo e fecha a lista." },
	]}
	notes={[
		"O campo tem role=\"combobox\" com aria-expanded e aria-activedescendant, então o leitor de tela acompanha o destaque enquanto você digita.",
		"Dentro de um Field, o FieldLabel dá nome ao campo; fora dele, passe um aria-label.",
		"Os botões de limpar e abrir precisam de nome: defina clearLabel e triggerLabel no idioma da página.",
		"O popup vai para um portal mas mantém o estilo pelo PortalScope, e o contraste passa no WCAG 2.2 AA nos 13 estilos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Select", description: "Escolha numa lista curta sem digitar.", href: "/pt-br/docs/components/select" },
		{ title: "CommandPalette", description: "Busca ações, não valores.", href: "/pt-br/docs/components/command-palette" },
		{ title: "TagsInput", description: "Digite vários valores livres.", href: "/pt-br/docs/components/tags-input" },
	]}
/>


# CommandPalette (/pt-br/docs/components/command-palette)

<ComponentMeta file="command-palette" primitive="Base UI" pattern="WAI-ARIA Dialog (Modal) + Combobox" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="CommandPalette, CommandPaletteTrigger, CommandPaletteContent, CommandPaletteInput, CommandPaletteList, CommandPaletteGroup, CommandPaletteItem, CommandPaletteEmpty, CommandPaletteFooter" />

## Anatomia [#anatomia]

O `CommandPaletteContent` renderiza o fundo e o dialog num portal. O foco fica na busca; as setas movem um destaque pela lista com `aria-activedescendant`.

<Anatomy
	tree={{
		slot: "command-palette-dialog",
		tag: "div",
		note: "role=dialog, num portal depois de command-palette-backdrop",
		children: [
			{
				slot: "command-palette-header",
				tag: "div",
				row: true,
				children: [
					{ slot: "command-palette-search-icon", tag: "span" },
					{ slot: "command-palette-input", tag: "input", note: "role=combobox" },
				],
			},
			{
				slot: "command-palette-list",
				tag: "div",
				note: "role=listbox, rola",
				children: [
					{
						slot: "command-palette-group",
						tag: "div",
						note: "role=group, opcional",
						children: [
							{ slot: "command-palette-group-label", tag: "span" },
							{
								slot: "command-palette-item",
								tag: "div",
								note: "role=option",
								row: true,
								children: [
									{ slot: "command-palette-item-icon", tag: "span" },
									{ slot: "command-palette-item-text", tag: "span" },
									{ slot: "command-palette-item-shortcut", tag: "span" },
								],
							},
						],
					},
				],
			},
			{ slot: "command-palette-empty", tag: "div", note: "quando nada corresponde" },
			{ slot: "command-palette-footer", tag: "div", note: "opcional" },
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo real que você pode copiar, no estilo, modo e marca da barra acima. Todos começam fechados: abra, digite, use as setas e o Enter, depois o Esc. A paleta não filtra sozinha. Guarde a busca no estado, renderize só os comandos que correspondem e dê ao `CommandPaletteList` um `key={query}`, para as setas seguirem a nova ordem.

<Preview name="command-palette/basic" compact />

<ExampleGrid>
	<Example name="command-palette/shortcut" title="Ctrl+K e atalhos dos comandos">
		Aperte Ctrl+K em qualquer lugar desta página. O botão continua sendo a entrada visível, e cada comando mostra o próprio atalho para as pessoas aprenderem.
	</Example>
	<Example name="command-palette/groups" title="Grupos: Navegação, Ações, Recentes">
		Títulos ajudam a percorrer uma lista longa. Um grupo sem resultados some junto com o título, e o destaque rola até ficar à vista.
	</Example>
	<Example name="command-palette/synonyms" title="Palavras-chave e sinônimos">
		Digite "recibo" ou "adicionar usuário". As pessoas buscam com as próprias palavras, então procure também nas palavras-chave e mostre qual delas bateu.
	</Example>
	<Example name="command-palette/empty" title="Estado vazio">
		Repita o que foi buscado e sugira o que tentar. A busca continua na caixa, fácil de corrigir.
	</Example>
	<Example name="command-palette/async" title="Resultados do servidor">
		Digite um nome. Enquanto a requisição roda, a lista fica com `aria-busy` e o rodapé diz "Buscando…"; uma busca mais nova descarta a anterior.
	</Example>
	<Example name="command-palette/nested" title="Páginas dentro da paleta">
		"Mudar tema…" abre uma página de opções. O Esc ou o Backspace com a busca vazia voltam um nível antes de fechar.
	</Example>
	<Example name="command-palette/a11y-announce" title="Contagem e resultado anunciados">
		A contagem do rodapé é um status educado, lido quando a digitação pausa. Depois que um comando roda, um status fora da paleta diz o que aconteceu.
	</Example>
	<Example name="command-palette/disabled" title="Um comando que você não pode rodar">
		Deixe na lista com `aria-disabled` e diga por quê. As pessoas encontram, descobrem quem pode fazer, e o Enter não faz nada.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Estas são partes inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="command-palette/context-dashboard" title="Busca no topo de um dashboard" uses="CommandPalette · Button · Avatar · Stat · Card" />
	<Context name="command-palette/context-docs-search" title="Busca de um site de documentação" uses="CommandPalette · Button · Kbd · Card" />
	<Context name="command-palette/context-go-to-file" title="Editor: Ir para arquivo" uses="CommandPalette · Tabs · Button · Card" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="command-palette/do-visible-path" title="Um atalho para o que já está na página.">
		Emitir e exportar têm botões próprios. A paleta é o caminho mais rápido para quem já sabe o que quer.
	</Guideline>
	<Guideline kind="dont" name="command-palette/dont-palette-only" title="Ações que só existem na paleta.">
		Ninguém navega por uma caixa de busca. Se "Emitir nota fiscal" não está na página, a maioria nunca encontra.
	</Guideline>
	<Guideline kind="do" name="command-palette/do-verb-labels" title="Rótulos curtos que começam com um verbo.">
		"Enviar lembrete de pagamento" diz o que vai acontecer, e a primeira palavra é o que as pessoas digitam.
	</Guideline>
	<Guideline kind="dont" name="command-palette/dont-vague-labels" title="Substantivos e frases longas.">
		"Nota fiscal" pode abrir, emitir ou cancelar uma. Uma frase é cortada e difícil de encontrar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="command-palette"
	type="CommandPaletteProps"
	include={["open", "defaultOpen", "onOpenChange", "modal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ shortcut: "Escuta Ctrl+K (⌘K no Mac) na página toda para abrir e fechar a paleta. Desligue quando a página tiver mais de uma paleta.", open: "Se a paleta está aberta. Use com `onOpenChange` para controlar o estado.", defaultOpen: "Se ela começa aberta. Deixe desligado: a paleta abre quando as pessoas pedem.", onOpenChange: "Chamado quando ela abre ou fecha. `eventDetails.reason` diz o motivo, por exemplo `escape-key`.", modal: "`true` prende o foco e esconde a página de trás dos leitores de tela. Mantenha o padrão." }}
>
	`CommandPaletteContent`, `CommandPaletteList`, `CommandPaletteEmpty` e `CommandPaletteFooter` recebem as props da sua `div`; passe `aria-label` ao conteúdo e à lista. O `CommandPaletteInput` recebe as props de um `input`, incluindo `value`, `onChange` e `aria-label`. O `CommandPaletteTrigger` recebe `render`.
</Props>

Cada comando é um `CommandPaletteItem`:

<Props
	file="command-palette"
	type="CommandPaletteItemProps"
	include={[]}
	describe={{ value: "Vai para `data-value`, para o seu filtro ou para testes. A paleta não filtra por ele.", icon: "Ícone no início, escondido dos leitores de tela.", shortcut: "Mostrado no fim, por exemplo teclas com Kbd ou uma dica. Só exibe: ligue o atalho você mesmo." }}
>
	O `onSelect` executa o comando, no clique ou no Enter com o item destacado. Ele também recebe as props da sua `div`, como `aria-disabled`, `aria-keyshortcuts` e `onMouseDown`. O `CommandPaletteGroup` recebe `label`, o título visível do grupo.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria paleta.

<StylingHooks
	slots={["command-palette-backdrop", "command-palette-dialog", "command-palette-header", "command-palette-search-icon", "command-palette-input", "command-palette-list", "command-palette-group", "command-palette-group-label", "command-palette-item", "command-palette-item-icon", "command-palette-item-text", "command-palette-item-shortcut", "command-palette-empty", "command-palette-footer"]}
	prefix="cmd"
	attributes={[
		{ attr: "data-active · aria-selected=\"true\"", value: "no comando destacado" },
		{ attr: "aria-disabled=\"true\"", value: "um comando que não pode rodar; aparece apagado" },
		{ attr: "data-value", value: "a prop value do item" },
		{ attr: "data-open · data-closed", value: "no dialog e no fundo" },
	]}
>

```css
/* uma lista mais alta para o buscador de arquivos */
.editor [data-slot="command-palette-list"] {
  max-height: 24rem;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Ctrl + K / ⌘ + K", description: "Abre a paleta de qualquer lugar da página e fecha quando ela está aberta. Só com a prop shortcut ligada, e não enquanto se digita em outro campo de texto, onde editores usam Ctrl+K para links." },
		{ key: "Enter / Space", description: "No gatilho, abre a paleta com o foco na busca." },
		{ key: "↓ / ↑", description: "Move o destaque para o próximo comando ou o anterior, dando a volta nas pontas. O foco fica na busca." },
		{ key: "Enter", description: "Executa o comando destacado." },
		{ key: "Esc", description: "Fecha a paleta e devolve o foco ao elemento que o tinha. Não limpa a busca antes." },
		{ key: "Tab", description: "Fica na busca: ela é o único controle do dialog." },
	]}
	notes={[
		"O dialog é modal e precisa de um nome: passe aria-label ao CommandPaletteContent, e outro ao CommandPaletteInput, no idioma da página.",
		"A busca é um combobox com aria-expanded e aria-controls apontando para o listbox. O aria-activedescendant acompanha o destaque, então o leitor de tela lê cada comando conforme você se move.",
		"Os resultados mudam em silêncio. Coloque a contagem num role=\"status\" dentro da paleta e, depois que um comando roda, conte o resultado num status fora dela: a paleta sumiu e o foco voltou ao gatilho.",
		"O Ctrl+K escuta a página toda. Deixe shortcut ligado em uma paleta só e desligue nas outras, ou um toque abre todas.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Combobox", description: "Busque numa lista para escolher o valor de um campo.", href: "/pt-br/docs/components/combobox" },
		{ title: "Dialog", description: "A janela modal sobre a qual a paleta é feita.", href: "/pt-br/docs/components/dialog" },
		{ title: "Kbd", description: "Mostre as teclas de um atalho ao lado de um comando.", href: "/pt-br/docs/components/kbd" },
	]}
/>


# Container (/pt-br/docs/components/container)

<ComponentMeta file="layout" pattern="CSS max-inline-size + margin-inline: auto" />

<Playground
	name="container/playground"
	component="Container"
	controls={[{ prop: "size", options: ["sm", "md", "lg", "xl"], default: "sm" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. Ele não tem estado, então renderiza no servidor.

<Import names="Container" />

## Anatomia [#anatomia]

Um só elemento. O tamanho chega como a custom property `--cml-container-max`, então o seu CSS ainda pode mudá-lo.

<Anatomy
	tree={{
		slot: "container",
		tag: "div",
		note: "ou a tag de as · centralizado, com padding · seu conteúdo dentro",
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. A caixa com borda em cada um faz o papel da janela do navegador; aumente e diminua a sua janela para ver a coluna acompanhar.

<Preview name="container/basic" compact />

<ExampleGrid>
	<Example name="container/sizes" title="Quatro tamanhos" wide>
		Escolha um tamanho. O desenho é uma tela de 1440 px reduzida para caber, então as proporções são as reais: `sm` para leitura e formulários, `lg` (o padrão) para a maioria das páginas, `xl` para tabelas.
	</Example>
	<Example name="container/reading-width" title="Largura de leitura">
		Texto longo se lê melhor com 60 a 75 caracteres por linha. Use `--cml-container-max: 65ch` e a coluna acompanha a fonte, não a tela.
	</Example>
	<Example name="container/full-bleed" title="Seção de ponta a ponta" wide>
		Coloque o fundo numa `section` de fora e o Container dentro dela: a cor vai de borda a borda e o texto fica alinhado com o resto da página.
	</Example>
	<Example name="container/phone-padding" title="Margem no celular">
		Ligue a margem maior. Abaixo do limite, a coluna ocupa a tela toda mas mantém 1rem de cada lado; mude `--cml-container-padding` para dar mais respiro.
	</Example>
	<Example name="container/narrow-form" title="Formulário estreito">
		Um cadastro não precisa da largura da página. `size="sm"` deixa rótulos, campos e o botão ao alcance de um só olhar.
	</Example>
	<Example name="container/landmark" title="Como landmark">
		O Container é uma `div` comum. Passe `as="main"`, `as="article"` ou `as="section"` com um rótulo, para quem usa leitor de tela pular direto para a coluna.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Containers emolduram páginas inteiras. São pedaços que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="container/context-article" title="Artigo de blog" uses="Container · Heading · Text · Image · Badge" />
	<Context name="container/context-marketing" title="Seção de landing page" uses="Container · Grid · Badge · Button" />
	<Context name="container/context-settings" title="Página de configurações" uses="Container · Card · Field · Switch · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="container/do-full-bleed" title="Cor na seção, conteúdo no container.">
		A faixa chega às duas bordas em qualquer tela, e o texto dela se alinha com a página.
	</Guideline>
	<Guideline kind="dont" name="container/dont-boxed-band" title="Fundo no próprio container.">
		Em telas largas a cor para na coluna e parece um card fora do lugar.
	</Guideline>
	<Guideline kind="do" name="container/do-reading-width" title="Coluna estreita para texto longo.">
		Linhas curtas ajudam o olho a achar o começo da próxima.
	</Guideline>
	<Guideline kind="dont" name="container/dont-wide-text" title="Artigo numa coluna xl.">
		Linhas de 150 caracteres cansam, e a pessoa se perde no texto.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="ContainerProps"
	describe={{
		size: "Largura máxima: `sm` 40rem (formulários, artigos), `md` 48rem (configurações), `lg` 64rem (a maioria das páginas), `xl` 80rem (dashboards, tabelas largas). Abaixo dela, o container ocupa a largura toda.",
		as: "O elemento a renderizar, para a semântica certa (por exemplo `as=\"main\"`).",
	}}
>
	Todos os atributos do elemento renderizado passam adiante, como `id`, `aria-labelledby` ou `style`. Não aninhe containers: o padding soma no celular.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: defina as custom properties no container, num elemento pai ou num estilo.

<StylingHooks
	slots={["container"]}
	prefix="container"
	attributes={[
		{ attr: "data-slot", value: '"container"' },
		{ attr: "--cml-container-max", value: "40rem · 48rem · 64rem · 80rem, vindo de size" },
		{ attr: "--cml-container-padding", value: "padding lateral, 1rem por padrão" },
	]}
>

```css
/* margem lateral maior de tablet para cima */
@media (min-width: 48rem) {
  [data-slot="container"] {
    --cml-container-padding: 2rem;
  }
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O Container não é interativo e não recebe foco. O Tab vai direto para os links e campos dentro dele." }]}
	notes={[
		"Ele renderiza uma div sem role. Use as=\"main\" na coluna principal da página, para o leitor de tela poder pular até ela.",
		"A largura é limitada em rem, então cresce com o tamanho de fonte e o zoom de quem lê; com zoom de 400% a coluna apenas ocupa a tela, sem rolagem lateral.",
		"O padding afasta o texto da borda no celular, onde cantos arredondados e capinhas cortariam as letras.",
		"Mudar o tamanho nunca muda a ordem de leitura: o conteúdo segue a ordem do código em qualquer largura.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Typography", description: "Títulos e textos para o que vai dentro da coluna.", href: "/pt-br/docs/components/typography" },
		{ title: "Card", description: "Uma superfície para um grupo de conteúdo dentro da página.", href: "/pt-br/docs/components/card" },
		{ title: "AspectRatio", description: "Mídia que mantém a forma em qualquer largura de coluna.", href: "/pt-br/docs/components/aspect-ratio" },
	]}
/>


# Menu de contexto (/pt-br/docs/components/context-menu)

<ComponentMeta file="context-menu" primitive="Base UI" pattern="WAI-ARIA Menu" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe as partes que precisar. O popup vai para um portal, na posição do ponteiro, e mantém o estilo, o modo e a cor da marca da página em volta.

<Import names="ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuSeparator" />

## Anatomia [#anatomia]

O `ContextMenu` guarda o estado de aberto. O `ContextMenuTrigger` (`data-slot="context-menu-trigger"`) é a área que a pessoa clica com o botão direito; o `ContextMenuContent` renderiza o popup abaixo num portal. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "context-menu-positioner",
		tag: "div",
		note: "num portal, no ponteiro",
		children: [
			{
				slot: "context-menu-popup",
				tag: "div",
				note: "role=menu",
				children: [
					{ slot: "context-menu-group-label", tag: "div" },
					{
						slot: "context-menu-item",
						tag: "div",
						row: true,
						children: [
							{ slot: "context-menu-item-icon", tag: "span" },
							{ slot: "context-menu-item-label", tag: "span" },
							{ slot: "context-menu-item-shortcut", tag: "span" },
						],
					},
					{
						slot: "context-menu-checkbox-item",
						tag: "div",
						row: true,
						children: [
							{ slot: "context-menu-item-indicator", tag: "span" },
							{ slot: "context-menu-item-label", tag: "span" },
						],
					},
					{
						slot: "context-menu-radio-item",
						tag: "div",
						row: true,
						children: [
							{ slot: "context-menu-item-indicator", tag: "span", children: [{ slot: "context-menu-radio-dot", tag: "span" }] },
							{ slot: "context-menu-item-label", tag: "span" },
						],
					},
					{
						slot: "context-menu-sub-trigger",
						tag: "div",
						note: "abre o context-menu-sub-popup",
						row: true,
						children: [
							{ slot: "context-menu-item-label", tag: "span" },
							{ slot: "context-menu-sub-arrow", tag: "span" },
						],
					},
					{ slot: "context-menu-separator", tag: "div" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a marca da barra acima, e todos começam fechados: clique neles com o botão direito.

<Preview name="context-menu/basic" compact />

<ExampleGrid>
	<Example name="context-menu/file-row" title="Numa linha de arquivo">
		O uso clássico: as ações de um arquivo, onde o ponteiro já está. O `tabIndex={0}` deixa quem usa teclado focar a linha e abrir o menu com Shift+F10 ou a tecla Menu.
	</Example>
	<Example name="context-menu/canvas" title="Numa área de desenho" wide>
		Num quadro vazio não há onde pôr um botão, então o clique direito é onde a pessoa procura. Mantenha os mesmos comandos numa barra de ferramentas.
	</Example>
	<Example name="context-menu/groups" title="Grupos e separadores">
		Um `ContextMenuGroupLabel` em cada grupo ajuda a pessoa a percorrer um menu mais longo; o grupo destrutivo vem por último.
	</Example>
	<Example name="context-menu/with-shortcuts" title="Com atalhos">
		Quem clica com o botão direito está aprendendo. Mostre o atalho com `Kbd` e use `aria-keyshortcuts`, para que da próxima vez a pessoa pule o menu.
	</Example>
	<Example name="context-menu/interactive-status" title="Agir e avisar">
		Clique na nota com o botão direito e escolha uma ação. O foco volta à nota, e uma linha com `role="status"` diz o que aconteceu.
	</Example>
	<Example name="context-menu/visible-path" title="Também num menu visível">
		Um menu de contexto é escondido por natureza. Coloque as mesmas ações atrás de um botão "⋯", a partir de uma lista só, para quem usa toque, teclado ou leitor de tela encontrar.
	</Example>
	<Example name="context-menu/view-options" title="Itens de marcar e de opção">
		Clique no quadro com o botão direito e mude as configurações: o `ContextMenuCheckboxItem` e o `ContextMenuRadioItem` mantêm o menu aberto e informam `aria-checked`, então dá para mudar várias de uma vez.
	</Example>
	<Example name="context-menu/submenu" title="Submenu">
		Ponha uma lista de destinos atrás de um item "Mover para" em vez de esticar o menu; → abre o submenu, ← volta, e a pasta atual fica desativada.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O menu de contexto acelera um trabalho que já tem um caminho visível. Estas são telas inteiras que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="context-menu/context-file-manager" title="Gerenciador de arquivos" uses="ContextMenu · Menu · IconButton" />
	<Context name="context-menu/context-kanban-card" title="Cartão de kanban" uses="Card · Badge · ContextMenu" />
	<Context name="context-menu/context-chat-message" title="Mensagem de chat" uses="Avatar · ContextMenu · Menu" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="context-menu/do-visible-path" title="As mesmas ações atrás de um botão visível.">
		O clique direito é um atalho para quem já conhece; o botão "⋯" é a entrada para todo mundo.
	</Guideline>
	<Guideline kind="dont" name="context-menu/dont-hidden-only" title="Ações só no clique direito.">
		Nada na tela diz que elas existem, e no celular ou com leitor de tela ninguém as encontra.
	</Guideline>
	<Guideline kind="do" name="context-menu/do-contextual" title="Ações da coisa sob o ponteiro.">
		Clique direito num comentário: responder, editar, copiar. O menu responde "o que posso fazer com isto?".
	</Guideline>
	<Guideline kind="dont" name="context-menu/dont-global" title="Comandos do app inteiro.">
		Configurações e Sair não têm nada a ver com o comentário, e ficam no cabeçalho, onde a pessoa espera.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="context-menu" type="ContextMenuItemProps" include={["onClick", "closeOnClick", "disabled", "label", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ icon: "Ícone antes do rótulo. Fica escondido do leitor de tela.", shortcut: "Mostrado no fim, por exemplo \"Ctrl D\". Só exibe: as teclas você liga por conta própria.", tone: "`danger` pinta uma ação destrutiva. Coloque por último, depois de um separador.", onClick: "Roda quando o item é escolhido com clique, Enter ou Espaço.", closeOnClick: "Se escolher o item fecha o menu.", disabled: "Desativa o item. Ele continua focável, para a pessoa conseguir ler.", label: "Texto para a busca por letra quando o conteúdo do item não é texto simples.", render: "Renderiza outro elemento, como um `<a>` para um link." }}
>
	Estas são as props do `ContextMenuItem`. O `ContextMenu` recebe as props da raiz do Base UI: `open`, `onOpenChange`, `disabled` e `actionsRef`. O `ContextMenuCheckboxItem` recebe `checked`, `defaultChecked`, `onCheckedChange` e `shortcut`; o `ContextMenuRadioGroup` recebe `value`, `defaultValue` e `onValueChange`, e cada `ContextMenuRadioItem`, um `value`. Envolva o `ContextMenuSubTrigger` e o `ContextMenuSubContent` num `ContextMenuSub`. O `ContextMenuTrigger` renderiza uma `<div>`: passe `tabIndex={0}` para ela receber foco, ou `render` para usar outro elemento.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio popup.

<StylingHooks
	slots={["context-menu-trigger", "context-menu-popup", "context-menu-item", "context-menu-item-icon", "context-menu-item-label", "context-menu-item-shortcut", "context-menu-checkbox-item", "context-menu-radio-item", "context-menu-item-indicator", "context-menu-radio-dot", "context-menu-sub-trigger", "context-menu-sub-arrow", "context-menu-sub-popup", "context-menu-group-label", "context-menu-separator"]}
	prefix="context-menu"
	attributes={[
		{ attr: "data-popup-open", value: "no gatilho enquanto o menu está aberto" },
		{ attr: "data-highlighted", value: "no item sob o teclado ou o mouse" },
		{ attr: "data-checked · data-unchecked", value: "nos itens de marcar e de opção" },
		{ attr: "data-disabled", value: "num item desativado" },
		{ attr: "data-tone", value: "danger" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Shift+F10 / Menu", description: "No gatilho focado: abre o menu e leva o foco para ele." },
		{ key: "↓ / ↑", description: "Vai para o primeiro ou o último item e depois anda entre eles, voltando ao início no fim." },
		{ key: "Home / End", description: "Vai para o primeiro ou o último item." },
		{ key: "A–Z", description: "Vai para o próximo item que começa com a letra." },
		{ key: "Enter / Space", description: "Escolhe o item; num item de marcar ou de opção, alterna e mantém o menu aberto." },
		{ key: "→ / ←", description: "No gatilho de um submenu, → abre o submenu no primeiro item; dentro dele, ← fecha e volta." },
		{ key: "Esc", description: "Fecha o submenu, ou o menu, e devolve o foco ao gatilho." },
		{ key: "Tab", description: "Fecha o menu inteiro, com os submenus, e devolve o foco para onde estava." },
	]}
	notes={[
		"Nada na tela avisa que existe um menu de contexto. Toda ação dele precisa estar também num botão ou menu visível.",
		"Os itens são menuitem; os de marcar são menuitemcheckbox e os de opção, menuitemradio, os dois com aria-checked. O gatilho do submenu informa aria-haspopup e aria-expanded.",
		"O gatilho é uma <div>: passe tabIndex={0} para quem usa teclado conseguir focar e abrir o menu com Shift+F10 ou a tecla Menu. Linhas que já têm um botão \"⋯\" podem dispensar isso e economizar uma parada de Tab.",
		"Em telas de toque, um toque longo abre o menu; quem usa leitor de tela raramente o encontra, mais um motivo para o caminho visível.",
		"O popup vai para um portal mas mantém o estilo pelo PortalScope, e o contraste passa no WCAG 2.2 AA nos 13 estilos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Menu", description: "A mesma lista de ações, aberta por um botão visível.", href: "/pt-br/docs/components/menu" },
		{ title: "Kbd", description: "Mostra o atalho ao lado de cada ação.", href: "/pt-br/docs/components/kbd" },
		{ title: "Button", description: "Para as uma ou duas ações mais usadas.", href: "/pt-br/docs/components/button" },
	]}
/>


# DataList (/pt-br/docs/components/data-list)

<ComponentMeta file="data-display" primitive="HTML dl" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="DataList, DataListTerm, DataListDetail, DataListItem" />

## Anatomia [#anatomia]

Uma lista de descrição nativa: uma grade de duas colunas em que cada termo (`<dt>`) fica ao lado do seu valor (`<dd>`). O `DataListItem` renderiza um par sem acrescentar nenhum elemento em volta.

<Anatomy
	tree={{
		slot: "data-list",
		tag: "dl",
		note: "grade de duas colunas",
		row: true,
		children: [
			{ slot: "data-list-term", tag: "dt" },
			{ slot: "data-list-detail", tag: "dd" },
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo de verdade que você pode copiar. Todos usam o estilo, o modo e a marca escolhidos na barra acima.

<Preview name="data-list/basic" compact />

<ExampleGrid>
	<Example name="data-list/with-badge" title="Status num badge">
		Use um badge no valor quando ele for um estado que a pessoa procura de olho, como Pago. Para o resto, texto simples é mais fácil de ler.
	</Example>
	<Example name="data-list/missing-value" title="Valores ausentes">
		Mantenha a linha e diga o que falta, como "Não informado", numa cor mais discreta. Um traço ou uma célula vazia passa despercebido, e alguns leitores de tela pulam.
	</Example>
	<Example name="data-list/links-and-actions" title="Links de e-mail e telefone">
		Transforme o valor em link quando ele abre algo, como `mailto:` ou `tel:`. O texto do link é o próprio valor, então ele continua claro fora de contexto.
	</Example>
	<Example name="data-list/multiline-detail" title="Valores longos">
		Endereços e observações quebram em várias linhas. Alinhe o termo no topo, para ele ficar ao lado da primeira linha em vez de flutuar no meio.
	</Example>
	<Example name="data-list/term-shorthand" title="Pares a partir de dados">
		Quando os pares vêm de um array, transforme cada um num `DataListItem` com `term`. Ele renderiza o `<dt>` e o `<dd>` para você, sem elemento extra dentro do `<dl>`.
	</Example>
	<Example name="data-list/interactive-copy" title="Copiar um valor">
		Clique no botão para copiar a chave. O nome dele diz o que copia, e uma mensagem de status anuncia o resultado, porque só um ícone novo não diz nada ao leitor de tela.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Uma lista de dados costuma ficar abaixo de um título que dá nome ao registro, com as ações do registro ao lado. Estes são pedaços inteiros de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="data-list/context-order-details" title="Resumo do pedido" uses="DataList · Badge · Button" />
	<Context name="data-list/context-profile" title="Perfil de um membro da equipe" uses="DataList · Avatar · Badge · Link" />
	<Context name="data-list/context-specs" title="Detalhes do servidor" uses="DataList · Badge · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="data-list/do-name-missing" title="Diga quando um valor falta.">
		"Não informado" mostra que o campo existe e está vazio, e não que a página falhou ao carregar.
	</Guideline>
	<Guideline kind="dont" name="data-list/dont-blank-values" title="Um valor vazio.">
		Uma célula em branco parece erro, e a pessoa não sabe se o dado falta ou se ainda está carregando.
	</Guideline>
	<Guideline kind="do" name="data-list/do-short-terms" title="Use termos de uma ou duas palavras.">
		A pessoa passa o olho pelos termos para achar uma linha. Termos curtos deixam espaço para os valores, até no celular.
	</Guideline>
	<Guideline kind="dont" name="data-list/dont-long-terms" title="Uma frase como termo.">
		A coluna dos termos cresce, os valores ficam espremidos, e o título acima já dá o contexto.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="DataListItemProps"
	describe={{
		term: "O rótulo, renderizado num `DataListTerm` (`<dt>`).",
		children: "O valor, renderizado num `DataListDetail` (`<dd>`). Sem `term`, os filhos aparecem como estão, sem nada em volta.",
		termProps: "Props repassadas ao `DataListTerm`.",
		detailProps: "Props repassadas ao `DataListDetail`.",
	}}
>
	`DataList`, `DataListTerm` e `DataListDetail` aceitam os atributos de `<dl>`, `<dt>` e `<dd>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou na própria lista.

<StylingHooks slots={["data-list", "data-list-term", "data-list-detail"]} prefix="data-list" />

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "Passa pelos links e botões dentro dos valores. A lista em si não recebe foco." }]}
	notes={[
		"O DataList renderiza um <dl> nativo, então o leitor de tela anuncia uma lista e lê cada termo com o seu valor.",
		"Coloque DataListTerm e DataListDetail direto dentro do DataList, em pares. O DataListItem não acrescenta nada em volta, então também pode.",
		"Dê nome ao registro com um título acima da lista, para a pessoa poder pular até ele e saber de quem são os detalhes.",
		"Botões dentro de um valor precisam de um nome que diga sobre o que agem, como \"Copiar chave publicável\", e de uma mensagem de status para o resultado.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Table", description: "Linhas e colunas, para comparar vários registros.", href: "/pt-br/docs/components/table" },
		{ title: "Stat", description: "Um número com rótulo, para um painel.", href: "/pt-br/docs/components/stat" },
		{ title: "Badge", description: "Um status curto dentro de um valor.", href: "/pt-br/docs/components/badge" },
	]}
/>


# DataTable (/pt-br/docs/components/data-table)

<ComponentMeta file="data-table" primitive="TanStack Table" pattern="WAI-ARIA table" />

<Playground
	name="data-table/playground"
	component="DataTable"
	controls={[
		{ prop: "selectable", type: "boolean", default: true },
		{ prop: "loading", type: "boolean", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe a tabela e o tipo das colunas. Ela roda no cliente.

<Import names="DataTable, type ColumnDef" />

## Anatomia [#anatomia]

Uma `<table>` nativa dentro de uma caixa que rola para o lado quando a tabela não cabe, com um rodapé para o status e as páginas. O rodapé só aparece quando a tabela tem seleção ou mais de uma página.

<Anatomy
	tree={{
		slot: "data-table",
		tag: "div",
		children: [
			{
				slot: "data-table-container",
				tag: "div",
				note: "rola quando não cabe",
				children: [
					{
						slot: "data-table-table",
						tag: "table",
						children: [
							{
								slot: "data-table-header",
								tag: "thead",
								children: [
									{
										slot: "data-table-header-row",
										tag: "tr",
										children: [
											{
												slot: "data-table-head",
												tag: "th",
												children: [
													{
														slot: "data-table-sort-button",
														tag: "button",
														note: "colunas ordenáveis",
														row: true,
														children: [{ slot: "data-table-sort-icon", tag: "span" }],
													},
												],
											},
										],
									},
								],
							},
							{
								slot: "data-table-body",
								tag: "tbody",
								children: [{ slot: "data-table-row", tag: "tr", row: true, children: [{ slot: "data-table-cell", tag: "td" }, { slot: "data-table-cell", tag: "td" }] }],
							},
						],
					},
				],
			},
			{
				slot: "data-table-footer",
				tag: "div",
				row: true,
				children: [
					{ slot: "data-table-status", tag: "span" },
					{ slot: "pagination", tag: "nav", note: "mais de uma página" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo de verdade que você pode copiar. Todos usam o estilo, o modo e a marca escolhidos na barra acima.

<Preview name="data-table/basic" compact />

<ExampleGrid>
	<Example name="data-table/sorting" title="Ordenação" wide>
		Clique num cabeçalho para ordenar. Números começam pelo maior, texto começa pelo A, e o terceiro clique volta à ordem original. Desligue a ordenação com `enableSorting: false` onde a ordem não diz nada, como num código.
	</Example>
	<Example name="data-table/selection" title="Seleção de linhas" wide>
		Use `selectable` quando a pessoa age sobre várias linhas de uma vez. Dê a cada caixa o nome da linha com `selectRowLabel`, para o leitor de tela dizer qual pedido ela seleciona, e não "Select row 2".
	</Example>
	<Example name="data-table/pagination" title="Páginas" wide>
		Quando as linhas passam de uma tela, defina `pageSize`. Diga quais linhas estão aparecendo em `selectionStatus` e traduza os botões de página com `previousLabel`, `nextLabel` e `pageLabel`.
	</Example>
	<Example name="data-table/loading-state" title="Carregando" wide>
		Clique em Atualizar. `loading` troca as linhas por skeletons, mas skeletons não dizem nada ao leitor de tela, então uma mensagem de status avisa quando o carregamento começa e termina.
	</Example>
	<Example name="data-table/empty" title="Ainda sem linhas" wide>
		Passe um `EmptyState` em `emptyState`. Os cabeçalhos continuam, então a pessoa vê o que a tabela vai mostrar, e a mensagem dá o próximo passo.
	</Example>
	<Example name="data-table/interactive-filter" title="Busca" wide>
		Digite o nome de um cliente. A tabela filtra o que você passa em `data`, uma linha de status anuncia quantos pedidos batem, e Limpar busca devolve o foco ao campo.
	</Example>
	<Example name="data-table/row-actions" title="Ações na linha" wide>
		Botões só com ícone ganham um nome com a linha, como "Baixar nota fiscal do pedido #4821", porque "Baixar" sozinho é igual em toda linha. O cabeçalho da coluna continua para o leitor de tela com `VisuallyHidden`.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Uma tabela de dados costuma ser a peça principal de uma página de administração, com ações acima dela. Estes são pedaços inteiros de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="data-table/context-orders" title="Pedidos para enviar" uses="DataTable · Button · Badge" wide />
	<Context name="data-table/context-users" title="Membros da equipe" uses="DataTable · Avatar · Badge" wide />
	<Context name="data-table/context-transactions" title="Movimentação da conta" uses="DataTable · Badge" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="data-table/do-right-align-numbers" title="Alinhe números à direita.">
		Use `meta: { align: "end" }` nas colunas de números. Os algarismos ficam com a mesma largura, então o maior valor se destaca.
	</Guideline>
	<Guideline kind="dont" name="data-table/dont-left-align-numbers" title="Números alinhados à esquerda.">
		Milhares e centenas começam no mesmo lugar, e a pessoa precisa ler cada valor para comparar.
	</Guideline>
	<Guideline kind="do" name="data-table/do-sort-useful" title="Ordene só as colunas que as pessoas ordenam.">
		Aqui só o nome ordena. Menos botões no cabeçalho são menos paradas de Tab antes dos dados.
	</Guideline>
	<Guideline kind="dont" name="data-table/dont-sort-everything" title="Um botão de ordenar em toda coluna.">
		Toda coluna com accessor ordena por padrão. Ninguém ordena por telefone, e cada botão a mais é mais uma parada para quem usa teclado.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-table"
	type="DataTableProps"
	describe={{
		data: "Os registros, um por linha.",
		columns: "As colunas, no formato do TanStack Table. Colunas com accessor ordenam, a não ser que tenham `enableSorting: false`; `meta: { align: \"end\" }` alinha números à direita.",
		caption: "Dá nome à tabela (`aria-label`) e, quando ela não cabe, à área de rolagem. Diga o que são as linhas.",
		getRowId: "Devolve um id estável para cada linha. A seleção usa esse id; sem ele, as linhas são identificadas pela posição.",
		selectable: "Mostra uma caixa de seleção em cada linha e uma no cabeçalho para selecionar todas.",
		rowSelection: "Linhas selecionadas, controladas por você: um objeto `{ [id]: true }`.",
		defaultRowSelection: "Linhas selecionadas no começo, quando a tabela controla a seleção.",
		onRowSelectionChange: "Chamada quando a seleção muda.",
		sorting: "Ordenação controlada por você: uma lista de `{ id, desc }`.",
		defaultSorting: "Ordenação inicial, quando a tabela controla a ordem.",
		onSortingChange: "Chamada quando a ordenação muda.",
		pageSize: "Linhas por página. Sem ele, todas as linhas aparecem numa página só.",
		pageCount: "Total de páginas, para paginação no servidor.",
		page: "Página atual controlada por você, começando em 1. Sem ela, a tabela guarda a página sozinha.",
		onPageChange: "Chamada com a nova página quando a pessoa troca de página.",
		loading: "Troca as linhas por skeletons enquanto os dados carregam.",
		loadingRows: "Quantas linhas de skeleton mostrar.",
		emptyState: "O que mostrar quando não há linhas e nada está carregando.",
		selectAllLabel: "Nome acessível da caixa de seleção do cabeçalho.",
		selectRowLabel: "Nome acessível da caixa de cada linha. Inclua algo que identifique a linha. O índice conta a partir da primeira linha da página atual.",
		selectionStatus: "Texto do status no rodapé, a partir das contagens de selecionadas e do total. Aparece sempre que o rodapé aparece, inclusive numa tabela paginada sem `selectable`.",
		totalRows: "Total de registros, para o status quando a paginação é no servidor.",
		paginationLabel: "Nome acessível da navegação de páginas.",
		previousLabel: "Texto ou ícone do botão de página anterior.",
		nextLabel: "Texto ou ícone do botão de próxima página.",
		pageLabel: "Nome acessível de cada botão de página.",
	}}
>
	Ela também aceita os atributos de uma `<div>`, como `aria-busy` e `style`. As colunas são `ColumnDef`s do TanStack: `accessorKey` ou `accessorFn`, `header`, `cell`, `enableSorting` e `meta.align`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria tabela.

<StylingHooks
	slots={[
		"data-table",
		"data-table-container",
		"data-table-table",
		"data-table-header",
		"data-table-header-row",
		"data-table-head",
		"data-table-sort-button",
		"data-table-sort-icon",
		"data-table-body",
		"data-table-row",
		"data-table-cell",
		"data-table-footer",
		"data-table-status",
	]}
	prefix="data-table"
	attributes={[
		{ attr: "data-align", value: "start · end, nos cabeçalhos e células" },
		{ attr: "data-sorted", value: "asc · desc, no botão de ordenar" },
		{ attr: "data-selected", value: "numa linha selecionada" },
		{ attr: "data-selection-cell", value: "no cabeçalho e nas células das caixas de seleção" },
		{ attr: "data-loading", value: "nas linhas de skeleton" },
		{ attr: "data-empty", value: "na linha vazia (data-empty-cell na célula)" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa pelos botões de ordenar, pelas caixas de seleção, pelos controles nas células e pelos botões de página. Quando a tabela não cabe, a área de rolagem é uma parada a mais." },
		{ key: "Enter / Espaço", description: "Num botão de ordenar, ordena por aquela coluna, depois inverte, depois volta ao original. Num botão de página, vai para aquela página." },
		{ key: "Espaço", description: "Marca ou desmarca a caixa da linha com foco, ou todas as linhas pela caixa do cabeçalho." },
		{ key: "← / →", description: "Rolam a tabela larga para o lado enquanto a área de rolagem está com o foco." },
	]}
	notes={[
		"A prop caption dá nome à tabela. Diga o que são as linhas, como \"Pedidos de outubro de 2026\"; o padrão \"Data table\" não diz nada.",
		"Cabeçalhos ordenáveis ganham aria-sort (ascending, descending ou none), então o leitor de tela diz como as linhas estão ordenadas.",
		"A caixa do cabeçalho fica indeterminada quando só algumas linhas estão selecionadas, e as linhas selecionadas ganham aria-selected.",
		"Linhas de skeleton são mudas. Coloque uma mensagem com role=\"status\" para o carregamento e para a contagem de resultados de uma busca.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Table", description: "Uma tabela fixa escrita à mão, renderizada no servidor.", href: "/pt-br/docs/components/table" },
		{ title: "Checkbox", description: "O controle usado na seleção de linhas, com o estado indeterminado.", href: "/pt-br/docs/components/checkbox" },
		{ title: "Empty state", description: "A mensagem para quando a tabela não tem linhas.", href: "/pt-br/docs/components/empty-state" },
	]}
/>


# Date field (/pt-br/docs/components/date-field)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Spinbutton (um por segmento)" />

<Playground
	name="date-field/playground"
	component="DateField"
	controls={[
		{ prop: "granularity", options: ["day", "hour", "minute"], default: "day" },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Os valores são objetos do `@internationalized/date`, reexportados pelo pacote; coloque o campo num `Field` para dar um rótulo a ele.

<Import names="DateField, CalendarDate, CalendarDateTime, Field, FieldLabel" />

## Anatomia [#anatomia]

Uma caixa com um segmento para cada parte da data. Separadores como `/` também são segmentos, desenhados só para o olho e pulados pelo teclado.

<Anatomy
	keys={[
		{ label: '[data-slot="date-field"]', color: "#8be36f" },
		{ label: '[data-slot="date-input"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">input</span>
	<span className="a-label">16</span>
	<span className="a-label">11</span>
	<span className="a-label">2026</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="date-field/basic" compact />

<ExampleGrid>
	<Example name="date-field/controlled" title="Controlado">
		Digite outra data. O `onChange` entrega um `CalendarDate`, e o `toString()` é a data ISO que a sua API espera, sem fuso horário para dar errado.
	</Example>
	<Example name="date-field/birth-date" title="Nascimento com limites">
		Mude o ano para 2008 ou antes. `minValue` e `maxValue` marcam o campo como inválido, e um `FieldError` diz qual regra falhou.
	</Example>
	<Example name="date-field/granularity" title="Data e hora">
		Passe um `CalendarDateTime` e `granularity="minute"` quando a hora faz parte da data, como numa consulta. As horas seguem o relógio do idioma.
	</Example>
	<Example name="date-field/placeholder-value" title="Valor de partida">
		Num campo vazio, as setas começam de hoje. O `placeholderValue` começa mais perto da resposta, sem preencher nada.
	</Example>
	<Example name="date-field/locales" title="Idiomas">
		O mesmo 12 de novembro de 2026 em três idiomas: é 11/12 ou 12/11? O `locale` define a ordem dos segmentos e os separadores, então use o idioma da página.
	</Example>
	<Example name="date-field/read-only" title="Somente leitura">
		O `readOnly` mantém o valor focável e lido pelo leitor de tela. Diga na descrição quem pode mudar.
	</Example>
	<Example name="date-field/disabled" title="Desativado">
		O `disabled` no `Field` chega ao rótulo e a todos os segmentos. Diga quando ele volta a abrir.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Campos de data vivem em formulários. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="date-field/context-signup" title="Cadastro com data de nascimento" uses="Card · Field · Input · DateField · Button" />
	<Context name="date-field/context-passport" title="Documento de viagem" uses="Card · Field · Input · DateField · Button" />
	<Context name="date-field/context-invoice" title="Vencimento de fatura" uses="Card · DateField · NativeSelect · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="date-field/do-one-field" title="Um campo para uma data conhecida.">
		A pessoa digita o aniversário de memória; os segmentos recebem os números na ordem.
	</Guideline>
	<Guideline kind="dont" name="date-field/dont-three-selects" title="Três selects para dia, mês e ano.">
		Três listas para abrir e rolar, e nada impede um 31 de fevereiro.
	</Guideline>
	<Guideline kind="do" name="date-field/do-error-message" title="Diga qual regra falhou.">
		A mensagem diz o que mudar, e o leitor de tela lê ela junto com o campo.
	</Guideline>
	<Guideline kind="dont" name="date-field/dont-color-only" title="Uma borda vermelha e mais nada.">
		A pessoa vê que algo está errado, mas não o quê. Cor sozinha não é mensagem de erro.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="DateFieldProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "placeholderValue", "granularity", "hourCycle", "hideTimeZone", "shouldForceLeadingZeros", "isDateUnavailable", "name", "autoFocus"]}
	types={{ value: "DateValue | null", defaultValue: "DateValue | null", onChange: "(value: DateValue | null) => void", minValue: "DateValue", maxValue: "DateValue", placeholderValue: "DateValue", granularity: "\"day\" | \"hour\" | \"minute\" | \"second\"", hourCycle: "12 | 24", isDateUnavailable: "(date: DateValue) => boolean" }}
	describe={{ className: "Classes adicionadas à raiz.", style: "Estilos inline da raiz.", disabled: "Desativa todos os segmentos. Dentro de um `Field`, vale o `disabled` do field quando este não é passado.", readOnly: "Mantém o valor focável e legível, mas não editável.", invalid: "Marca o campo como inválido. Dentro de um `Field`, vale o `invalid` do field quando este não é passado.", required: "Marca o campo como obrigatório para as tecnologias assistivas.", locale: "Idioma BCP 47 para a ordem dos segmentos, os separadores e o relógio, como `\"pt-BR\"` ou `\"en-US\"`. Sem ele, vale o `I18nProvider` mais próximo ou o idioma do navegador.", value: "A data atual (controlada).", defaultValue: "A data inicial (não controlada).", onChange: "Roda a cada mudança de valor. Recebe `null` quando um segmento é apagado.", minValue: "A menor data aceita. Antes dela, o campo fica inválido.", maxValue: "A maior data aceita. Depois dela, o campo fica inválido.", placeholderValue: "A data de onde as setas partem num campo vazio. Também define o tipo do valor, como `CalendarDateTime`. Padrão: hoje à meia-noite.", granularity: "A menor unidade mostrada. Padrão: `\"day\"` para datas e `\"minute\"` para datas com hora.", hourCycle: "Força o relógio de 12 ou 24 horas. Padrão: o do idioma.", hideTimeZone: "Esconde o segmento de fuso horário de um `ZonedDateTime`.", shouldForceLeadingZeros: "Mostra zero à esquerda em dia, mês e hora, mesmo que o idioma não use.", isDateUnavailable: "Marca datas que não podem ser escolhidas; o campo fica inválido nelas.", name: "Nome do input escondido enviado com o formulário, em formato ISO.", autoFocus: "Foca o primeiro segmento ao montar." }}
>
	O `validationBehavior` tem padrão `"aria"`: um valor fora dos limites marca o campo como inválido, mas nunca bloqueia o formulário. As outras props do React Aria passam direto, como `onFocusChange`, `onKeyDown` e `form`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio campo.

<StylingHooks
	slots={["date-field", "date-input", "date-segment"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"date-field" · "date-input" · "date-segment"' },
		{ attr: "data-invalid", value: "na raiz e nos segmentos quando inválido" },
		{ attr: "data-disabled · data-readonly", value: "na raiz e nos segmentos quando desativado · somente leitura" },
		{ attr: "data-placeholder", value: "num segmento ainda sem valor" },
		{ attr: "data-type", value: "a parte do segmento: day · month · year · hour · minute · literal…" },
		{ attr: "data-focused", value: "no segmento com foco" },
	]}
>

```css
/* segmentos retos e sublinhados, só neste formulário */
.passport-form [data-slot="date-field"] {
  --cml-segment-radius: 0;
  --cml-segment-focus-bg: transparent;
  --cml-segment-focus-fg: var(--cml-accent-text);
  --cml-segment-focus-shadow: inset 0 -2px 0 var(--cml-accent);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "0–9", description: "Digita no segmento focado e passa para o próximo quando ele enche." },
		{ key: "Seta para cima · Seta para baixo", description: "Soma ou subtrai um, voltando ao início no fim do segmento." },
		{ key: "Seta para a esquerda · Seta para a direita", description: "Passa de um segmento para outro." },
		{ key: "Page Up · Page Down", description: "Anda um passo maior, como 5 anos." },
		{ key: "Backspace", description: "Apaga o segmento focado." },
		{ key: "Tab", description: "Vai para o próximo segmento e depois sai do campo." },
	]}
	notes={[
		"Cada segmento é um spinbutton com o nome da sua parte (dia, mês, ano) e o rótulo do campo, então a pessoa sabe qual número está mudando.",
		"O valor inteiro é lido como texto, como \"16 de novembro de 2026\", e não como números soltos.",
		"FieldDescription e FieldError ficam ligados pelo aria-describedby, e um campo inválido marca aria-invalid.",
		"Passe sempre o locale: assim o servidor e o navegador formatam igual, e os nomes dos segmentos vêm no idioma da página.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Date picker", description: "O mesmo campo com um calendário em popover.", href: "/pt-br/docs/components/date-picker" },
		{ title: "Time field", description: "Horas e minutos, com fusos horários.", href: "/pt-br/docs/components/time-field" },
		{ title: "Field", description: "Rótulo, descrição e erro de um controle.", href: "/pt-br/docs/components/field" },
	]}
/>


# Date picker (/pt-br/docs/components/date-picker)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Date Picker Dialog" />

<Playground
	name="date-picker/playground"
	component="DatePicker"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. As datas são objetos do `@internationalized/date`, reexportados pela biblioteca. Coloque o seletor num `Field` para dar um rótulo a ele.

<Import names="DatePicker, CalendarDate, CalendarDateTime, isWeekend, Field, FieldLabel" />

## Anatomia [#anatomia]

Uma caixa com um segmento editável para cada parte da data e um botão que abre um `Calendar` num popup. O popup é renderizado num portal e mantém o estilo.

<Anatomy
	keys={[
		{ label: '[data-slot="date-picker"] · [data-slot="date-picker-control"]', color: "#8be36f" },
		{ label: '[data-slot="date-picker-trigger"] · [data-slot="date-picker-popup"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-input"] · [data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">14 / 11 / 2026</span>
	<span className="a-part">botão</span>
	<span className="a-part">popup</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="date-picker/basic" compact />

<ExampleGrid>
	<Example name="date-picker/controlled" title="Controlado, com o dia da semana">
		Escolha outro dia. Escrever o dia da semana na descrição pega um sábado que ninguém queria escolher.
	</Example>
	<Example name="date-picker/min-max" title="Data mínima e máxima">
		`minValue` e `maxValue` riscam os dias fora do intervalo. Confira o valor também e use `invalid` no `Field`, para que uma data digitada receba a mensagem.
	</Example>
	<Example name="date-picker/unavailable" title="Datas indisponíveis">
		`isDateUnavailable` com `isWeekend` bloqueia os fins de semana do idioma da página. Diga a regra na descrição, porque o calendário fica escondido até abrir.
	</Example>
	<Example name="date-picker/with-time" title="Data e hora">
		Passe um `CalendarDateTime` e `granularity="minute"` para ganhar segmentos de hora e minuto. O `hourCycle={24}` tira o AM/PM onde o relógio de 24 horas é mais claro, como na agenda de um webinar.
	</Example>
	<Example name="date-picker/placeholder" title="Abre no mês certo">
		Sem valor, o calendário abre no dia de hoje. O `placeholderValue` abre onde estão as datas que importam, sem preencher o campo.
	</Example>
	<Example name="date-picker/read-only" title="Somente leitura">
		O `readOnly` deixa a data focável e legível, ao contrário do `disabled`. Diga na descrição quem pode mudar.
	</Example>
	<Example name="date-picker/required" title="Obrigatório num formulário">
		Envie o formulário vazio. O erro diz o que falta, fica ligado ao campo e some assim que uma data é escolhida.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Datas fazem parte de tarefas maiores. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="date-picker/context-flight" title="Busca de voos" uses="Card · Field · Input · DatePicker · Button" />
	<Context name="date-picker/context-schedule" title="Agendar um post" uses="Card · Field · Textarea · DatePicker · Button" />
	<Context name="date-picker/context-invoice" title="Vencimento da cobrança" uses="Card · Field · Input · NativeSelect · DatePicker · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="date-picker/do-near-date" title="Calendário para datas próximas.">
		Uma entrega ou uma reserva fica a poucos cliques, e o calendário mostra o dia da semana.
	</Guideline>
	<Guideline kind="dont" name="date-picker/dont-birth-date" title="Calendário para data de nascimento.">
		Voltar 30 anos, mês a mês, é lento. Use um `DateField` e deixe a pessoa digitar.
	</Guideline>
	<Guideline kind="do" name="date-picker/do-state-rule" title="Diga quais datas valem.">
		A regra aparece antes de a pessoa abrir o calendário ou digitar uma data.
	</Guideline>
	<Guideline kind="dont" name="date-picker/dont-hidden-rule" title="Regra descoberta pelo erro.">
		"Data indisponível." chega tarde demais e não diz quais datas estão livres.
	</Guideline>
</Guidelines>

## Props [#props]

O `DatePicker` recebe as props do date picker do React Aria. Estas são as mais usadas:

<Props
	file="date"
	type="DatePickerProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "placeholderValue", "granularity", "hourCycle", "firstDayOfWeek", "onOpenChange", "name"]}
	types={{ value: "DateValue | null", defaultValue: "DateValue | null", onChange: "(value: DateValue | null) => void", minValue: "DateValue", maxValue: "DateValue", placeholderValue: "DateValue", isDateUnavailable: "(date: DateValue) => boolean", granularity: '"day" | "hour" | "minute" | "second"', hourCycle: "12 | 24", firstDayOfWeek: '"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"', onOpenChange: "(isOpen: boolean) => void", weekdayStyle: '"narrow" | "short" | "long"', calendarFooter: "ReactNode" }}
	describe={{
		className: "Classe do elemento raiz.",
		style: "Estilo inline do elemento raiz.",
		open: "Abre ou fecha o calendário, controlado. Use junto com `onOpenChange`.",
		disabled: "Desativa os segmentos e o botão do calendário.",
		readOnly: "Mostra a data e deixa focável, mas não deixa mudar.",
		invalid: "Marca o seletor como inválido. Dentro de um `Field`, vale o `invalid` do campo quando esta prop não é passada.",
		required: "Marca o seletor como obrigatório para as tecnologias assistivas.",
		locale: "O idioma que define a ordem dos segmentos, os nomes dos meses e o primeiro dia da semana, como `\"pt-BR\"`. Usa o do navegador por padrão.",
		weekdayStyle: "Como os dias da semana aparecem no calendário. O padrão é `\"short\"`.",
		triggerLabel: "Nome acessível do botão do calendário. O React Aria já traz um padrão traduzido.",
		previousLabel: "Nome acessível do botão de mês anterior. O React Aria já traz um padrão traduzido.",
		nextLabel: "Nome acessível do botão de próximo mês. O React Aria já traz um padrão traduzido.",
		calendarFooter: "Conteúdo mostrado abaixo da grade do calendário, como uma legenda ou um aviso.",
		value: "A data, controlada. `null` quando o campo está vazio.",
		defaultValue: "A data inicial, não controlada.",
		onChange: "Roda quando a data muda, pelo teclado ou pelo calendário.",
		minValue: "A data mais cedo permitida.",
		maxValue: "A data mais tarde permitida.",
		isDateUnavailable: "Devolve `true` para os dias que não podem ser escolhidos.",
		placeholderValue: "A data usada para abrir o calendário e preencher os segmentos quando não há valor.",
		granularity: "A menor parte editável. `\"hour\"`, `\"minute\"` e `\"second\"` adicionam a hora.",
		hourCycle: "Força o relógio de 12 ou 24 horas. Por padrão, segue o idioma.",
		firstDayOfWeek: "O primeiro dia da semana no calendário. Por padrão, segue o idioma.",
		onOpenChange: "Roda quando o calendário abre ou fecha.",
		name: "Identifica a data no envio do formulário, no formato ISO.",
	}}
>
	As outras props do React Aria passam direto, como `defaultOpen`, `shouldCloseOnSelect`, `hideTimeZone`, `shouldForceLeadingZeros`, `pageBehavior` e `autoFocus`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio seletor. O calendário do popup lê os tokens do `Calendar`.

<StylingHooks
	slots={["date-picker", "date-picker-control", "date-input", "date-segment", "date-picker-trigger", "date-picker-popup", "date-picker-dialog"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"date-picker" · "date-picker-control" · "date-input" · "date-segment" · "date-picker-trigger" · "date-picker-popup"' },
		{ attr: "data-open", value: "na raiz enquanto o calendário está aberto" },
		{ attr: "data-invalid", value: "na raiz, no controle e nos segmentos quando inválido" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-focus-within", value: "na raiz e no controle enquanto um segmento tem foco" },
		{ attr: "data-placeholder · data-type", value: "num segmento: ainda vazio · a parte dele (dia, mês, ano, literal…)" },
	]}
>

```css
/* destaque mais suave nos segmentos, só no formulário de reserva */
.reserva [data-slot="date-segment"] {
  --cml-segment-focus-bg: var(--cml-item-highlight);
  --cml-segment-focus-fg: var(--cml-fg);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa pelos segmentos e depois pelo botão do calendário." },
		{ key: "Seta para cima / Seta para baixo", description: "Aumenta ou diminui o segmento focado." },
		{ key: "Seta para a esquerda / Seta para a direita", description: "Vai para o segmento anterior ou o próximo." },
		{ key: "0–9", description: "Digita no segmento e avança quando ele está completo." },
		{ key: "Backspace", description: "Limpa o segmento focado." },
		{ key: "Alt + Seta para baixo", description: "Abre o calendário a partir de um segmento." },
		{ key: "Setas (calendário)", description: "Andam entre os dias. Page Up / Page Down trocam o mês." },
		{ key: "Enter", description: "Escolhe o dia focado e fecha o calendário." },
		{ key: "Escape", description: "Fecha o calendário e devolve o foco ao botão." },
	]}
	notes={[
		"Cada segmento é um spinbutton nomeado pelo rótulo do campo, então o leitor de tela anuncia a parte e a data completa.",
		"O popup é um diálogo. O foco entra no calendário quando ele abre e volta ao botão quando fecha.",
		"Dias indisponíveis ou fora do intervalo são anunciados como indisponíveis, não só riscados.",
		"O FieldDescription e o FieldError ficam ligados por aria-describedby, e um seletor inválido marca aria-invalid.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Date range picker", description: "Data de início e de fim num só campo.", href: "/pt-br/docs/components/date-range-picker" },
		{ title: "Date field", description: "Uma data digitada, sem calendário.", href: "/pt-br/docs/components/date-field" },
		{ title: "Calendar", description: "A grade do mês sozinha.", href: "/pt-br/docs/components/calendar" },
	]}
/>


# Date range picker (/pt-br/docs/components/date-range-picker)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Date Picker Dialog" />

<Playground
	name="date-range-picker/playground"
	component="DateRangePicker"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O valor é um objeto `{ start, end }` com datas do `@internationalized/date`, reexportadas pela biblioteca. Coloque o seletor num `Field` para dar um rótulo a ele.

<Import names="DateRangePicker, CalendarDate, isWeekend, Field, FieldLabel" />

## Anatomia [#anatomia]

Dois campos de data unidos por um separador e um botão que abre um `RangeCalendar` num popup. O popup é renderizado num portal e mantém o estilo.

<Anatomy
	keys={[
		{ label: '[data-slot="date-range-picker"] · [data-slot="date-picker-control"]', color: "#8be36f" },
		{ label: '[data-slot="date-range-separator"] · [data-slot="date-picker-trigger"] · [data-slot="date-picker-popup"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-input"] · [data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">21/12/2026</span>
	<span className="a-part">–</span>
	<span className="a-label">31/12/2026</span>
	<span className="a-part">botão</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="date-range-picker/basic" compact />

<ExampleGrid>
	<Example name="date-range-picker/controlled" title="Controlado, com a duração">
		Mude as datas. Contar as diárias abaixo do campo poupa a pessoa de fazer a conta de cabeça.
	</Example>
	<Example name="date-range-picker/max-length" title="Intervalo máximo">
		Não há prop para duração máxima, então confira no `onChange` e use `invalid` no `Field`. O erro diz como corrigir.
	</Example>
	<Example name="date-range-picker/unavailable" title="Datas reservadas">
		O `isDateUnavailable` risca os dias reservados, e o intervalo não pode passar por eles. Diga também na descrição quais datas estão ocupadas.
	</Example>
	<Example name="date-range-picker/business-days" title="Passando por fins de semana">
		Com `allowsNonContiguousRanges`, o intervalo pode atravessar dias indisponíveis, como os fins de semana de uma sprint, sem contar esses dias.
	</Example>
	<Example name="date-range-picker/separator" title="Separador próprio">
		O `separator` troca o traço, aqui por uma palavra. Ele fica escondido do leitor de tela, que chama os dois campos de data inicial e final.
	</Example>
	<Example name="date-range-picker/read-only" title="Somente leitura">
		O `readOnly` mostra um período fechado que ainda pode ser focado e lido. Diga onde reclamar se estiver errado.
	</Example>
	<Example name="date-range-picker/required" title="Obrigatório num formulário">
		Envie vazio. `startName` e `endName` mandam duas datas ISO, e o erro some quando as duas são escolhidas.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Intervalos filtram, reservam e planejam. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="date-range-picker/context-report" title="Filtro de relatório com atalhos" uses="Card · Field · DateRangePicker · Button" />
	<Context name="date-range-picker/context-hotel" title="Reserva de hospedagem" uses="Card · Field · DateRangePicker · NumberField · Button" />
	<Context name="date-range-picker/context-time-off" title="Pedido de folga" uses="Card · NativeSelect · Field · DateRangePicker · Textarea · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="date-range-picker/do-one-range" title="Um campo para um intervalo.">
		O calendário mostra o período inteiro, e o fim não fica antes do início.
	</Guideline>
	<Guideline kind="dont" name="date-range-picker/dont-two-pickers" title="Dois seletores para uma hospedagem.">
		Nenhum calendário mostra o período, e a pessoa escolhe a segunda data sem ver a primeira.
	</Guideline>
	<Guideline kind="do" name="date-range-picker/do-show-length" title="Diga quanto tempo dura.">
		"10 dias úteis, volta na segunda" confirma o intervalo em palavras.
	</Guideline>
	<Guideline kind="dont" name="date-range-picker/dont-hide-length" title="Deixar a pessoa contando.">
		Só as duas datas obrigam a contar os dias, e é fácil esquecer os fins de semana.
	</Guideline>
</Guidelines>

## Props [#props]

O `DateRangePicker` recebe as props do date range picker do React Aria. Estas são as mais usadas:

<Props
	file="date"
	type="DateRangePickerProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "allowsNonContiguousRanges", "placeholderValue", "granularity", "firstDayOfWeek", "onOpenChange", "startName", "endName"]}
	types={{ value: "DateRange | null", defaultValue: "DateRange | null", onChange: "(value: DateRange | null) => void", minValue: "DateValue", maxValue: "DateValue", placeholderValue: "DateValue", isDateUnavailable: "(date: DateValue) => boolean", granularity: '"day" | "hour" | "minute" | "second"', firstDayOfWeek: '"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"', onOpenChange: "(isOpen: boolean) => void", weekdayStyle: '"narrow" | "short" | "long"', separator: "ReactNode", calendarFooter: "ReactNode" }}
	describe={{
		className: "Classe do elemento raiz.",
		style: "Estilo inline do elemento raiz.",
		open: "Abre ou fecha o calendário, controlado. Use junto com `onOpenChange`.",
		disabled: "Desativa os dois campos e o botão do calendário.",
		readOnly: "Mostra o intervalo e deixa focável, mas não deixa mudar.",
		invalid: "Marca o seletor como inválido. Dentro de um `Field`, vale o `invalid` do campo quando esta prop não é passada.",
		required: "Marca as duas datas como obrigatórias para as tecnologias assistivas.",
		locale: "O idioma que define a ordem dos segmentos, os nomes dos meses e o primeiro dia da semana, como `\"pt-BR\"`. Usa o do navegador por padrão.",
		weekdayStyle: "Como os dias da semana aparecem no calendário. O padrão é `\"short\"`.",
		separator: "O que fica entre a data inicial e a final. Escondido do leitor de tela. O padrão é `\"–\"`.",
		triggerLabel: "Nome acessível do botão do calendário. O React Aria já traz um padrão traduzido.",
		previousLabel: "Nome acessível do botão de mês anterior. O React Aria já traz um padrão traduzido.",
		nextLabel: "Nome acessível do botão de próximo mês. O React Aria já traz um padrão traduzido.",
		calendarFooter: "Conteúdo mostrado abaixo da grade do calendário, como uma legenda ou um aviso.",
		value: "O intervalo, controlado. `null` quando está vazio.",
		defaultValue: "O intervalo inicial, não controlado.",
		onChange: "Roda quando o intervalo muda, pelo teclado ou pelo calendário.",
		minValue: "A data mais cedo permitida.",
		maxValue: "A data mais tarde permitida.",
		isDateUnavailable: "Devolve `true` para os dias que não podem ser escolhidos.",
		allowsNonContiguousRanges: "Deixa o intervalo atravessar dias indisponíveis, como fins de semana.",
		placeholderValue: "A data usada para abrir o calendário e preencher os segmentos quando não há valor.",
		granularity: "A menor parte editável. `\"hour\"`, `\"minute\"` e `\"second\"` adicionam a hora.",
		firstDayOfWeek: "O primeiro dia da semana no calendário. Por padrão, segue o idioma.",
		onOpenChange: "Roda quando o calendário abre ou fecha.",
		startName: "Identifica a data inicial no envio do formulário, no formato ISO.",
		endName: "Identifica a data final no envio do formulário, no formato ISO.",
	}}
>
	As outras props do React Aria passam direto, como `defaultOpen`, `shouldCloseOnSelect`, `hourCycle`, `hideTimeZone`, `pageBehavior` e `autoFocus`. Ao contrário do `DatePicker`, ele não pega o `name` do `Field`: use `startName` e `endName`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio seletor. O calendário do popup lê os tokens do `RangeCalendar`.

<StylingHooks
	slots={["date-range-picker", "date-picker-control", "date-input", "date-segment", "date-range-separator", "date-picker-trigger", "date-picker-popup", "date-picker-dialog"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"date-range-picker" · "date-picker-control" · "date-input" · "date-range-separator" · "date-picker-trigger" · "date-picker-popup"' },
		{ attr: "data-open", value: "na raiz enquanto o calendário está aberto" },
		{ attr: "data-invalid", value: "na raiz, no controle e nos segmentos quando inválido" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-focus-within", value: "na raiz e no controle enquanto um segmento tem foco" },
		{ attr: "data-placeholder · data-type", value: "num segmento: ainda vazio · a parte dele (dia, mês, ano, literal…)" },
	]}
>

```css
/* mais espaço em volta do separador, só nos filtros do relatório */
.filtros-relatorio [data-slot="date-range-separator"] {
  padding-inline: 0.5rem;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa pelos segmentos da data inicial, depois da final e depois pelo botão do calendário." },
		{ key: "Seta para cima / Seta para baixo", description: "Aumenta ou diminui o segmento focado." },
		{ key: "Seta para a esquerda / Seta para a direita", description: "Vai para o segmento anterior ou o próximo, passando pelas duas datas." },
		{ key: "0–9", description: "Digita no segmento e avança quando ele está completo." },
		{ key: "Alt + Seta para baixo", description: "Abre o calendário a partir de um segmento." },
		{ key: "Enter (calendário)", description: "Começa o intervalo no dia focado; um segundo Enter termina e fecha o calendário." },
		{ key: "Setas (calendário)", description: "Andam entre os dias e estendem o intervalo enquanto ele está começado." },
		{ key: "Escape", description: "Fecha o calendário e devolve o foco ao botão." },
	]}
	notes={[
		"Os dois campos formam um grupo nomeado pelo rótulo, e cada um é anunciado como data inicial ou final.",
		"O popup é um diálogo. O foco entra no calendário quando ele abre e volta ao botão quando fecha.",
		"O separador tem aria-hidden, então uma palavra como \"até\" não é lida entre as datas.",
		"O FieldDescription e o FieldError ficam ligados por aria-describedby, e um seletor inválido marca aria-invalid.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Date picker", description: "Uma data, digitada ou escolhida.", href: "/pt-br/docs/components/date-picker" },
		{ title: "Range calendar", description: "A grade de intervalo sozinha, sempre visível.", href: "/pt-br/docs/components/range-calendar" },
		{ title: "Date field", description: "Uma data digitada, sem calendário.", href: "/pt-br/docs/components/date-field" },
	]}
/>


# Dialog (/pt-br/docs/components/dialog)

<ComponentMeta file="dialog" primitive="Base UI" pattern="WAI-ARIA Dialog (Modal)" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose, DialogActions" />

## Anatomia [#anatomia]

Um botão `dialog-trigger` abre um `dialog-backdrop` e este popup. Os dois renderizam num portal que mantém o estilo, o modo e a cor da página em volta do gatilho.

<Anatomy
	tree={{
		slot: "dialog-popup",
		tag: "div",
		note: "role=dialog",
		children: [
			{ slot: "dialog-title", tag: "h2" },
			{ slot: "dialog-description", tag: "p" },
			{ slot: "children", note: "campos, tabelas, texto" },
			{
				slot: "dialog-actions",
				tag: "div",
				row: true,
				children: [
					{ slot: "dialog-close", tag: "button" },
					{ slot: "button", tag: "button", note: "ação principal" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Abra: o dialog usa o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="dialog/basic" compact />

<ExampleGrid>
	<Example name="dialog/form-submit" title="Formulário que fecha ao enviar">
		Clique. O foco começa no campo; enviar salva, fecha o dialog, devolve o foco ao gatilho e uma mensagem de status diz o que mudou.
	</Example>
	<Example name="dialog/controlled" title="Aberto por outro elemento">
		Quando o estado mora em outro lugar (um item de menu, um atalho), passe `open` e `onOpenChange`. O foco continua voltando para quem abriu.
	</Example>
	<Example name="dialog/scrolling" title="Conteúdo longo">
		Role só o corpo, para o título e os botões ficarem à vista. Use um `ScrollArea`: a área recebe foco, então dá para rolar pelo teclado.
	</Example>
	<Example name="dialog/outside-click" title="Não fecha com clique fora">
		Quando a pessoa digita muito, um clique sem querer não deve jogar tudo fora. O `disablePointerDismissal` mantém o Esc e os botões funcionando.
	</Example>
	<Example name="dialog/close-button" title="Botão de fechar no canto">
		Todo dialog precisa de uma saída visível: leitor de tela em tela touch não tem Esc. Ponha o botão de ícone por último no código, para o foco começar no conteúdo.
	</Example>
	<Example name="dialog/wide" title="Mais largo para uma tabela" wide>
		Existe uma largura padrão. Defina `inline-size` no `DialogContent` quando uma tabela precisar de espaço; no celular ele continua cabendo na tela.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Um dialog guarda uma tarefa que pertence a algo na página. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="dialog/context-edit-profile" title="Editar perfil" uses="Card · Avatar · Dialog · Field" />
	<Context name="dialog/context-invite" title="Convidar pessoas" uses="Card · Avatar · Badge · Dialog · NativeSelect" />
	<Context name="dialog/context-export" title="Exportar um relatório" uses="Card · Dialog · RadioGroup · Switch" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="dialog/do-one-task" title="Uma tarefa, poucos campos.">
		A pessoa termina e volta ao que estava fazendo.
	</Guideline>
	<Guideline kind="dont" name="dialog/dont-whole-page" title="Uma página de configurações inteira num dialog.">
		Ele rola, esconde a página a que pertence e não dá para compartilhar o link. Use uma página.
	</Guideline>
	<Guideline kind="do" name="dialog/do-task-title" title="Um título que diz a tarefa.">
		"Convidar pessoas" e "Enviar convites" dizem o que acontece, também para um leitor de tela que só lê o título.
	</Guideline>
	<Guideline kind="dont" name="dialog/dont-generic-title" title="&quot;Informação&quot; e &quot;OK&quot;.">
		O título é o nome acessível do dialog. Um título genérico não diz a ninguém onde está.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="dialog" type="DialogProps" include={["open", "defaultOpen", "onOpenChange", "modal", "disablePointerDismissal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{ open: "Se o dialog está aberto. Use com `onOpenChange` para controlar o estado.", defaultOpen: "Se o dialog começa aberto, sem controlar o estado.", onOpenChange: "Chamado quando o dialog abre ou fecha. `eventDetails.reason` diz o motivo, por exemplo `escape-key` ou `outside-press`.", modal: "`true` prende o foco, trava a rolagem e bloqueia cliques fora. `trap-focus` só prende o foco. `false` deixa a página livre.", disablePointerDismissal: "Impede que um clique fora feche o dialog. O Esc e os botões continuam funcionando." }}
>
	`DialogTrigger`, `DialogTitle`, `DialogDescription` e `DialogClose` recebem as props do seu elemento, mais `render`.
</Props>

O `DialogContent` decide para onde vai o foco:

<Props file="dialog" type="DialogContentProps" include={["initialFocus", "finalFocus"]}
	types={{ initialFocus: "boolean | RefObject | (openType) => HTMLElement | boolean", finalFocus: "boolean | RefObject | (closeType) => HTMLElement | boolean" }}
	describe={{ initialFocus: "O elemento que recebe o foco ao abrir. Por padrão, o primeiro elemento focável dentro do dialog.", finalFocus: "O elemento que recebe o foco ao fechar. Por padrão, o gatilho ou o elemento que estava focado antes." }}
/>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio popup.

<StylingHooks
	slots={["dialog-trigger", "dialog-backdrop", "dialog-popup", "dialog-title", "dialog-description", "dialog-actions", "dialog-close"]}
	prefix="dialog"
	attributes={[
		{ attr: "data-open", value: "presente quando aberto" },
		{ attr: "data-closed", value: "presente quando fechado" },
		{ attr: "data-starting-style", value: "presente enquanto abre" },
		{ attr: "data-ending-style", value: "presente enquanto fecha" },
		{ attr: "data-nested", value: "presente num dialog aberto de dentro de outro" },
	]}
>

```css
/* dialog em tela cheia no celular */
@media (max-width: 40rem) {
  .checkout [data-slot="dialog-popup"] {
    inline-size: 100vw;
    max-block-size: 100dvh;
    border-radius: 0;
  }
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter / Space", description: "No gatilho, abre o dialog. O foco vai para o primeiro campo ou botão dentro dele." },
		{ key: "Tab", description: "Vai para o próximo elemento focável. O foco fica dentro do dialog: depois do último, volta ao primeiro." },
		{ key: "Shift + Tab", description: "Vai para o elemento focável anterior, voltando ao último." },
		{ key: "Escape", description: "Fecha o dialog. O foco volta para o elemento que o abriu." },
	]}
	notes={[
		"O popup tem role=\"dialog\". O DialogTitle dá o nome e o DialogDescription a descrição, por aria-labelledby e aria-describedby: sempre inclua um título.",
		"Enquanto ele está aberto, o resto da página fica oculto para o leitor de tela (aria-hidden), o foco não sai dele e a página não rola.",
		"Um clique fora fecha o dialog, a menos que você passe disablePointerDismissal. O Esc e os botões de fechar sempre funcionam.",
		"Quando o elemento que abriu some depois de fechar, aponte o finalFocus para algo que faça sentido e anuncie o resultado com role=\"status\".",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "AlertDialog", description: "Pede confirmação de uma decisão que não dá para desfazer.", href: "/pt-br/docs/components/alert-dialog" },
		{ title: "Popover", description: "Um painel pequeno ao lado do gatilho, sem bloquear a página.", href: "/pt-br/docs/components/popover" },
		{ title: "Field", description: "Rótulo, descrição e erro para os campos de dentro.", href: "/pt-br/docs/components/field" },
	]}
/>


# DirectionProvider (/pt-br/docs/components/direction-provider)

<ComponentMeta file="scroll-area" primitive="Base UI" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. É o `DirectionProvider` do Base UI, reexportado.

<Import names="DirectionProvider" />

Você precisa de duas coisas, e cada uma faz um trabalho diferente:

- **`dir="rtl"` num elemento** (normalmente o `<html>`, com `lang`) espelha o layout: alinhamento do texto, ordem do flex e do grid, e todas as propriedades lógicas dos estilos.
- **`<DirectionProvider direction="rtl">`** avisa o JavaScript dos componentes: qual seta avança, de que ponta o slider começa e para que lado o popup se alinha. O navegador não tem como contar isso a eles.

## Anatomia [#anatomia]

Ele não renderiza nenhum elemento: só coloca a direção no contexto do React. O atributo `dir` fica por sua conta.

<Anatomy
	tree={{
		slot: "html",
		tag: "html dir=rtl lang=ar",
		note: "layout e leitores de tela",
		children: [
			{
				slot: "DirectionProvider",
				note: "sem elemento, contexto do React",
				children: [{ slot: "slider · tabs · toolbar · radio-group · menu · select…", note: "leem a direção" }],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Os textos em árabe e hebraico são frases curtas de exemplo (Salvar, Cancelar, Configurações…). Peça a um falante nativo para revisar os textos reais.

<Preview name="direction-provider/basic" compact />

<ExampleGrid>
	<Example name="direction-provider/slider-keys" title="Sliders começam pela direita">
		Foque cada slider e use as setas. Em RTL o preenchimento cresce da direita, a seta para a esquerda aumenta o valor e a seta para a direita diminui, então a tecla combina com o movimento.
	</Example>
	<Example name="direction-provider/tabs-keys" title="Abas invertem as setas">
		A primeira aba fica à direita. A seta para a esquerda vai para a próxima aba; Home e End continuam indo para a primeira e a última.
	</Example>
	<Example name="direction-provider/menu-rtl" title="Menus numa seção da direita para a esquerda">
		Abra o menu. Para cima e para baixo não mudam. O popup é renderizado no `<body>`, então passe `dir` para ele; ele se alinha à borda direita do gatilho quando o `<html>` tem `dir="rtl"`.
	</Example>
	<Example name="direction-provider/language-switch" title="Trocar a direção em tempo de execução">
		Ligue o switch. Mude o provider, o `dir` e o `lang` juntos, e espelhe os ícones que significam "avançar" ou "voltar".
	</Example>
	<Example name="direction-provider/logical-css" title="Propriedades lógicas no seu CSS">
		Escreva `padding-inline-start` e `border-inline-start`, não left e right. Assim o mesmo aviso funciona nas duas direções, sem uma segunda folha de estilo.
	</Example>
	<Example name="direction-provider/mixed-direction" title="Conteúdo da esquerda para a direita dentro">
		E-mails, telefones e códigos são lidos da esquerda para a direita. Dê `dir="ltr"` aos campos deles e envolva valores no meio do texto em `<bdi>`, para não embaralhar a frase.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Pedaços inteiros de interface em idiomas da direita para a esquerda, no estilo que você escolheu.

<ContextGrid>
	<Context name="direction-provider/context-settings" title="Configurações da conta (árabe)" uses="DirectionProvider · Card · Field · Select · Switch" />
	<Context name="direction-provider/context-order" title="Resumo do pedido (hebraico)" uses="DirectionProvider · Card · DataList · Badge · Button" />
	<Context name="direction-provider/context-filters" title="Filtro de preço (árabe)" uses="DirectionProvider · Card · Slider · Switch · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="direction-provider/do-both" title="Defina dir e o provider.">
		O rótulo, o preenchimento e as setas concordam entre si.
	</Guideline>
	<Guideline kind="dont" name="direction-provider/dont-dir-only" title="Só o dir.">
		O preenchimento começa pela direita, mas a seta para a direita aumenta o valor e o clique cai no ponto espelhado.
	</Guideline>
	<Guideline kind="do" name="direction-provider/do-logical" title="Margens e espaçamentos lógicos.">
		`margin-inline-start` mantém o espaço entre a palavra e o badge em qualquer direção.
	</Guideline>
	<Guideline kind="dont" name="direction-provider/dont-physical" title="margin-left numa página da direita para a esquerda.">
		O espaço vai para o lado errado e o badge encosta na palavra.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="scroll-area"
	type="DirectionProviderProps"
	include={["direction", "children"]}
	types={{ direction: '"ltr" | "rtl"' }}
	describe={{
		direction: "A direção de leitura que os componentes dentro dele seguem.",
		children: "Os componentes que devem seguir a direção.",
	}}
>
	Ele não renderiza elemento, então não recebe outras props. Defina `dir` e `lang` num elemento você mesmo.
</Props>

## Styling hooks [#styling-hooks]

Não há nada para estilizar no provider. Os estilos usam propriedades lógicas em tudo, então seguem o `dir`; use-o quando precisar de uma regra só para uma direção.

<StylingHooks
	slots={[]}
	attributes={[
		{ attr: "dir", value: "rtl · ltr, no seu elemento (herdado)" },
		{ attr: ":dir(rtl)", value: "pseudoclasse CSS que pega a direção herdada" },
		{ attr: "data-orientation", value: "horizontal · vertical, em sliders, abas e barras de ferramentas" },
	]}
>

```css
/* espelha ícones de direção em páginas da direita para a esquerda */
:dir(rtl) .icone-avancar {
  scale: -1 1;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Seta para a esquerda", description: "Em RTL: próxima aba ou item da barra; aumenta o valor do slider." },
		{ key: "Seta para a direita", description: "Em RTL: aba ou item anterior; diminui o valor do slider." },
		{ key: "Seta para cima / para baixo", description: "Não mudam: menus, selects e listas verticais não invertem." },
		{ key: "Home / End", description: "Não mudam: primeiro e último item, ou o mínimo e o máximo do slider." },
	]}
	notes={[
		"O provider não tem elemento e não recebe foco. Os leitores de tela descobrem a direção e o idioma pelo dir e pelo lang dos seus elementos.",
		"Defina lang junto com dir, para que os leitores de tela leiam árabe ou hebraico com a voz certa.",
		"Popups são renderizados no <body>. Defina dir no <html> para uma página toda em RTL, ou passe dir ao popup dentro de uma seção da direita para a esquerda.",
		"Espelhe os ícones que apontam para avançar ou voltar. Não mexa nos que não apontam, como play, check ou relógio.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "StyleProvider", description: "Estilo, modo e cor da marca de uma seção.", href: "/pt-br/docs/components/style-provider" },
		{ title: "Slider", description: "Preenche a partir da direita em RTL.", href: "/pt-br/docs/components/slider" },
		{ title: "Tabs", description: "As setas seguem a direção de leitura.", href: "/pt-br/docs/components/tabs" },
	]}
/>


# Drawer (/pt-br/docs/components/drawer)

<ComponentMeta file="drawer" primitive="Base UI" pattern="WAI-ARIA Dialog (Modal)" />

<Playground
	name="drawer/playground"
	component="Drawer"
	controls={[{ prop: "side", options: ["right", "left", "bottom"], default: "right" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter, DrawerClose" />

## Anatomia [#anatomia]

O `DrawerContent` renderiza o fundo escurecido e o painel num portal, com o estilo, o modo e a cor da página em volta do gatilho. Só o corpo rola, então o cabeçalho e o rodapé ficam sempre à vista.

<Anatomy
	tree={{
		slot: "drawer-viewport",
		tag: "div",
		note: "num portal, depois de drawer-backdrop",
		children: [
			{
				slot: "drawer-popup",
				tag: "div",
				note: "role=dialog",
				children: [
					{ slot: "drawer-header", tag: "div", row: true, children: [{ slot: "drawer-title", tag: "h2" }, { slot: "drawer-close", tag: "button", note: "×" }] },
					{ slot: "drawer-body", tag: "div", note: "rola", children: [{ slot: "drawer-description", tag: "p", note: "opcional" }] },
					{ slot: "drawer-footer", tag: "div", note: "ações, sempre à vista" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Todos começam fechados: abra e teste Tab, Escape e um clique no fundo escurecido.

<Preview name="drawer/basic" compact />

<ExampleGrid>
	<Example name="drawer/sides" title="Lados" wide>
		Direita para detalhes e filtros, ao lado do conteúdo que eles mudam. Esquerda para navegação, onde fica o menu. Embaixo no celular, onde o polegar alcança.
	</Example>
	<Example name="drawer/mobile-nav" title="Navegação no celular">
		Clique num link. O menu fecha, o foco volta para o botão do menu e uma mensagem de status diz qual página está aberta.
	</Example>
	<Example name="drawer/filters" title="Filtros com Aplicar e Limpar">
		Mude alguns filtros. O botão principal conta os resultados enquanto você escolhe; nada muda na página até você apertar, e fechar sem apertar descarta as mudanças.
	</Example>
	<Example name="drawer/long-content" title="Conteúdo longo, ações à vista">
		Só o corpo rola, então Aceitar e Recusar ficam no rodapé enquanto a pessoa lê. Um corpo só com texto vira uma parada de Tab enquanto rola, para quem usa teclado conseguir rolar também.
	</Example>
	<Example name="drawer/a11y-named" title="Nome vindo do título">
		O `DrawerTitle` é o nome do diálogo e o `DrawerDescription` é lido logo depois. O × não tem texto, então passe um `aria-label` no idioma da página.
	</Example>
	<Example name="drawer/bottom-sheet" title="Painel de baixo">
		Uma lista curta de opções para o celular. Cada uma fecha o painel e conta o que aconteceu numa mensagem de status.
	</Example>
	<Example name="drawer/from-code" title="Aberto pelo código">
		Sem `DrawerTrigger`, controle com `open` e `onOpenChange`. O foco ainda volta para o botão que abriu.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="drawer/context-cart" title="Carrinho de compras" uses="Drawer · Card · SearchInput · IconButton · Separator" />
	<Context name="drawer/context-notifications" title="Central de notificações" uses="Drawer · IconButton · Badge · Avatar · Button" />
	<Context name="drawer/context-task" title="Detalhes da tarefa" uses="Card · Drawer · Field · Textarea · Checkbox" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="drawer/do-side-task" title="Uma tarefa que precisa da página à vista.">
		Editar o endereço ao lado do pedido a que ele pertence mantém a pessoa situada.
	</Guideline>
	<Guideline kind="dont" name="drawer/dont-confirm" title="Um drawer para um sim ou não.">
		Um painel inteiro para uma frase e dois botões é demais. Use um diálogo de alerta, que ainda põe o foco na opção segura.
	</Guideline>
	<Guideline kind="do" name="drawer/do-sticky-footer" title="Ações no rodapé.">
		O `DrawerFooter` fica à vista enquanto a lista rola, então o próximo passo está sempre ali.
	</Guideline>
	<Guideline kind="dont" name="drawer/dont-actions-in-body" title="Ações no fim de um corpo longo.">
		A pessoa precisa rolar 24 opções para descobrir como confirmar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="drawer"
	type="DrawerProps"
	include={["open", "defaultOpen", "onOpenChange", "modal", "disablePointerDismissal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{
		side: "Borda de onde o painel vem. Arrastar na direção dessa borda fecha o drawer.",
		open: "Se o drawer está aberto. Use junto com `onOpenChange` para controlar pelo código.",
		defaultOpen: "Se o drawer começa aberto, sem controle pelo código.",
		onOpenChange: "Chamado quando o drawer abre ou fecha, com o motivo em `eventDetails`.",
		modal: "Prende o foco e esconde a página de trás. `\"trap-focus\"` só prende o foco.",
		disablePointerDismissal: "Impede que um clique fora feche o drawer.",
	}}
>
	O `DrawerContent` aceita as props do popup, incluindo `initialFocus` e `finalFocus` para escolher onde o foco vai ao abrir e ao fechar. O `DrawerClose` sem filhos renderiza o botão ×; passe `aria-label` no idioma da página (o padrão é "Close").
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio painel.

<StylingHooks
	slots={["drawer-trigger", "drawer-backdrop", "drawer-viewport", "drawer-popup", "drawer-header", "drawer-title", "drawer-description", "drawer-body", "drawer-footer", "drawer-close"]}
	attributes={[
		{ attr: "data-swipe-direction", value: "right · left · down" },
		{ attr: "data-open · data-closed", value: "no popup e no fundo escurecido" },
		{ attr: "data-starting-style · data-ending-style", value: "enquanto entra e sai" },
		{ attr: "data-swiping", value: "presente enquanto é arrastado" },
	]}
>

```css
/* um painel mais largo para o editor de pedidos */
.orders [data-slot="drawer-popup"][data-swipe-direction="right"] {
  inline-size: min(36rem, calc(100vw - 3rem));
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "No gatilho, abre o drawer e leva o foco para o painel." },
		{ key: "Tab", description: "Vai para o próximo controle do drawer. Do último, volta para o primeiro; a página de trás não é alcançada." },
		{ key: "Shift + Tab", description: "Vai para o controle anterior, também dando a volta dentro do drawer." },
		{ key: "Page Down / Page Up", description: "Rolam um corpo longo quando ele tem o foco. Um corpo que rola e não tem controles vira uma parada de Tab." },
		{ key: "Escape", description: "Fecha o drawer e devolve o foco ao elemento que o abriu." },
	]}
	notes={[
		"O painel é um diálogo modal: a página de trás fica escondida do leitor de tela, e um clique no fundo escurecido fecha o drawer.",
		"O DrawerTitle dá nome ao diálogo. Todo drawer precisa de um, mesmo que repita o texto do gatilho.",
		"Ao fechar, o foco volta para o gatilho, ou para o botão que abriu pelo código. Conte o resultado numa mensagem de status, porque o drawer que mostrava ele sumiu.",
		"Em tela de toque, arrastar na direção da borda fecha o painel. Todo gesto tem um botão como alternativa: o ×, uma ação do rodapé ou o Escape.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Dialog", description: "Uma janela centralizada para uma decisão ou um formulário curto.", href: "/pt-br/docs/components/alert-dialog" },
		{ title: "Popover", description: "Um painel pequeno ao lado do gatilho, que não bloqueia a página.", href: "/pt-br/docs/components/popover" },
		{ title: "Field", description: "Rótulos, dicas e erros para os formulários dentro do drawer.", href: "/pt-br/docs/components/field" },
	]}
/>


# Empty state (/pt-br/docs/components/empty-state)

<ComponentMeta file="data-display" pattern="Título + texto + ações" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="EmptyState, EmptyStateIcon, EmptyStateTitle, EmptyStateDescription, EmptyStateActions" />

## Anatomia [#anatomia]

Uma coluna centralizada com até quatro partes. Passe `icon`, `title`, `description` e `actions`, ou monte com as partes como filhos. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "empty-state",
		tag: "div",
		children: [
			{ slot: "empty-state-icon", tag: "span", note: "aria-hidden" },
			{ slot: "empty-state-title", tag: "h3", note: "nível definido por as" },
			{ slot: "empty-state-description", tag: "p" },
			{ slot: "empty-state-actions", tag: "div", note: "botões ou links" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="empty-state/basic" compact />

<ExampleGrid>
	<Example name="empty-state/no-results" title="Busca sem resultado">
		Digite o nome de um produto e depois limpe a busca. Repita o termo no título para a pessoa ver o que mudar, e anuncie a contagem num `role="status"`, porque o empty state em si não é lido quando aparece.
	</Example>
	<Example name="empty-state/error-state" title="Falha ao carregar">
		Quando os dados não carregam, diga o que falhou e que nada se perdeu, e ofereça tentar de novo. O contato com o suporte é um link, porque leva a outro lugar.
	</Example>
	<Example name="empty-state/minimal" title="Nada pendente">
		Quando estar vazio é a boa notícia, uma confirmação curta basta: passe `icon={null}` para tirar o ícone de pasta padrão e deixe as ações de fora.
	</Example>
	<Example name="empty-state/in-card" title="Dentro de um card">
		Mantenha o título do próprio card, para a pessoa saber qual seção está vazia, e diga quando ela vai se preencher.
	</Example>
	<Example name="empty-state/with-parts" title="Montado com as partes">
		Use as partes como filhos quando precisar de mais que um título e uma frase, como as regras de uma importação. Com filhos, nenhum ícone padrão é desenhado.
	</Example>
	<Example name="empty-state/interactive-action" title="Primeiro item">
		Crie um projeto e depois exclua todos. O botão clicado some junto com a tela, então o foco vai para o botão que toma o lugar dele, e uma mensagem de status conta o que aconteceu.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Um empty state costuma ficar onde o conteúdo vai estar: num card, abaixo de uma busca, no lugar de uma lista. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="empty-state/context-inbox" title="Caixa de suporte zerada" uses="Card · Badge · EmptyState · Link" wide />
	<Context name="empty-state/context-search" title="Busca no catálogo" uses="Card · SearchInput · EmptyState · Button" wide />
	<Context name="empty-state/context-team" title="Equipe só com você" uses="Card · EmptyState · Button" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="empty-state/do-actionable-cta" title="Dê o próximo passo.">
		Diga por que o espaço está vazio e coloque ali mesmo a ação que o preenche.
	</Guideline>
	<Guideline kind="dont" name="empty-state/dont-dead-end" title='Só "Vazio".'>
		A pessoa não sabe se algo quebrou nem o que fazer, e vai embora.
	</Guideline>
	<Guideline kind="do" name="empty-state/do-calm-tone" title="Conta nova com tom calmo.">
		Nada deu errado ainda, então use um ícone neutro e diga como o primeiro passo é rápido.
	</Guideline>
	<Guideline kind="dont" name="empty-state/dont-alarming-style" title="Cores de erro num vazio normal.">
		Ícone vermelho e a palavra "Erro" fazem a pessoa achar que perdeu dados.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="EmptyStateProps"
	include={["children"]}
	describe={{
		icon: "Ícone acima do título, escondido do leitor de tela. Sem ele, aparece um ícone de pasta, a não ser que você passe `children`; `null` tira o ícone.",
		title: "O que está vazio, renderizado como `<h3>`. Para outro nível, passe um `<EmptyStateTitle as=\"h4\">` como filho.",
		description: "Por que está vazio e o que fazer em seguida.",
		actions: "Botões ou links do próximo passo, numa linha centralizada no fim.",
		children: "Seu próprio conteúdo, depois da descrição. Use para montar com as partes.",
	}}
>
	`EmptyStateIcon`, `EmptyStateTitle`, `EmptyStateDescription` e `EmptyStateActions` aceitam os atributos do elemento HTML de cada um (`span`, `h3`, `p`, `div`). O `EmptyStateTitle` também aceita `as` (de `h2` a `h6`, ou `p`; padrão `h3`) para definir o nível do título. O `EmptyState` aceita os atributos de uma `div`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou no próprio empty state.

<StylingHooks
	slots={["empty-state", "empty-state-icon", "empty-state-title", "empty-state-description", "empty-state-actions"]}
	prefix="empty-state"
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "Passa pelos botões e links das ações. O empty state em si não é parada de Tab." }]}
	notes={[
		"A prop title renderiza um <h3>. Dentro de um card cujo título também é <h3>, passe um <EmptyStateTitle as=\"h4\"> como filho, para os títulos ficarem aninhados.",
		"O ícone fica dentro de aria-hidden, então o leitor de tela lê só o título e a descrição.",
		"O empty state não é uma região viva. Quando ele substitui resultados depois de uma busca ou exclusão, anuncie a mudança com um role=\"status\" ao lado.",
		"Quando a ação que esvaziou a lista remove o botão com foco, mova o foco você mesmo para o próximo controle, como o campo de busca ou a ação principal do empty state.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Table", description: "Uma tabela sem linhas mantém os cabeçalhos e uma linha explicando por quê.", href: "/pt-br/docs/components/table" },
		{ title: "Skeleton", description: "Aparece enquanto os dados carregam, antes de saber se estão vazios.", href: "/pt-br/docs/components/skeleton" },
		{ title: "Alert", description: "Para um erro que não substitui o conteúdo, como uma falha ao salvar.", href: "/pt-br/docs/components/alert" },
	]}
/>


# Error summary (/pt-br/docs/components/error-summary)

<ComponentMeta file="error-summary" pattern="Alert + in-page links" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. Ele trabalha junto com as partes do `Field`.

<Import names="ErrorSummary" />

## Anatomia [#anatomia]

Um `Alert` de perigo com título e uma lista de links. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="alert"][data-kind="error-summary"]', color: "#8be36f" },
		{ label: '[data-slot="alert-icon"] · [data-slot="alert-title"] · [data-slot="error-summary-list"]', color: "#ffcf7a" },
		{ label: '[data-slot="error-summary-link"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">ícone</span>
	<span className="a-part">título</span>
	<span className="a-label">E-mail</span>
	<span className="a-label">Celular</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="error-summary/basic" compact />

<ExampleGrid>
	<Example name="error-summary/focus-on-submit" title="Foco no envio">
		Clique em Continuar com os campos vazios. O resumo recebe o foco com `ref` e `tabIndex={-1}`, então é lido primeiro, e diminui conforme você corrige cada campo.
	</Example>
	<Example name="error-summary/server-errors" title="Erros vindos do servidor">
		Clique em Salvar. Quando a API recusa um valor, mostre o mesmo resumo: a pessoa tem um só lugar para olhar, venha o erro do navegador ou do backend.
	</Example>
	<Example name="error-summary/any-control" title="Selects e checkboxes">
		O `target` é o id de qualquer controle focável. O id de um checkbox fica no input escondido, que passa o foco para a caixa visível.
	</Example>
	<Example name="error-summary/long-form" title="Num formulário longo">
		Clique num link. O controle rola até o meio da tela, então um cabeçalho fixo nunca esconde o campo para onde você foi.
	</Example>
	<Example name="error-summary/plural" title="Um ou vários">
		Conte os erros no título e escolha o texto com `Intl.PluralRules`, para "1 campo" e "3 campos" ficarem certos em qualquer idioma.
	</Example>
	<Example name="error-summary/with-label" title="Com rótulo escrito">
		O `label` acrescenta uma palavra como "Erro". Alguns estilos mostram ela no lugar do ícone, e ela dá ao alerta um sinal em texto além da cor.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O resumo de erros fica no topo de formulários reais. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="error-summary/context-react-hook-form" title="Cadastro com react-hook-form + zod" uses="Card · ErrorSummary · Field · Input · PasswordInput · Checkbox" />
	<Context name="error-summary/context-checkout" title="Pagamento com cartão" uses="Card · ErrorSummary · Field · Input · Button" />
	<Context name="error-summary/context-profile" title="Perfil não salvo" uses="Card · ErrorSummary · Field · Input · Textarea" />
</ContextGrid>

## Com react-hook-form e zod [#com-react-hook-form-e-zod]

O Camaleo não depende de nenhuma biblioteca de formulários. O cadastro acima liga react-hook-form e zod ao `Field` e ao `ErrorSummary`; a aba Código tem o arquivo inteiro.

```bash
pnpm add react-hook-form zod @hookform/resolvers
```

- **O schema guarda as mensagens.** O `zodResolver(schema)` valida no envio, e cada mensagem do zod vira `fieldState.error.message`.
- **O `Controller` conecta cada controle.** Passe `fieldState.invalid` para `Field invalid` e a mensagem para `FieldError match={fieldState.invalid}`, assim o erro fica ligado ao controle e o `aria-invalid` é marcado.
- **Dê um id a cada controle.** Use `useId()` e coloque no `Input` (ou no `Checkbox`, `NativeSelect` ou `Rating`, que o repassam ao elemento que recebe o foco); o resumo aponta para esse mesmo id.
- **Monte o resumo a partir de `formState.errors`.** Mostre quando `isSubmitted` e houver erros, transforme cada nome inválido em `{ target: id, message: rótulo }` e dê foco a ele quando `submitCount` mudar. Passe `shouldFocusError: false` para o react-hook-form não levar o foco ao primeiro campo antes.
- **Use `noValidate` no formulário.** Senão os balões do próprio navegador aparecem antes das suas mensagens.

```tsx
const { control, handleSubmit, formState: { errors, isSubmitted, submitCount } } =
	useForm<Values>({ resolver: zodResolver(schema), defaultValues, shouldFocusError: false });
const invalid = (Object.keys(labels) as (keyof Values)[]).filter((name) => errors[name]);

useEffect(() => {
	if (submitCount > 0) summaryRef.current?.focus();
}, [submitCount]);

{isSubmitted && invalid.length > 0 && (
	<ErrorSummary
		ref={summaryRef}
		tabIndex={-1}
		title={`Corrija ${invalid.length} campos para continuar.`}
		errors={invalid.map((name) => ({ target: ids[name], message: labels[name] }))}
	/>
)}
```

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="error-summary/do-links" title="Ligue cada erro ao seu campo.">
		Um clique ou Enter leva a pessoa direto ao que precisa corrigir.
	</Guideline>
	<Guideline kind="dont" name="error-summary/dont-no-links" title="Um alerta que só diz que algo está errado.">
		A pessoa precisa caçar os campos vermelhos no formulário.
	</Guideline>
	<Guideline kind="do" name="error-summary/do-fix" title="Diga o campo e a correção.">
		"Número do cartão: digite os 16 dígitos" funciona fora de contexto, numa lista de links.
	</Guideline>
	<Guideline kind="dont" name="error-summary/dont-generic" title="A mesma mensagem vaga duas vezes.">
		Dois links chamados "Valor inválido" ficam iguais para quem usa leitor de tela.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="error-summary" type="ErrorSummaryProps"
	types={{ errors: "{ target: string; message: ReactNode }[]" }}
	describe={{
		title: "O título do resumo; diga quantos campos precisam de correção.",
		errors: "`target` é o id do controle inválido; o link dele leva o foco até lá.",
		label: "Tipo da mensagem por escrito (\"Atenção\", \"Erro\"). Alguns estilos mostram no lugar do ícone.",
		icon: "Substitui o ícone de perigo.",
	}}
>
	Os outros atributos de `div` são repassados, inclusive `ref` e `tabIndex`: use os dois para levar o foco ao resumo depois de um envio com erro.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio resumo.

<StylingHooks
	slots={["alert", "alert-title", "error-summary-list", "error-summary-link"]}
	prefix="alert"
	attributes={[
		{ attr: "data-slot", value: '"alert" · "alert-title" · "error-summary-list" · "error-summary-link"' },
		{ attr: "data-kind", value: '"error-summary"' },
		{ attr: "data-tone", value: '"danger"' },
	]}
>

```css
/* um erro por linha, só no checkout */
.checkout [data-slot="error-summary-list"] {
  flex-direction: column;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Percorre os links, na ordem do formulário." },
		{ key: "Enter", description: "Segue um link: o foco vai para o controle e ele rola até ficar visível." },
		{ key: "Shift + Tab", description: "Do controle, volta para os links do resumo." },
	]}
	notes={[
		"Ele usa role=\"alert\", então o leitor de tela anuncia assim que ele aparece.",
		"Leve o foco até ele depois de um envio com erro (ref + tabIndex={-1}), para quem usa teclado começar pela lista e não pelo botão de enviar.",
		"Cada link foca o próprio controle, não só o rótulo, então dá para digitar na hora.",
		"Mantenha também o FieldError em cada campo: o resumo é o mapa, o campo diz o que mudar.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Field", description: "Rótulo, descrição e erro de cada campo.", href: "/pt-br/docs/components/field" },
		{ title: "Alert", description: "Mensagens estáticas em quatro tons.", href: "/pt-br/docs/components/alert" },
		{ title: "Checkbox", description: "Termos e consentimento num formulário.", href: "/pt-br/docs/components/checkbox" },
	]}
/>


# Field (/pt-br/docs/components/field)

<ComponentMeta file="field" primitive="Base UI" pattern="HTML label + aria-describedby" />

<Playground
	name="field/playground"
	component="Field"
	controls={[
		{ prop: "invalid", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar.

<Import names="Field, FieldLabel, FieldDescription, FieldError" />

<Import names="Input, Textarea, Label, Fieldset, FieldsetLegend" />

## Anatomia [#anatomia]

Um `Field` é uma grade com até quatro partes. O rótulo aponta para o controle, e a descrição e o erro são lidos junto com ele.

<Anatomy
	keys={[
		{ label: '[data-slot="field"]', color: "#8be36f" },
		{ label: '[data-slot="field-label"] · [data-slot="field-description"] · [data-slot="field-error"]', color: "#ffcf7a" },
		{ label: 'controle: [data-slot="input"] · [data-slot="textarea"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">rótulo</span>
	<span className="a-label">input</span>
	<span className="a-part">descrição</span>
	<span className="a-part">erro</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="field/basic" compact />

<ExampleGrid>
	<Example name="field/textarea-count" title="Textarea com contador">
		Digite. Uma contagem ao vivo no `FieldDescription` é lida com o campo, então a pessoa ouve o limite antes de chegar nele.
	</Example>
	<Example name="field/required" title="Obrigatório">
		Digite uma letra, apague e saia. O `valueMissing` espera o campo ser alterado ou o formulário ser enviado, então um formulário novo nunca abre em vermelho.
	</Example>
	<Example name="field/invalid" title="Erro vindo do servidor">
		Quando o erro vem da sua API, use `invalid` e renderize `FieldError match`. O input recebe `aria-invalid` e a mensagem fica ligada a ele.
	</Example>
	<Example name="field/validate" title="Validação própria">
		Digite um espaço ou apague letras. O `validate` devolve a mensagem, e um `FieldError` vazio mostra ela enquanto a pessoa digita.
	</Example>
	<Example name="field/disabled" title="Desativado">
		O `disabled` no `Field` chega ao rótulo e ao controle. Diga o motivo na descrição, senão ninguém sabe quem pode mudar.
	</Example>
	<Example name="field/fieldset" title="Agrupado com fieldset">
		`Fieldset` e `FieldsetLegend` dão nome ao grupo, então "Nome" é anunciado como parte de "Contato de emergência".
	</Example>
	<Example name="field/label-checkbox" title="Rótulo fora de um field">
		Para checkbox ou switch, envolva com `Label`: a linha inteira fica clicável e dá nome ao controle.
	</Example>
	<Example name="field/input-types" title="Tipos de input">
		O `type` e o `autoComplete` certos abrem o teclado adequado no celular e deixam o navegador preencher o valor.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Campos vivem em formulários. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="field/context-signup" title="Formulário de cadastro" uses="Card · Field · Input · Checkbox · Button" />
	<Context name="field/context-address" title="Endereço de entrega" uses="Fieldset · Field · Input · NativeSelect" />
	<Context name="field/context-profile" title="Configurações do perfil" uses="Card · Field · Input · Textarea · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="field/do-visible-label" title="Rótulo visível acima do input.">
		Ele fica no lugar enquanto a pessoa digita, e o placeholder fica livre para mostrar um exemplo.
	</Guideline>
	<Guideline kind="dont" name="field/dont-placeholder-label" title="Placeholder no lugar do rótulo.">
		Ele some na primeira tecla, e o contraste baixo dificulta a leitura.
	</Guideline>
	<Guideline kind="do" name="field/do-specific-error" title="Diga como corrigir.">
		O erro diz a regra, então a pessoa sabe o que digitar.
	</Guideline>
	<Guideline kind="dont" name="field/dont-generic-error" title="Erro genérico.">
		"Entrada inválida." avisa que algo está errado, mas não o que mudar.
	</Guideline>
</Guidelines>

## Props [#props]

O `Field` recebe as props da raiz de field do Base UI. Estas são as mais usadas:


<Props
	file="field"
	type="FieldProps"
	include={["invalid", "disabled", "name", "validate", "validationMode", "validationDebounceTime", "dirty", "touched"]}
	types={{"invalid": "boolean", "disabled": "boolean", "name": "string", "validate": "(value, formValues) => string | string[] | null", "validationMode": "\"onSubmit\" | \"onBlur\" | \"onChange\"", "validationDebounceTime": "number", "dirty": "boolean", "touched": "boolean"}}
	describe={{"invalid": "Marca o campo como inválido, para erros que vêm do servidor ou de uma biblioteca de formulários.", "disabled": "Desativa o rótulo e o controle.", "name": "Identifica o campo no envio do formulário. Tem prioridade sobre o `name` do controle.", "validate": "Devolve a(s) mensagem(ns) de erro, ou nada quando o valor é válido. Pode ser assíncrona.", "validationMode": "Quando o `validate` e as regras nativas rodam.", "validationDebounceTime": "Milissegundos de espera entre chamadas do `validate` no modo `onChange`.", "dirty": "Controle esses estados a partir de uma biblioteca de formulários.", "touched": "Controle esses estados a partir de uma biblioteca de formulários."}}
/>

O `FieldError` recebe `match`: `true` para mostrar sempre, uma chave de `ValidityState` como `"valueMissing"` para mostrar só nesse erro, ou nada para mostrar sempre que o campo estiver inválido. O `Fieldset` recebe `disabled`. `Input` e `Textarea` recebem os atributos de `<input>` e `<textarea>`; o `Label`, os de `<label>`.

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio campo.

<StylingHooks
	slots={["field", "field-label", "field-description", "field-error", "input", "textarea", "label", "fieldset", "fieldset-legend"]}
	prefix="field"
	attributes={[
		{ attr: "data-slot", value: '"field" · "field-label" · "field-description" · "field-error" · "input" · "textarea"' },
		{ attr: "data-invalid", value: "presente no campo e no controle quando inválido" },
		{ attr: "data-valid", value: "presente depois de uma validação aprovada" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-touched · data-dirty", value: "presente depois de focado e deixado · depois de alterado" },
		{ attr: "data-filled · data-focused", value: "presente quando tem valor · enquanto focado" },
	]}
>

```css
/* formulário mais compacto, só neste diálogo */
.quick-add [data-slot="field"] {
  --cml-field-gap: 0.25rem;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco ao controle. Clicar no rótulo também foca." },
		{ key: "Shift + Tab", description: "Volta o foco ao controle anterior." },
	]}
	notes={[
		"O FieldLabel é um <label> de verdade ligado ao controle, então o texto dele é o nome acessível do controle.",
		"O FieldDescription e um FieldError visível entram no aria-describedby, então o leitor de tela lê os dois depois do nome.",
		"Um campo inválido marca aria-invalid no controle. A cor nunca é o único sinal: a mensagem de erro é sempre texto.",
		"O FieldsetLegend dá nome ao grupo, e a legenda é anunciada quando o foco entra nele.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Native select", description: "O select do navegador, com o visual do estilo.", href: "/pt-br/docs/components/native-select" },
		{ title: "Number field", description: "Campo numérico com botões de passo.", href: "/pt-br/docs/components/number-field" },
		{ title: "Input group", description: "Inputs com complementos, senha e busca.", href: "/pt-br/docs/components/input-group" },
	]}
/>


# Envio de arquivos (/pt-br/docs/components/file-upload)

<ComponentMeta file="file-upload" primitive="HTML" pattern="Native file input + role=group" />

<Playground
	name="file-upload/playground"
	component="Dropzone"
	controls={[
		{ prop: "multiple", default: true },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe a área e a lista.

<Import names="Dropzone, FileList, FileItem" />

## Anatomia [#anatomia]

O `Dropzone` é um grupo com nome e um botão que abre o seletor de arquivos. Cada `FileItem` de um `FileList` tem ícone, nome, barra de progresso ou linha de detalhes, e as suas ações.

<Anatomy
	keys={[
		{ label: '[data-slot="dropzone"] · [data-slot="file-list"] · [data-slot="file-item"]', color: "#8be36f" },
		{ label: '[data-slot="dropzone-icon"] · [data-slot="dropzone-title"] · [data-slot="dropzone-description"] · botão', color: "#ffcf7a" },
		{ label: '[data-slot="file-item-name"] · [data-slot="file-item-meta"] · progresso', color: "#7cc7ff" },
	]}
>
	<span className="a-part">ícone</span>
	<span className="a-part">título</span>
	<span className="a-part">descrição</span>
	<span className="a-part">Escolher arquivos</span>
	<span className="a-label">relatorio-3tri.pdf · 64%</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Nada sai do seu navegador: os envios são simulados com timers.

<Preview name="file-upload/basic" compact />

<ExampleGrid>
	<Example name="file-upload/rejections" title="Tipos e limite de tamanho" wide>
		Solte um PDF ou uma foto grande. O `accept` e o `maxSize` separam os arquivos, o `onFilesRejected` diz o motivo de cada um, e uma linha de status anuncia o resultado.
	</Example>
	<Example name="file-upload/progress" title="Progresso, cancelar e remover" wide>
		Adicione um arquivo. Guarde o estado do envio você mesmo e passe para `status`, `progress` e `meta`; a barra leva o nome do arquivo.
	</Example>
	<Example name="file-upload/statuses" title="Todos os status">
		O `status` comanda a linha: `idle` antes do envio, `uploading` com barra, `done` com check, `error` com a mensagem.
	</Example>
	<Example name="file-upload/retry" title="Tentar de novo após erro">
		Clique em tentar de novo. A linha com falha guarda o arquivo e oferece o próximo passo, então ninguém precisa buscar o arquivo na pasta outra vez.
	</Example>
	<Example name="file-upload/single" title="Uma imagem">
		Com `multiple={false}` só o primeiro arquivo é entregue, e escolher de novo substitui; a linha mostra nome, tipo e tamanho.
	</Example>
	<Example name="file-upload/indeterminate" title="Progresso desconhecido">
		Quando o servidor não consegue medir (antivírus, conversão), passe `progress={null}` e diga no `meta` o que está acontecendo.
	</Example>
	<Example name="file-upload/disabled" title="Desativado, com motivo">
		O `disabled` ignora arquivos soltos e desativa o botão. Use a descrição para dizer o motivo e o que fazer.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Enviar arquivos é parte de uma tarefa. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="file-upload/context-ticket" title="Anexos de um chamado" uses="Card · Field · Input · Textarea · Dropzone · FileList · IconButton" />
	<Context name="file-upload/context-avatar" title="Foto do perfil" uses="Card · Avatar · Dropzone · FileItem · Button" />
	<Context name="file-upload/context-import" title="Importar contatos de CSV" uses="Card · Dropzone · FileItem · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="file-upload/do-limits" title="Diga os tipos e o limite.">
		A pessoa confere antes de arrastar, e nenhum arquivo é recusado de surpresa.
	</Guideline>
	<Guideline kind="dont" name="file-upload/dont-no-limits" title="Área de soltar sem nada.">
		As regras existem do mesmo jeito; a pessoa só descobre quando um arquivo falha.
	</Guideline>
	<Guideline kind="do" name="file-upload/do-specific-error" title="Diga como corrigir.">
		O erro diz o limite e a saída, bem no arquivo.
	</Guideline>
	<Guideline kind="dont" name="file-upload/dont-generic-error" title="Erro genérico.">
		"Falha no envio." faz a pessoa tentar o mesmo arquivo de novo.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="file-upload"
	type="DropzoneProps"
	describe={{
		title: "O título da área; também dá nome ao grupo.",
		description: "Tipos aceitos e tamanho, em palavras (\"PNG, JPG ou PDF até 10 MB\").",
		buttonLabel: "Texto do botão que abre o seletor de arquivos.",
		icon: "Substitui o ícone de envio.",
		accept: "Mesma sintaxe do `<input accept>`: extensões, tipos MIME, `image/*`.",
		multiple: "Aceita vários arquivos de uma vez; com false, só o primeiro é entregue.",
		maxSize: "Maior arquivo aceito, em bytes.",
		disabled: "Ignora arquivos soltos e desativa o botão.",
		onFilesAccepted: "Recebe os arquivos que passam no `accept` e no `maxSize`.",
		onFilesRejected: "Recebe os arquivos recusados, cada um com `reason: \"type\" | \"size\"`.",
	}}
>
	Estas são as props do `Dropzone`; os `children` aparecem entre a descrição e o botão. Uma recusa é `{ file, reason: "type" | "size" }`. O `FileList` recebe os atributos de `<ul>`; dê um `aria-label` a ele.
</Props>

O `FileItem` mostra um arquivo:

<Props
	file="file-upload"
	type="FileItemProps"
	describe={{
		name: "O nome do arquivo. Também dá nome à barra de progresso.",
		meta: "Tamanho, texto de progresso ou status (\"64% · 2,4 de 3,8 MB\", \"Enviado · 1,2 MB\").",
		status: "uploading mostra a barra; done adiciona um check; error mostra o `error`.",
		progress: "De 0 a 100 durante o envio; `null` é indeterminado.",
		error: "Mensagem mostrada com `status=\"error\"`.",
		icon: "Substitui o ícone de arquivo (o de perigo, no erro).",
		actions: "Botões no fim da linha (cancelar, remover, tentar de novo). Dê nome a eles com o arquivo.",
	}}
>
	Outros atributos de `<li>` também são aceitos.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria área.

<StylingHooks
	slots={["dropzone", "dropzone-icon", "dropzone-title", "dropzone-description", "file-list", "file-item", "file-item-icon", "file-item-name", "file-item-meta", "file-item-error"]}
	prefix="dropzone"
	attributes={[
		{ attr: "data-slot", value: '"dropzone" · "dropzone-icon" · "dropzone-title" · "dropzone-description" · "file-list" · "file-item" · "file-item-icon" · "file-item-body" · "file-item-header" · "file-item-name" · "file-item-meta" · "file-item-error"' },
		{ attr: "data-dragging", value: "no dropzone enquanto arquivos são arrastados sobre ele" },
		{ attr: "data-disabled", value: "no dropzone quando desativado" },
		{ attr: "data-status", value: '"idle" · "uploading" · "done" · "error", em cada item' },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco ao botão dentro da área." },
		{ key: "Enter / Espaço", description: "Abre o seletor de arquivos do sistema." },
		{ key: "Tab (na lista)", description: "Passa pelas ações de cada arquivo." },
	]}
	notes={[
		"Arrastar é um atalho, não o único caminho: a área sempre tem um botão de verdade e um <input type=\"file\"> nativo.",
		"A área é um grupo nomeado pelo título e descrito pela descrição, então os tipos aceitos são lidos junto.",
		"Cada barra de progresso leva o nome do arquivo. Dê o nome do arquivo aos botões também: \"Remover capa.png\", não \"Remover\".",
		"Erros são texto abaixo do arquivo, não só uma borda vermelha; anuncie o que entrou ou foi recusado numa linha com role=\"status\".",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Progress", description: "Barra para qualquer tarefa com progresso conhecido.", href: "/pt-br/docs/components/progress" },
		{ title: "Field", description: "Rótulo, descrição e erro para qualquer controle.", href: "/pt-br/docs/components/field" },
		{ title: "Error summary", description: "Liste todos os erros no topo de um formulário longo.", href: "/pt-br/docs/components/error-summary" },
	]}
/>


# Grid (/pt-br/docs/components/grid)

<ComponentMeta file="layout" pattern="CSS grid" />

<Playground
	name="grid/playground"
	component="Grid"
	controls={[
		{ prop: "minChildWidth", options: ["8rem", "12rem", "16rem"], default: "12rem" },
		{ prop: "align", options: ["stretch", "start", "center", "end"], default: "stretch" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. Ele não tem estado, então renderiza no servidor.

<Import names="Grid" />

## Anatomia [#anatomia]

Um elemento grid com `data-slot="grid"`. Os filhos são as células; qualquer filho pode ocupar mais espaço com `gridColumn`, como o card aqui, que pega a linha inteira.

<Anatomy
	tree={{
		slot: "grid",
		tag: "div",
		note: 'minChildWidth="9rem"',
		row: true,
		children: [
			{ slot: "stat", tag: "article", note: "uma célula" },
			{ slot: "stat", tag: "article" },
			{ slot: "stat", tag: "article" },
			{ slot: "card", tag: "div", note: 'gridColumn: "1 / -1"' },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Estreite a janela para ver o layout se reorganizar.

<Preview name="grid/basic" compact />

<ExampleGrid>
	<Example name="grid/auto-fit" title="Cards que cabem na largura" wide>
		O `minChildWidth` coloca quantas colunas couberem, cada uma com pelo menos essa largura. Sem breakpoints: quatro cards por linha no desktop, um no celular.
	</Example>
	<Example name="grid/columns" title="Qualquer modelo de colunas">
		Passe uma string em `columns` para tudo que o CSS grid aceita. `"auto 1fr"` ajusta os rótulos ao mais longo e dá o resto para os valores.
	</Example>
	<Example name="grid/span" title="Um item na linha inteira">
		Não existe prop de span: defina `gridColumn` no filho. `"1 / -1"` ocupa a linha toda, quantas colunas couberem, então nunca quebra o layout.
	</Example>
	<Example name="grid/form-two-columns" title="Duas colunas, uma no celular" wide>
		Ponha campos curtos lado a lado e dê a linha inteira aos longos. Com `minChildWidth`, o formulário volta para uma coluna em telas estreitas.
	</Example>
	<Example name="grid/align-toggle" title="Alturas iguais">
		Desligue o interruptor. O `align="stretch"` padrão deixa cada card da linha tão alto quanto o maior, e os botões ficam alinhados.
	</Example>
	<Example name="grid/gallery" title="Galeria como lista">
		Renderize `as="ul"` para o leitor de tela anunciar "6 itens". Mantenha o DOM na ordem em que as pessoas veem e evite `order` ou empacotamento denso, que embaralham.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="grid/context-dashboard" title="Dashboard de vendas" uses="Grid · Stat · Card · Meter · Badge" />
	<Context name="grid/context-address" title="Formulário de endereço" uses="Card · Grid · Field · Input · Button" />
	<Context name="grid/context-pricing" title="Planos e preços" uses="Grid · Card · Badge · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="grid/do-equal" title="Cards da mesma linha com a mesma altura.">
		Com o stretch padrão e a ação embaixo, os botões se alinham e a linha é lida como um conjunto.
	</Guideline>
	<Guideline kind="dont" name="grid/dont-ragged" title="Cards que terminam em alturas diferentes.">
		`align="start"` deixa a borda de baixo irregular, e o olho precisa caçar cada botão.
	</Guideline>
	<Guideline kind="do" name="grid/do-pair" title="Junte campos que andam juntos.">
		O número do cartão ocupa a linha; validade e CVV ficam lado a lado porque a pessoa preenche os dois juntos.
	</Guideline>
	<Guideline kind="dont" name="grid/dont-pair" title="Duas colunas só para ocupar espaço.">
		Campos sem relação lado a lado fazem a pessoa ziguezaguear, e a ordem de leitura não é a ordem de digitação.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="GridProps"
	types={{ as: '"div" | "section" | "ul" | "form" | …', align: "CSS align-items" }}
	describe={{
		as: "Elemento renderizado, para a semântica certa (por exemplo `as=\"ul\"`).",
		columns: "Um número de colunas iguais, ou qualquer valor de `grid-template-columns`.",
		minChildWidth: "Alternativa responsiva a `columns`: quantas colunas couberem, cada uma com pelo menos essa largura.",
		gap: "Espaço entre linhas e colunas, em múltiplos de `--cml-space`: `gap={4}` = 1rem.",
		align: "Alinhamento vertical dos itens na linha (`align-items`).",
	}}
>
	O `as` aceita as mesmas tags do [Box](/pt-br/docs/components/box). Quando os dois estão definidos, `minChildWidth` vence `columns`. Os filhos se posicionam com `gridColumn` e `gridRow`.
</Props>

## Styling hooks [#styling-hooks]

Cada prop vira uma propriedade customizada no elemento. Deixe uma prop de fora e o seu CSS pode definir essa propriedade.

<StylingHooks slots={["grid"]} prefix="grid" attributes={[{ attr: "data-slot", value: '"grid"' }]}>

```css
/* layout com barra lateral a partir de 48rem, uma coluna abaixo disso */
@media (min-width: 48rem) {
  .account[data-slot="grid"] {
    --cml-grid-columns: 16rem minmax(0, 1fr);
  }
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O Grid não renderiza nenhum elemento interativo. O Tab passa pelos filhos na ordem do DOM, linha por linha." }]}
	notes={[
		"Grid é layout, não grade de dados: não tem papel grid nem navegação por setas. Para dados que a pessoa compara entre linhas, use uma Table.",
		"Mantenha a ordem visual igual à do DOM. order, grid-auto-flow: dense e posicionamento explícito movem células sem mover o foco nem o que o leitor de tela lê.",
		"Renderize uma coleção de cards ou fotos com as=\"ul\" para o tamanho ser anunciado, e dê um nome com aria-label quando não houver título visível.",
		"Não use a posição para passar significado (\"o card da direita\"): com minChildWidth, a coluna da direita desce no celular.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Stack", description: "Uma coluna ou uma linha, quando as células não precisam se alinhar.", href: "/pt-br/docs/components/stack" },
		{ title: "Card", description: "A superfície de que a maioria dos grids é feita.", href: "/pt-br/docs/components/card" },
		{ title: "Table", description: "Linhas e colunas de dados, com cabeçalhos navegáveis.", href: "/pt-br/docs/components/table" },
	]}
/>


# HoverCard (/pt-br/docs/components/hover-card)

<ComponentMeta file="hover-card" primitive="Base UI" pattern="Link + prévia no hover e no foco" />

<Playground
	name="hover-card/playground"
	component="HoverCardContent"
	controls={[
		{ prop: "align", options: ["start", "center", "end"], default: "start" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="HoverCard, HoverCardTrigger, HoverCardContent, HoverCardArrow" />

## Anatomia [#anatomia]

O gatilho é um link (`hover-card-trigger`, um `<a>`). O card é renderizado num portal, dentro de um escopo que mantém o estilo, o modo e a cor da página em volta do link.

<Anatomy
	tree={{
		slot: "hover-card-positioner",
		tag: "div",
		note: "num portal",
		children: [
			{
				slot: "hover-card-popup",
				tag: "div",
				note: "sem role",
				children: [{ slot: "hover-card-arrow", tag: "div", note: "opcional" }],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Passe o mouse num link ou chegue nele com Tab: o card também abre no foco.

Qual usar? O **Tooltip** dá nome a um controle em poucas palavras. O **HoverCard** mostra uma prévia de para onde o link vai, como um extra para quem usa mouse e teclado. O **Toggletip** explica um termo com um clique, então é o que funciona no toque e o que o leitor de tela lê.

<Preview name="hover-card/basic" compact />

<ExampleGrid>
	<Example name="hover-card/author-byline" title="Autor de um artigo">
		Quem lê vê quem escreveu sem sair da página. Clicar no nome continua abrindo o perfil, que é o único caminho no celular.
	</Example>
	<Example name="hover-card/link-preview" title="Prévia de link">
		Mostre o título e um resumo de uma linha da página, para a pessoa saber se vale o clique. O texto do link já diz para onde ele vai.
	</Example>
	<Example name="hover-card/a11y-bonus" title="Só um extra">
		O leitor de tela não lê o card, e a tela de toque nunca abre ele. Coloque a informação principal no texto do link ("sua gerente de conta"), não só no card.
	</Example>
	<Example name="hover-card/delays" title="Espera maior numa lista">
		Numa lista de nomes, `delay={1000}` evita que os cards pisquem quando o mouse só atravessa a lista. O padrão é 600 ms para abrir e 300 ms para fechar.
	</Example>
	<Example name="hover-card/lazy-load" title="Carregar ao abrir">
		Passe o mouse. Busque os detalhes no `onOpenChange`, não para cada link da página, e mostre um `Skeleton` com `aria-busy` enquanto carregam.
	</Example>
	<Example name="hover-card/alignment" title="Alinhamento" wide>
		O `align` alinha o card com o início, o centro ou o fim do link. O `side` escolhe o lado em que ele abre; ele troca de lado quando não há espaço.
	</Example>
	<Example name="hover-card/with-arrow" title="Com seta">
		Use o `HoverCardArrow` quando houver vários links próximos, para ficar claro a qual deles o card pertence.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O hover card dá uma espiada rápida em links que a pessoa já tem. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="hover-card/context-comments" title="Conversa de comentários" uses="Card · Avatar · Link · HoverCard" />
	<Context name="hover-card/context-team-table" title="Responsáveis pelas tarefas" uses="Table · Badge · Avatar · HoverCard" />
	<Context name="hover-card/context-article" title="Artigo de ajuda" uses="Card · Link · HoverCard" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="hover-card/do-real-link" title="Um link que funciona sozinho.">
		A página do perfil tem tudo o que o card mostra, então um clique, um toque ou o Enter levam a pessoa até lá.
	</Guideline>
	<Guideline kind="dont" name="hover-card/dont-dead-trigger" title="Um gatilho que não leva a lugar nenhum.">
		Sem `href` ele não recebe foco nem toque, então quem usa teclado ou celular nunca vê o card.
	</Guideline>
	<Guideline kind="do" name="hover-card/do-summary" title="Um resumo curto, só para ler.">
		Três ou quatro informações que a pessoa entende de relance e segue em frente.
	</Guideline>
	<Guideline kind="dont" name="hover-card/dont-actions" title="Botões dentro do card.">
		Ele fecha quando o mouse escapa, e quem usa teclado não chega até eles. Coloque as ações na página do perfil, ou use um popover.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="hover-card"
	type="HoverCardContentProps"
	describe={{
		sideOffset: "Distância em pixels entre o gatilho e o card.",
		align: "Alinhamento do card ao longo da borda do gatilho.",
		side: "De que lado do gatilho o card abre. Ele troca de lado quando não há espaço.",
	}}
>
	O `HoverCardTrigger` recebe `delay` (ms antes de abrir, padrão 600), `closeDelay` (ms antes de fechar, padrão 300) e `render` para usar um `Link`. O `HoverCard` aceita `open`, `onOpenChange` e `defaultOpen`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio card.

<StylingHooks
	slots={["hover-card-trigger", "hover-card-positioner", "hover-card-popup", "hover-card-arrow"]}
	prefix="hover-card"
	attributes={[
		{ attr: "data-popup-open", value: "no gatilho enquanto o card está aberto" },
		{ attr: "data-side", value: "bottom · top" },
		{ attr: "data-align", value: "start · center · end" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Ao focar o link, o card abre depois da mesma espera do hover. O foco fica no link; o próximo Tab segue adiante e fecha o card." },
		{ key: "Escape", description: "Fecha o card. O foco continua no link." },
		{ key: "Enter", description: "Abre o link, como em qualquer link." },
	]}
	notes={[
		"O leitor de tela não ouve o card: o popup não tem role e nada liga ele ao gatilho. O texto do link e a página que ele abre precisam ter tudo.",
		"Tela de toque não tem hover: um toque abre o link e o card nunca aparece.",
		"O card nunca entra na ordem de tabulação, então quem usa teclado não alcança nada dentro dele. Nunca coloque links ou botões nele.",
		"Dá para levar o mouse do link até o card sem ele fechar, como pede o WCAG 1.4.13.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Tooltip", description: "Um rótulo curto para botão de ícone, no hover ou no foco.", href: "/pt-br/docs/components/tooltip" },
		{ title: "Toggletip", description: "Uma explicação que abre com clique, então funciona também no toque.", href: "/pt-br/docs/components/toggletip" },
		{ title: "Avatar", description: "A foto ou as iniciais no topo de um card de perfil.", href: "/pt-br/docs/components/avatar" },
	]}
/>


# Image (/pt-br/docs/components/image)

<ComponentMeta file="image" pattern="HTML figure + img" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. Ele é um componente de cliente, porque observa o evento de erro da imagem.

<Import names="Image" />

## Anatomia [#anatomia]

Uma `<figure>` enquanto a imagem funciona, e uma `<div>` no lugar dela quando falha. `style` e `className` vão para o elemento de fora; todas as outras props vão para a `<img>`.

<Anatomy
	tree={{
		slot: "image",
		tag: "figure",
		children: [
			{ slot: "image-skeleton", tag: "span", note: "com loadingState" },
			{ slot: "image-img", tag: "img" },
			{ slot: "image-caption", tag: "figcaption", row: true, children: [{ slot: "image-caption-meta", tag: "span", note: "captionMeta" }] },
		],
	}}
/>

Quando falha, o substituto padrão toma o lugar da figura inteira:

<Anatomy
	tree={{
		slot: "image-fallback",
		tag: "div",
		note: "role=img",
		row: true,
		children: [
			{ slot: "icon", tag: "svg" },
			{ slot: "image-fallback-body", tag: "div", children: [{ slot: "image-fallback-title", tag: "p" }, { slot: "image-fallback-subtitle", tag: "p" }] },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="image/basic" compact />

<ExampleGrid>
	<Example name="image/with-caption" title="Legenda e crédito">
		`caption` vira uma `<figcaption>` que o leitor de tela liga à imagem; coloque o crédito ou o tamanho do arquivo em `captionMeta`.
	</Example>
	<Example name="image/aspect-ratio" title="Tamanho e corte">
		`width` e `height` reservam o espaço antes de o arquivo chegar; um `aspectRatio` no `style` corta a mesma foto em 16:9 ou 1:1 com `object-fit: cover`.
	</Example>
	<Example name="image/loading-state" title="Skeleton de carregamento">
		Ligue `loadingState` enquanto espera o arquivo e desligue no `onLoad`; o componente não desliga sozinho.
	</Example>
	<Example name="image/fallback-default" title="Quando o arquivo falha">
		O substituto padrão mantém a moldura e mostra o nome do arquivo. Ele recebe `role="img"` e o `alt` como nome, então o leitor de tela ainda diz o que deveria estar ali.
	</Example>
	<Example name="image/custom-fallback" title="Substituto com nova tentativa">
		Clique em Tentar de novo. Um `fallback` próprio pode ter controles, e recebe `role="group"` para eles continuarem acessíveis; depois da nova tentativa, o foco fica na caixa e uma mensagem de status confirma.
	</Example>
	<Example name="image/interactive-toggle" title="Os três estados">
		Alterne entre carregada, carregando e com erro. O estado de erro só é lido na montagem, então troque a `key` quando precisar reiniciá-lo.
	</Example>
	<Example name="image/decorative" title="Imagem decorativa">
		Use `alt=""` só quando o texto ao lado já diz tudo. O `alt` é vazio por padrão, então uma foto sem `alt` também some para o leitor de tela.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Imagens costumam ficar no topo de um card ou numa grade de miniaturas. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="image/context-blog" title="Card de artigo" uses="Card · Image · Badge" wide />
	<Context name="image/context-product" title="Card de produto" uses="Card · Image · Button" wide />
	<Context name="image/context-gallery" title="Biblioteca de mídia" uses="Card · Image" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="image/do-descriptive-alt" title="Descreva o que a imagem mostra.">
		Diga o que importa neste contexto, numa frase, como você contaria para alguém ao telefone.
	</Guideline>
	<Guideline kind="dont" name="image/dont-redundant-alt" title="Nome do arquivo como alt.">
		O leitor de tela já diz "imagem", e "imagem.png" não conta nada sobre o conteúdo.
	</Guideline>
	<Guideline kind="do" name="image/do-same-ratio" title="Uma proporção por grade.">
		Dê a todas as miniaturas o mesmo `aspectRatio`, para as linhas se alinharem seja qual for o formato de cada foto.
	</Guideline>
	<Guideline kind="dont" name="image/dont-mixed-ratios" title="Cada imagem numa proporção.">
		A linha fica torta, e o olho segue os buracos em vez das fotos.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="image"
	type="ImageProps"
	include={["src", "alt", "width", "height", "onLoad", "onError"]}
	describe={{
		src: "O arquivo a mostrar. Sem ele, o substituto aparece na hora.",
		alt: "O que a imagem mostra. Também dá nome ao substituto. O padrão é `\"\"`, que marca a imagem como decorativa.",
		width: "Largura do arquivo. Com `height`, o navegador reserva o espaço antes de carregar.",
		height: "Altura do arquivo. Com `width`, o navegador reserva o espaço antes de carregar.",
		onLoad: "Roda quando o arquivo carrega. Desligue o `loadingState` aqui.",
		onError: "Roda quando o arquivo falha; em seguida o substituto toma o lugar dele.",
		fallback: "Substitui o substituto padrão quando a imagem falha, por exemplo com um botão de nova tentativa. Fica dentro de um `role=\"group\"` com o nome do `alt`.",
		fallbackTitle: "Título do substituto padrão.",
		fallbackSubtitle: "Segunda linha do substituto padrão, como o nome do arquivo. Sem ela, mostra o `src`.",
		caption: "Texto abaixo da imagem, renderizado como `<figcaption>`.",
		captionMeta: "Texto secundário no fim da linha da legenda, como um crédito ou o tamanho do arquivo.",
		defaultError: "Começa no estado de erro. Só é lido na montagem: troque a `key` para reiniciar.",
		loadingState: "Cobre a imagem com um skeleton. Você controla: desligue no `onLoad`.",
	}}
>
	`style` e `className` vão para a `<figure>` de fora ou para o substituto; um `aspectRatio` ou uma altura ali corta a imagem. Todos os outros atributos de `<img>`, como `loading="lazy"` ou `srcSet`, vão para a imagem.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os slots ou defina os tokens num elemento pai, num estilo ou na própria imagem.

<StylingHooks
	slots={["image", "image-img", "image-skeleton", "image-caption", "image-caption-meta", "image-fallback", "image-fallback-body", "image-fallback-title", "image-fallback-subtitle"]}
	prefix="image"
	attributes={[{ attr: "data-loading", value: "em image, enquanto loadingState está ligado" }]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "A imagem não é parada de Tab. O Tab só chega aos controles dentro de um substituto próprio, como Tentar de novo." }]}
	notes={[
		"Carregada, ela é uma <img> dentro de uma <figure>; a legenda é uma <figcaption>.",
		"Dê alt a toda imagem que tem significado. Sem ele, o alt fica \"\" e o leitor de tela pula a imagem.",
		"O substituto padrão é role=\"img\" com o nome do alt, então uma foto quebrada continua com nome. Sem alt, o nome é \"Unavailable image\", em inglês.",
		"O skeleton fica em aria-hidden e a figura não tem estado de ocupado, então uma imagem lenta não é anunciada.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Avatar", description: "Uma foto pequena e redonda de uma pessoa, com iniciais quando falha.", href: "/pt-br/docs/components/avatar" },
		{ title: "Carousel", description: "Várias imagens ou slides num só lugar, um de cada vez.", href: "/pt-br/docs/components/carousel" },
		{ title: "Skeleton", description: "Marcadores para textos e blocos enquanto a página carrega.", href: "/pt-br/docs/components/skeleton" },
	]}
/>


# Input group (/pt-br/docs/components/input-group)

<ComponentMeta file="input-group" primitive="Base UI" pattern="HTML input + button" />

<Playground
	name="input-group/playground"
	component="PasswordInput"
	controls={[
		{ prop: "size", options: ["sm", "md"], default: "md" },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Coloque dentro de um `Field` para dar um rótulo.

<Import names="InputGroup, InputAddon, PasswordInput, SearchInput, Input" />

## Anatomia [#anatomia]

O grupo desenha uma borda e um anel de foco só. O input de dentro perde os dele, e complementos, ícones e botões ficam nas pontas.

<Anatomy
	keys={[
		{ label: '[data-slot="input-group"]', color: "#8be36f" },
		{ label: '[data-slot="input-addon"] · [data-slot="icon"] · [data-slot="input-group-button"]', color: "#ffcf7a" },
		{ label: '[data-slot="input-group-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">https://</span>
	<span className="a-label">input</span>
	<span className="a-part">botão</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="input-group/basic" compact />

<ExampleGrid>
	<Example name="input-group/password-rules" title="Senha com regras ao vivo">
		Digite uma senha. Com o texto visível, a pessoa pega o erro de digitação antes que uma regra como "um número" recuse a senha duas vezes.
	</Example>
	<Example name="input-group/search-filter" title="Busca com limpar">
		Digite e depois aperte o × ou Esc. Limpar dispara o `onChange` e devolve o foco ao input, e a contagem é anunciada com `aria-live`.
	</Example>
	<Example name="input-group/search-shortcut" title="Atalho de teclado">
		Aperte / fora de um campo. O `shortcut` só desenha a dica com o campo vazio: ligue a tecla você mesmo e declare com `aria-keyshortcuts`.
	</Example>
	<Example name="input-group/url-prefix" title="URL com prefixo">
		A parte fixa fica num `InputAddon`, então a pessoa digita só o domínio e o valor salvo não tem "https://" para limpar.
	</Example>
	<Example name="input-group/currency" title="Moeda e período">
		A moeda antes e o período depois dizem o que o número significa, então o rótulo pode ser curto.
	</Example>
	<Example name="input-group/copy-link" title="Botão de copiar">
		Clique em Copiar. Um `Button` dentro do grupo divide a borda, e o novo texto é anunciado, então a pessoa sabe que funcionou.
	</Example>
	<Example name="input-group/leading-icon" title="Ícone à esquerda">
		O ícone ajuda a pessoa a percorrer um formulário longo, mas é decoração: marque `aria-hidden` e deixe o rótulo dar o nome.
	</Example>
	<Example name="input-group/invalid" title="Inválido">
		Num `Field` inválido o grupo inteiro fica vermelho, complemento incluído, e o erro diz o que tentar no lugar.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="input-group/context-sign-in" title="Cartão de login" uses="Card · Field · InputGroup · PasswordInput · Button" />
	<Context name="input-group/context-header" title="Busca no cabeçalho do app" uses="SearchInput · Button" />
	<Context name="input-group/context-shop" title="Configurações da loja" uses="Card · Field · InputGroup · InputAddon · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="input-group/do-addon" title="Parte fixa num complemento.">
		A pessoa digita só o que muda e não tem como errar o prefixo.
	</Guideline>
	<Guideline kind="dont" name="input-group/dont-type-prefix" title="Obrigar a digitar a parte fixa.">
		Metade esquece o "https://", a outra metade digita duas vezes.
	</Guideline>
	<Guideline kind="do" name="input-group/do-reveal" title="Um campo de senha com botão de mostrar.">
		A pessoa confere o que digitou olhando.
	</Guideline>
	<Guideline kind="dont" name="input-group/dont-confirm" title="Um segundo campo para confirmar a senha.">
		Dobra a digitação e ainda não mostra um erro repetido nos dois campos.
	</Guideline>
</Guidelines>

## Props [#props]

`PasswordInput` e `SearchInput` recebem todas as props do `Input`, mais as próprias:

<Props
	file="input-group"
	type="PasswordInputProps"
	include={["disabled"]}
	describe={{ size: "Altura do campo. `sm` para barras de ferramentas e tabelas densas.", showLabel: "Nome acessível do botão de visibilidade enquanto a senha está oculta (traduzível).", hideLabel: "Nome acessível do botão de visibilidade enquanto a senha está visível (traduzível).", disabled: "Desativa o input e o botão de mostrar." }}
/>

<Props
	file="input-group"
	type="SearchInputProps"
	describe={{ size: "Altura do campo. `sm` para barras de ferramentas e tabelas densas.", clearLabel: "Nome acessível do botão de limpar (traduzível).", shortcut: "Dica de teclado mostrada com o campo vazio, como \"Ctrl K\". Use junto com `aria-keyshortcuts`." }}
>
	O `InputGroup` recebe `size` e os atributos de uma `<div>`; o `InputAddon`, os de um `<span>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio grupo.

<StylingHooks
	slots={["input-group", "input-group-input", "input-addon", "input-group-button"]}
	prefix="input-addon"
	attributes={[
		{ attr: "data-slot", value: '"input-group" · "input-group-input" · "input-addon" · "input-group-button"' },
		{ attr: "data-size", value: '"sm" · "md" no grupo' },
		{ attr: "data-pressed", value: "no botão de senha enquanto o texto está visível" },
		{ attr: "data-invalid", value: "no input quando o Field é inválido; o grupo fica vermelho junto" },
	]}
>

```css
/* complementos sem fundo, só no checkout */
.checkout [data-slot="input-group"] {
  --cml-input-addon-bg: transparent;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco ao input e depois ao botão de mostrar/ocultar ou de limpar." },
		{ key: "Enter · Space", description: "No botão de mostrar/ocultar: mostra ou oculta a senha. No botão de limpar: limpa a busca." },
		{ key: "Escape", description: "Num SearchInput: limpa o texto (comportamento de busca do navegador)." },
	]}
	notes={[
		"O nome do botão de senha diz o que o clique faz (\"Mostrar senha\" / \"Ocultar senha\"), então ele não usa aria-pressed. O foco fica nele, e a pessoa pode alternar de volta.",
		"Limpar a busca devolve o foco ao input, então a pessoa já digita a próxima.",
		"showLabel, hideLabel e clearLabel vêm em inglês por padrão. Passe os traduzidos.",
		"O texto do complemento é lido com o input, a não ser que você marque aria-hidden. Esconda decoração como \"https://\" e deixe unidades como \"/mês\" legíveis.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Field", description: "Rótulo, descrição e erro de um controle.", href: "/pt-br/docs/components/field" },
		{ title: "Combobox", description: "Um campo de busca que sugere valores.", href: "/pt-br/docs/components/combobox" },
		{ title: "Number field", description: "Campo numérico com botões de passo.", href: "/pt-br/docs/components/number-field" },
	]}
/>


# Kbd (/pt-br/docs/components/kbd)

<ComponentMeta file="display" pattern="HTML kbd" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Kbd" />

## Anatomia [#anatomia]

Um `<kbd>` para cada tecla. Uma combinação são vários `Kbd` lado a lado, não um só.

<Anatomy tree={{ slot: "kbd", tag: "kbd", note: "uma tecla" }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="kbd/basic" compact />

<ExampleGrid>
	<Example name="kbd/combinations" title="Combinações" wide>
		Use um `Kbd` por tecla. Assim a pessoa vê de relance quantas teclas são e quais.
	</Example>
	<Example name="kbd/symbols" title="Símbolos do Mac" wide>
		O leitor de tela não sabe ler ⌘ nem ⌥. Esconda o símbolo com `aria-hidden` e coloque o nome da tecla com `VisuallyHidden`.
	</Example>
	<Example name="kbd/platforms" title="Windows e Mac">
		A mesma ação usa Ctrl no Windows e ⌘ no Mac. Se você não sabe o sistema da pessoa, mostre os dois, cada um com o nome.
	</Example>
	<Example name="kbd/sequence" title="Uma tecla, depois outra">
		Quando as teclas são apertadas uma de cada vez, escreva "depois" entre elas. Sem isso, a pessoa aperta as duas juntas.
	</Example>
	<Example name="kbd/in-menu" title="Num menu">
		Abra o menu. O atalho fica no fim de cada item, e a pessoa aprende enquanto clica. O `aria-keyshortcuts` conta as teclas para o leitor de tela.
	</Example>
	<Example name="kbd/with-tooltip" title="Numa dica">
		Passe o mouse ou foque o botão. A dica ensina o atalho bem na hora em que a pessoa usa a ação.
	</Example>
	<Example name="kbd/interactive-recorder" title="Trocar um atalho">
		Clique em "Trocar atalho" e aperte as novas teclas. Tab e Esc nunca são gravados: o Tab segue em frente e o Esc cancela. Quem usa teclado sempre consegue sair.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O atalho aparece onde a pessoa age. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="kbd/context-shortcuts-dialog" title="Lista de atalhos" uses="Card · Kbd" />
	<Context name="kbd/context-search-input" title="Busca com atalho" uses="SearchInput · Kbd" />
	<Context name="kbd/context-editor-footer" title="Barra de status do editor" uses="Kbd" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="kbd/do-individual-keys" title="Um Kbd para cada tecla.">
		Teclas separadas mostram quantas são, e cada uma parece mesmo uma tecla.
	</Guideline>
	<Guideline kind="dont" name="kbd/dont-merged-keys" title="O atalho inteiro numa tecla só.">
		"Ctrl + S" numa caixa só parece uma tecla com um nome estranho.
	</Guideline>
	<Guideline kind="do" name="kbd/do-aria-keys" title="Dê nome aos símbolos.">
		O leitor de tela pula o ⌘ ou lê um nome que ninguém entende. Coloque "Command" como texto escondido.
	</Guideline>
	<Guideline kind="dont" name="kbd/dont-prose-text" title="Atalho perdido no meio da frase.">
		"Aperte ctrl e k" se mistura com o texto, e quem lê por cima não vê.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="display" type="KbdProps" describe={{}}>
	O `Kbd` não tem props próprias. Ele renderiza um `<kbd>` e aceita os atributos dele, como `className` e `style`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use o slot ou defina os tokens num elemento pai, num estilo ou na própria tecla.

<StylingHooks slots={["kbd"]} />

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O Kbd só mostra as teclas e nunca recebe foco. Quem recebe é o controle a que ele pertence." }]}
	notes={[
		"O Kbd não cria o atalho. Você escuta as teclas no seu código e coloca aria-keyshortcuts no controle que ele aciona, como \"Control+S\".",
		"Símbolos como ⌘, ⌥ e ⇧ precisam de um nome em texto. Esconda o símbolo com aria-hidden e coloque o nome com VisuallyHidden. Muitos leitores de tela ignoram o aria-label num <kbd>.",
		"Nunca tome para você o Tab, o Shift+Tab ou o Esc. A pessoa precisa deles para andar pela página e para sair (WCAG 2.1.2).",
		"Atalho de uma tecla só, como / ou ?, precisa poder ser desligado, ou só funcionar quando a área dele está em foco (WCAG 2.1.4).",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Tooltip", href: "/pt-br/docs/components/tooltip", description: "Uma dica curta ao passar o mouse ou focar, bom lugar para ensinar um atalho." },
		{ title: "Input group", href: "/pt-br/docs/components/input-group", description: "O SearchInput mostra a dica de atalho dentro do campo." },
		{ title: "Code block", href: "/pt-br/docs/components/code-block", description: "Para comandos que a pessoa digita, e não teclas que ela aperta." },
	]}
/>


# Link (/pt-br/docs/components/link)

<ComponentMeta file="link" pattern="WAI-ARIA link" />

<Playground
	name="link/playground"
	component="Link"
	label="Ler o guia completo"
	controls={[
		{ prop: "variant", options: ["default", "muted", "standalone"], default: "default" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Link" />

## Anatomia [#anatomia]

Um `<a>` comum. A variante de destaque coloca uma seta depois do texto. Os dois têm um `data-slot` que você pode usar no CSS.

<Anatomy tree={{ slot: "link", tag: "a", row: true, children: [{ slot: "icon", tag: "svg", note: "só no standalone" }] }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="link/basic" compact />

<ExampleGrid>
	<Example name="link/variants" title="Variantes" wide>
		Use o link padrão dentro de frases, o discreto onde há muitos links juntos (um rodapé, uma linha de termos) e o de destaque para o próximo passo de uma seção.
	</Example>
	<Example name="link/standalone" title="Link de destaque">
		Ele fica sozinho numa linha, então ganha uma seta e uma área de toque de 24px de altura, fácil de acertar no celular.
	</Example>
	<Example name="link/current-page" title="Página atual num menu">
		Clique numa seção. O `aria-current="page"` avisa o leitor de tela em qual página a pessoa está; o negrito mostra isso para quem enxerga.
	</Example>
	<Example name="link/external" title="Abre em nova aba">
		Uma nova aba quebra o botão Voltar, então avise. O ícone mostra isso, e um texto escondido coloca "abre em uma nova aba" no nome que o leitor de tela lê.
	</Example>
	<Example name="link/download" title="Baixar um arquivo">
		Clique para baixar um CSV de verdade. Coloque o formato e o tamanho no texto, para a pessoa saber o que vem antes de tocar numa conexão lenta.
	</Example>
	<Example name="link/skip-link" title="Pular para o conteúdo">
		Clique logo acima da caixa e aperte Tab. A primeira parada é um link escondido que aparece com o foco e pula o menu. Assim quem usa teclado não passa pelo menu em toda página.
	</Example>
	<Example name="link/next-link" title="Com o roteador do Next.js">
		Passe `render={<NextLink href="…" />}`. O roteador cuida do clique sem recarregar a página, e o link mantém o visual do estilo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Links ficam onde a pessoa decide para onde ir. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="link/context-footer" title="Rodapé do site" uses="Link" />
	<Context name="link/context-banner" title="Aviso de nova versão" uses="Link" />
	<Context name="link/context-card-link" title="Card com título em link" uses="Card · Link" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="link/do-meaningful-text" title="Diga para onde o link leva.">
		Quem usa leitor de tela costuma pular de link em link. Cada um precisa fazer sentido fora da frase.
	</Guideline>
	<Guideline kind="dont" name="link/dont-click-here" title='"Clique aqui" ou "Saiba mais".'>
		Numa lista de links, dez "Clique aqui" soam iguais e não dizem nada.
	</Guideline>
	<Guideline kind="do" name="link/do-standalone-cta" title="Um link de destaque para o próximo passo.">
		Use para o caminho principal de uma seção, como começar um guia.
	</Guideline>
	<Guideline kind="dont" name="link/dont-button-as-link" title="Um link que exclui, salva ou copia.">
		Ações são do `Button`. O leitor de tela anuncia um link como "ir para algum lugar", e ninguém espera que ele mude dados.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="link"
	type="LinkProps"
	describe={{
		variant: "O visual do link: `default` dentro de frases, `muted` para links secundários e `standalone` para um link sozinho, com seta.",
		render: "Troca o elemento renderizado, por exemplo pelo link do Next.js: `render={<NextLink href=\"/docs\" />}`.",
	}}
>
	`Link` aceita todos os atributos de `<a>`, como `href`, `target`, `rel`, `download` e `aria-current`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio link.

<StylingHooks
	slots={["link", "icon"]}
	attributes={[
		{ attr: "data-variant", value: "default · muted · standalone" },
		{ attr: "aria-current", value: "page (você define no link da página atual)" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Vai para o próximo link." },
		{ key: "Enter", description: "Segue o link. A barra de espaço não funciona, ao contrário de um botão." },
	]}
	notes={[
		"O texto é o nome que o leitor de tela lê. Acrescente um texto escondido quando o ícone tem significado, como \"abre em uma nova aba\".",
		"Marque o link da página atual com aria-current=\"page\" e não dependa só da cor para mostrar isso.",
		"Links de destaque têm pelo menos 24px de altura (WCAG 2.5.8). Links dentro de frases não precisam, mas deixe espaço entre links numa lista.",
		"Se o clique muda dados ou abre um diálogo, é um botão. Use Button, mesmo que ele pareça um link.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Button", description: "Para ações: salvar, copiar, excluir, abrir um diálogo.", href: "/pt-br/docs/components/button" },
		{ title: "Typography", description: "Títulos e parágrafos onde os links ficam.", href: "/pt-br/docs/components/typography" },
		{ title: "Card", description: "Uma caixa que costuma levar a uma página de detalhes pelo título.", href: "/pt-br/docs/components/card" },
	]}
/>


# Menu (/pt-br/docs/components/menu)

<ComponentMeta file="menu" primitive="Base UI" pattern="WAI-ARIA Menu Button" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe as partes que precisar. O popup vai para um portal e mantém o estilo, o modo e a cor da marca da página em volta.

<Import names="Menu, MenuTrigger, MenuContent, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuSub, MenuSubTrigger, MenuSubContent, MenuGroup, MenuGroupLabel, MenuSeparator" />

## Anatomia [#anatomia]

O `Menu` guarda o estado de aberto. O `MenuTrigger` é o botão (`data-slot="menu-trigger"`, ou o slot do próprio `Button` quando você passa `render={<Button />}`); o `MenuContent` renderiza o popup abaixo num portal. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "menu-positioner",
		tag: "div",
		note: "num portal",
		children: [
			{
				slot: "menu-popup",
				tag: "div",
				note: "role=menu",
				children: [
					{
						slot: "menu-group",
						tag: "div",
						children: [
							{ slot: "menu-group-label", tag: "div" },
							{
								slot: "menu-item",
								tag: "div",
								row: true,
								children: [
									{ slot: "menu-item-icon", tag: "span" },
									{ slot: "menu-shortcut", tag: "span" },
								],
							},
							{
								slot: "menu-checkbox-item",
								tag: "div",
								children: [{ slot: "menu-checkbox-indicator", tag: "span" }],
							},
							{
								slot: "menu-radio-item",
								tag: "div",
								children: [
									{ slot: "menu-radio-indicator", tag: "span", children: [{ slot: "menu-radio-dot", tag: "span" }] },
								],
							},
						],
					},
					{
						slot: "menu-sub-trigger",
						tag: "div",
						note: "abre o menu-sub-popup",
						children: [{ slot: "menu-sub-arrow", tag: "span" }],
					},
					{ slot: "menu-separator", tag: "div" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a marca da barra acima, e todos começam fechados.

<Preview name="menu/basic" compact />

<ExampleGrid>
	<Example name="menu/with-shortcuts" title="Com atalhos">
		Mostre o atalho com `Kbd` para a pessoa aprender enquanto usa o menu, e use `aria-keyshortcuts` para o leitor de tela anunciar também. O menu só exibe o atalho: as teclas você liga por conta própria.
	</Example>
	<Example name="menu/groups" title="Grupos e separadores">
		Passando de cinco ou seis itens, um `MenuGroupLabel` em cada grupo deixa a pessoa pular direto para a parte certa em vez de ler tudo.
	</Example>
	<Example name="menu/checkbox" title="Itens de marcar">
		Liga e desliga opções. O `MenuCheckboxItem` continua aberto depois do clique e informa `aria-checked`, então o leitor de tela diz "marcado" ou "desmarcado".
	</Example>
	<Example name="menu/interactive-status" title="Agir e avisar">
		Escolha uma ação. O foco volta ao gatilho, e uma linha com `role="status"` conta ao leitor de tela o que aconteceu, porque o menu que mostrava a ação sumiu.
	</Example>
	<Example name="menu/destructive" title="Destrutiva, com confirmação">
		Escolha "Excluir projeto". Ele vem por último, depois de um separador, e abre um `AlertDialog`; o `finalFocus` devolve o foco ao botão do menu quando ele fecha.
	</Example>
	<Example name="menu/disabled-reason" title="Desativado, com o motivo">
		Mantenha a ação indisponível no menu para a pessoa saber que ela existe, e diga o porquê no próprio item: o motivo é lido junto com o nome.
	</Example>
	<Example name="menu/icon-only" title="Gatilho só com ícone">
		Um botão "⋯" não tem texto, então o `aria-label` diz de que são as ações: "Ações da fatura INV-4029", e não só "Mais".
	</Example>
	<Example name="menu/links" title="Links como itens">
		Para algumas páginas relacionadas, como num menu de ajuda, passe `render={<a href="…" />}` ao item: ele abre com Enter, e o navegador consegue abrir numa nova aba.
	</Example>
	<Example name="menu/view-options" title="Itens de opção e submenu">
		Para uma configuração de exibição com uma escolha só, como lista ou grade, use o `MenuRadioItem`; guarde um grupo maior, como a ordenação, num `MenuSub` que abre com → e fecha com ←.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O menu tira as ações secundárias do caminho. Estas são telas inteiras que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="menu/context-table-row" title="Ações da linha" uses="Table · Badge · IconButton · Menu" />
	<Context name="menu/context-account" title="Menu da conta" uses="Avatar · Button · Menu" />
	<Context name="menu/context-file-card" title="Card de arquivo" uses="Card · Badge · IconButton · Menu" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="menu/do-verbs" title="Rótulos curtos que começam com verbo.">
		"Renomear", "Duplicar", "Mover para pasta…": a pessoa sabe o que cada item faz antes de escolher.
	</Guideline>
	<Guideline kind="dont" name="menu/dont-pick-value" title="Um menu para escolher um valor.">
		Depois do clique o gatilho continua dizendo "País", e o formulário não recebe nada. Use um Select; para ir a outras páginas, use links ou um NavigationMenu.
	</Guideline>
	<Guideline kind="do" name="menu/do-danger-last" title="Ações destrutivas por último, depois de um separador.">
		O item vermelho fica longe de um ↓ Enter apressado, e a cor mostra que ele é diferente.
	</Guideline>
	<Guideline kind="dont" name="menu/dont-danger-middle" title="Excluir no meio das ações do dia a dia.">
		Um deslize do mouse ou das setas e a coisa errada some.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="menu" type="MenuItemProps" include={["onClick", "closeOnClick", "disabled", "label", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ icon: "Ícone antes do rótulo. Fica escondido do leitor de tela; alguns estilos escondem os ícones de menu.", shortcut: "Mostrado no fim, por exemplo \"Ctrl E\". Só exibe: as teclas você liga por conta própria.", tone: "`danger` pinta uma ação destrutiva. Coloque por último, depois de um separador.", onClick: "Roda quando o item é escolhido com clique, Enter ou Espaço.", closeOnClick: "Se escolher o item fecha o menu.", disabled: "Desativa o item. Ele continua focável, para a pessoa conseguir ler.", label: "Texto para a busca por letra quando o conteúdo do item não é texto simples.", render: "Renderiza outro elemento, como um `<a>` para um link." }}
>
	Estas são as props do `MenuItem`. O `Menu` recebe as props da raiz do Base UI: `open`, `onOpenChange`, `modal` e `disabled`. O `MenuCheckboxItem` recebe `checked`, `defaultChecked`, `onCheckedChange` e `closeOnClick` (desligado por padrão). O `MenuRadioGroup` recebe `value`, `defaultValue` e `onValueChange`, e cada `MenuRadioItem`, um `value`; um `MenuGroupLabel` dentro do grupo dá o nome dele. Envolva o `MenuSubTrigger` e o `MenuSubContent` num `MenuSub`. O `MenuTrigger` recebe `render`, normalmente `<Button />` ou `<IconButton aria-label="…" />`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio popup.

<StylingHooks
	slots={["menu-trigger", "menu-popup", "menu-item", "menu-item-icon", "menu-shortcut", "menu-checkbox-item", "menu-checkbox-indicator", "menu-radio-item", "menu-radio-indicator", "menu-radio-dot", "menu-sub-trigger", "menu-sub-arrow", "menu-sub-popup", "menu-group-label", "menu-separator"]}
	prefix="menu"
	attributes={[
		{ attr: "data-popup-open", value: "no gatilho enquanto o menu está aberto" },
		{ attr: "data-highlighted", value: "no item sob o teclado ou o mouse" },
		{ attr: "data-checked · data-unchecked", value: "nos itens de marcar e de opção" },
		{ attr: "data-disabled", value: "num item desativado" },
		{ attr: "data-tone", value: "danger" },
		{ attr: "data-side", value: "top · bottom (no popup)" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter / Space / ↓", description: "No gatilho: abre o menu e foca o primeiro item." },
		{ key: "↑", description: "No gatilho: abre o menu e foca o último item." },
		{ key: "↓ / ↑", description: "Anda entre os itens, voltando ao início no fim." },
		{ key: "Home / End", description: "Vai para o primeiro ou o último item." },
		{ key: "A–Z", description: "Vai para o próximo item que começa com a letra." },
		{ key: "Enter / Space", description: "Escolhe o item; num item de marcar ou de opção, alterna e mantém o menu aberto." },
		{ key: "→ / ←", description: "No gatilho de um submenu, → abre o submenu no primeiro item; dentro dele, ← fecha e volta." },
		{ key: "Esc", description: "Fecha o submenu, ou o menu, e devolve o foco ao gatilho dele." },
		{ key: "Tab", description: "Fecha o menu e segue em frente." },
	]}
	notes={[
		"O gatilho informa aria-haspopup e aria-expanded, e o do submenu também; os itens são menuitem, os de marcar são menuitemcheckbox e os de opção, menuitemradio, os dois com aria-checked.",
		"Itens desativados continuam na ordem das setas e são anunciados como indisponíveis, então o motivo no texto deles também é lido.",
		"Depois de uma ação o menu some: anuncie o resultado com role=\"status\" e mantenha o foco no gatilho.",
		"O popup vai para um portal mas mantém o estilo pelo PortalScope, e o contraste passa no WCAG 2.2 AA nos 13 estilos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Select", description: "Escolhe um valor para um formulário, em vez de rodar uma ação.", href: "/pt-br/docs/components/select" },
		{ title: "Menu de contexto", description: "As mesmas ações no clique direito.", href: "/pt-br/docs/components/context-menu" },
		{ title: "Button", description: "Uma ou duas ações que cabem à vista.", href: "/pt-br/docs/components/button" },
	]}
/>


# Menubar (/pt-br/docs/components/menubar)

<ComponentMeta file="menubar" primitive="Base UI" pattern="WAI-ARIA Menubar" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe as partes que precisar. Os menus renderizam num portal e mantêm o estilo, o modo e a cor da página em volta.

<Import names="Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSub, MenubarSubTrigger, MenubarSubContent, MenubarSeparator" />

## Anatomia [#anatomia]

O `Menubar` é a barra, uma parada só do Tab. Cada `MenubarMenu` junta um `MenubarTrigger` na barra com um popup `MenubarContent`, renderizado num portal. Dentro vão os itens, os itens de marcar, os de opção e os submenus.

<Anatomy
	tree={{
		slot: "menubar",
		tag: "div",
		note: "role=menubar",
		children: [
			{ slot: "menubar-trigger", tag: "button", note: "role=menuitem" },
			{
				slot: "menubar-positioner",
				tag: "div",
				note: "num portal",
				children: [
					{
						slot: "menubar-popup",
						tag: "div",
						note: "role=menu",
						children: [
							{
								slot: "menubar-item",
								tag: "div",
								row: true,
								children: [
									{ slot: "menubar-item-icon", tag: "span" },
									{ slot: "menubar-item-label", tag: "span" },
									{ slot: "menubar-item-shortcut", tag: "span" },
								],
							},
							{
								slot: "menubar-checkbox-item",
								tag: "div",
								row: true,
								children: [
									{ slot: "menubar-item-indicator", tag: "span", note: "quando marcado" },
									{ slot: "menubar-item-label", tag: "span" },
								],
							},
							{
								slot: "menubar-sub-trigger",
								tag: "div",
								row: true,
								children: [
									{ slot: "menubar-item-label", tag: "span" },
									{ slot: "menubar-sub-arrow", tag: "span" },
								],
							},
							{ slot: "menubar-separator", tag: "div" },
						],
					},
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima, e todos começam fechados.

<Preview name="menubar/basic" compact />

<ExampleGrid>
	<Example name="menubar/shortcuts" title="Com atalhos">
		Mostre cada atalho com `Kbd` para a pessoa aprender enquanto navega, e adicione `aria-keyshortcuts` para o leitor de tela falar também. A barra só mostra o atalho: as teclas você liga no seu app.
	</Example>
	<Example name="menubar/checkbox" title="Itens de marcar">
		Abra Exibir e desligue a régua. O `MenubarCheckboxItem` continua aberto depois do clique e informa `aria-checked`, então dá para mudar várias opções seguidas.
	</Example>
	<Example name="menubar/radio" title="Itens de opção">
		Escolha um nível de zoom. O `MenubarRadioGroup` serve para um valor entre poucos; cada item é lido como "marcado" ou "não marcado".
	</Example>
	<Example name="menubar/submenu" title="Submenu">
		Agrupe variações de um comando, como os formatos de exportação, num `MenubarSub`. Fique num nível só: cada nível é mais um passar do mouse e mais uma seta.
	</Example>
	<Example name="menubar/disabled-reason" title="Desativado, com o motivo">
		Deixe o comando indisponível no lugar para a pessoa aprender onde ele fica, e diga o porquê no item: itens desativados continuam recebendo foco, então o motivo é lido junto com o nome.
	</Example>
	<Example name="menubar/destructive" title="Destrutivo, com confirmação">
		Escolha "Excluir documento". Ele vem por último, depois de um separador, e abre um `AlertDialog`; o `finalFocus` devolve o foco para Arquivo quando ele fecha.
	</Example>
	<Example name="menubar/interactive-status" title="Agir e avisar">
		Escolha um comando. O foco volta para o gatilho do menu, e uma linha com `role="status"` conta ao leitor de tela o que aconteceu, porque o menu que mostrava a ação sumiu.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

A menubar fica no alto da janela de um app, acima do trabalho. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="menubar/context-spreadsheet" title="Planilha" uses="Menubar · Badge · Kbd · Table" />
	<Context name="menubar/context-photo-editor" title="Editor de fotos" uses="Menubar · Toolbar" />
	<Context name="menubar/context-mail" title="Cliente de e-mail" uses="Menubar · Avatar · Badge · Kbd" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="menubar/do-app-window" title="Menubar para um app com muitos comandos.">
		Editores, planilhas e ferramentas de design têm dezenas de comandos; Arquivo, Editar e Formatar dão a cada um um lugar que a pessoa já conhece.
	</Guideline>
	<Guideline kind="dont" name="menubar/dont-site-nav" title="Menubar para ir de uma página a outra.">
		Os itens não são links: nada de clique do meio, nada de "abrir em nova aba", e setas que quem visita um site não espera. Use um NavigationMenu.
	</Guideline>
	<Guideline kind="do" name="menubar/do-groups" title="Comandos parecidos juntos, com os atalhos.">
		Os separadores dividem criar, salvar e imprimir, então a pessoa percorre três grupos curtos em vez de uma lista comprida.
	</Guideline>
	<Guideline kind="dont" name="menubar/dont-flat-list" title="Dez comandos sem ordem.">
		Imprimir ao lado de Novo, Excluir ao lado de Renomear: a pessoa lê linha por linha, e um deslize cai no item errado.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="menubar" type="MenubarItemProps" include={["onClick", "closeOnClick", "disabled", "label", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{ icon: "Ícone antes do texto. Fica escondido do leitor de tela.", shortcut: "Atalho mostrado no fim da linha, normalmente um `Kbd`. Só aparece: use junto com `aria-keyshortcuts` e ligue as teclas você mesmo.", tone: "`\"danger\"` pinta de vermelho um item destrutivo.", onClick: "Roda quando o item é escolhido com clique, Enter ou Espaço.", closeOnClick: "Se escolher o item fecha o menu.", disabled: "Desativa o item. Ele continua recebendo foco, então a pessoa ainda consegue lê-lo.", label: "Texto para a busca por letra quando o conteúdo do item não é texto simples.", render: "Renderiza outro elemento, como um `<a>` para um link." }}
>
	Estas são as props do `MenubarItem`. O `Menubar` aceita `modal`, `disabled`, `loopFocus` e `orientation`, e precisa de um `aria-label`. O `MenubarCheckboxItem` aceita `checked`, `defaultChecked`, `onCheckedChange` e `shortcut`; o `MenubarRadioGroup` aceita `value`, `defaultValue` e `onValueChange`. O `MenubarMenu` aceita as props da raiz de menu do Base UI, como `open` e `onOpenChange`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria barra.

<StylingHooks
	slots={["menubar", "menubar-trigger", "menubar-popup", "menubar-item", "menubar-item-icon", "menubar-item-label", "menubar-item-shortcut", "menubar-checkbox-item", "menubar-radio-item", "menubar-item-indicator", "menubar-sub-trigger", "menubar-sub-popup", "menubar-separator"]}
	prefix="menubar"
	attributes={[
		{ attr: "data-popup-open", value: "no gatilho cujo menu está aberto" },
		{ attr: "data-highlighted", value: "no item sob o teclado ou o mouse" },
		{ attr: "data-checked · data-unchecked", value: "nos itens de marcar e de opção" },
		{ attr: "data-disabled", value: "num item desativado" },
		{ attr: "data-tone", value: "danger" },
		{ attr: "data-orientation", value: "horizontal · vertical (na barra)" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Entra na barra, no último menu usado, e sai dela: a barra inteira é uma parada só do Tab." },
		{ key: "→ / ←", description: "Na barra: vai para o menu seguinte ou anterior, dando a volta nas pontas. Num menu aberto: → abre um submenu e ← fecha; nos outros itens, abrem o menu seguinte ou anterior." },
		{ key: "↓ / Enter / Espaço", description: "Num menu da barra: abre e leva o foco ao primeiro item ativo." },
		{ key: "↓ / ↑", description: "Passa de um item para outro, dando a volta nas pontas. Itens desativados entram na conta." },
		{ key: "Home / End", description: "Vai para o primeiro ou o último item." },
		{ key: "A–Z", description: "Vai para o próximo item que começa com essa letra." },
		{ key: "Enter / Espaço", description: "Roda o item e fecha o menu; num item de marcar ou de opção, alterna e mantém o menu aberto." },
		{ key: "Esc", description: "Fecha o submenu, ou o menu, e devolve o foco ao gatilho na barra." },
	]}
	notes={[
		"A barra é role=menubar e precisa de um aria-label. Os gatilhos são menuitem com aria-haspopup e aria-expanded; itens de marcar e de opção informam aria-checked.",
		"Com um menu aberto, passar o mouse por outro gatilho da barra troca de menu, como num programa de computador.",
		"Os atalhos no Kbd só aparecem. Adicione aria-keyshortcuts para o leitor de tela falar e trate as teclas no seu app.",
		"Depois de um comando o menu some: conte o resultado com role=\"status\" e deixe o foco no gatilho.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Menu", description: "Um menu atrás de um botão, para as ações de uma linha ou de um card.", href: "/pt-br/docs/components/menu" },
		{ title: "Navigation menu", description: "Links para as páginas de um site, com painéis que abrem.", href: "/pt-br/docs/components/navigation-menu" },
		{ title: "Kbd", description: "Mostra o atalho de teclado ao lado de um comando.", href: "/pt-br/docs/components/kbd" },
	]}
/>


# Meter (/pt-br/docs/components/meter)

<ComponentMeta file="meter" primitive="Base UI" pattern="WAI-ARIA meter" />

<Playground
	name="meter/playground"
	component="Meter"
	controls={[
		{ prop: "tone", options: ["brand", "warning", "danger"], default: "brand" },
		{ prop: "showValue", default: true },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O estilo carregado cuida do visual.

<Import names="Meter" />

## Anatomia [#anatomia]

Uma raiz com um cabeçalho (rótulo e valor) e um trilho com o preenchimento. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="meter"]', color: "#8be36f" },
		{ label: '[data-slot="meter-track"] · [data-slot="meter-indicator"]', color: "#ffcf7a" },
		{ label: "rótulo · valor", color: "#7cc7ff" },
	]}
>
	<span className="a-part">trilho</span>
	<span className="a-part">preenchimento</span>
	<span className="a-label">Armazenamento 64,2 de 100 GB</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="meter/basic" compact />

<ExampleGrid>
	<Example name="meter/a11y-vs-progress" title="Meter ou Progress?">
		O Meter diz quanto algo está cheio, e o valor pode subir ou descer. O Progress diz quanto de uma tarefa já foi feito, e só anda para a frente.
	</Example>
	<Example name="meter/tones" title="Tons para o status">
		Use `brand` quando está tudo bem, `warning` quando chega perto do limite e `danger` quando a pessoa precisa agir. Diga isso no texto também, não só na cor.
	</Example>
	<Example name="meter/thresholds" title="Avise antes de encher">
		Clique para adicionar arquivos. Escolha o tom a partir do valor: o medidor fica `warning` em 75% e `danger` quando a caixa enche.
	</Example>
	<Example name="meter/value-label" title="Na unidade de verdade">
		Use o limite real em `max` e mostre "8.450 de 10.000". As pessoas pensam em usuários e gigabytes, não em porcentagem.
	</Example>
	<Example name="meter/seats" title="Vagas, por extenso">
		Com o `getAriaValueText`, o leitor de tela fala "7 de 10 vagas em uso" em vez de "70 por cento".
	</Example>
	<Example name="meter/range" title="Uma faixa que não começa no zero">
		Use `min` e `max` para escalas como temperatura. O preenchimento mostra onde 24 °C fica entre 16 e 32.
	</Example>
	<Example name="meter/settings-row" title="Numa linha de configurações" wide>
		Coloque o medidor ao lado da ação que resolve. "Liberar espaço" perto do número poupa a pessoa de procurar.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O medidor fica onde a pessoa confere os limites dela. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="meter/context-plan-limit" title="Vagas da equipe" uses="Card · Meter · Button" />
	<Context name="meter/context-password-strength" title="Força da senha" uses="Card · Label · Input · Meter" />
	<Context name="meter/context-server" title="Recursos do servidor" uses="Card · Meter" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="meter/do-fixed-capacity" title="Meça algo que tem limite.">
		Espaço em disco, vagas, e-mails do mês: um valor e um máximo conhecido.
	</Guideline>
	<Guideline kind="dont" name="meter/dont-task-completion" title="Um medidor para um envio.">
		Um envio é uma tarefa com fim. Use o Progress, para o leitor de tela anunciar uma barra de progresso.
	</Guideline>
	<Guideline kind="do" name="meter/do-explain-unit" title="Mostre o valor e o limite.">
		"85 de 100 conexões" diz quanto espaço ainda sobra.
	</Guideline>
	<Guideline kind="dont" name="meter/dont-missing-unit" title="Um número sem unidade.">
		85 o quê? Porcentagem, megabytes ou usuários? A pessoa não sabe se deve se preocupar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="meter" type="MeterProps" include={["value", "min", "max", "getAriaValueText", "format", "locale"]}
	types={{ getAriaValueText: "(formattedValue, value) => string", format: "Intl.NumberFormatOptions", locale: "Intl.LocalesArgument" }}
	describe={{
		label: "Rótulo visível. Também é o nome do medidor para o leitor de tela.",
		showValue: "Mostra o valor ao lado do rótulo.",
		valueLabel: "Troca o texto do valor, por exemplo por \"18 de 20 vagas\". Muda só o que aparece na tela.",
		tone: "Cor do preenchimento: `brand` quando está tudo bem, `warning` perto do limite, `danger` quando é preciso agir.",
		value: "A medida atual, entre `min` e `max`.",
		min: "O menor valor da faixa.",
		max: "O maior valor da faixa, como o limite do plano.",
		getAriaValueText: "O texto que o leitor de tela ouve para o valor. Por padrão, a porcentagem.",
		format: "Opções de Intl.NumberFormat para o valor formatado.",
		locale: "Idioma usado para formatar o valor.",
	}}
>
	As outras props da raiz do medidor do Base UI e os atributos nativos de `<div>` passam direto.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["meter", "meter-header", "meter-label", "meter-value", "meter-track", "meter-indicator"]}
	attributes={[
		{ attr: "data-tone", value: "brand · warning · danger" },
		{ attr: "data-slot", value: '"meter" · "meter-track" · "meter-indicator"' },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "Não recebe foco. Ele só mostra um valor; os controles ao redor é que recebem o foco." }]}
	notes={[
		"Renderiza role=\"meter\" com aria-valuenow, aria-valuemin e aria-valuemax, e o rótulo vira o nome acessível.",
		"Por padrão, o leitor de tela ouve a porcentagem. O valueLabel muda só o texto visível, então passe o getAriaValueText com as mesmas palavras.",
		"A cor nunca é o único sinal: coloque o status (\"Quase cheia\") no texto do valor.",
		"O preenchimento mantém contraste de pelo menos 3:1 com o trilho nos 13 estilos, claro e escuro.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Progress", href: "/pt-br/docs/components/progress", description: "Quanto de uma tarefa já foi feito, como um envio." },
		{ title: "Stat", href: "/pt-br/docs/components/stat", description: "Um número importante com rótulo e tendência." },
		{ title: "Badge", href: "/pt-br/docs/components/badge", description: "Um status curto, como \"Quase cheia\"." },
	]}
/>


# Native select (/pt-br/docs/components/native-select)

<ComponentMeta file="native-select" primitive="HTML" pattern="Native <select>" />

<Playground
	name="native-select/playground"
	component="NativeSelect"
	controls={[
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar.

<Import names="NativeSelect, Label" />

## Anatomia [#anatomia]

Um invólucro em volta de um `<select>` de verdade e de uma seta. As opções são elementos `<option>` e `<optgroup>` comuns.

<Anatomy
	keys={[
		{ label: '[data-slot="native-select"]', color: "#8be36f" },
		{ label: '[data-slot="native-select"] > select · [data-slot="icon"]', color: "#ffcf7a" },
		{ label: "<option> (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">select</span>
	<span className="a-label">Brasil</span>
	<span className="a-part">icon</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="native-select/basic" compact />

<ExampleGrid>
	<Example name="native-select/with-description" title="Com descrição">
		Dentro de um `Field`, o `FieldDescription` fica ligado ao select e é lido depois do rótulo.
	</Example>
	<Example name="native-select/placeholder" title="Opção de placeholder">
		Uma primeira opção vazia e desativada, mais `required`, faz a pessoa escolher em vez de ficar com um palpite seu.
	</Example>
	<Example name="native-select/groups" title="Grupos de opções">
		O `<optgroup>` divide uma lista longa em seções com nome, e o leitor de tela anuncia o grupo.
	</Example>
	<Example name="native-select/long-list" title="Lista longa">
		Oitenta anos cabem bem: a pessoa digita "19" para pular, e o celular abre a própria roleta.
	</Example>
	<Example name="native-select/installments" title="Parcelamento">
		Escolha o número de parcelas. Um `value` controlado atualiza o resumo, e o `aria-live` lê o novo valor.
	</Example>
	<Example name="native-select/disabled" title="Desativado, com o motivo">
		Um select desativado não recebe foco, então coloque o motivo em texto visível logo ao lado.
	</Example>
	<Example name="native-select/invalid" title="Obrigatório, com erro">
		Escolha uma forma de envio e o erro some. O `Field invalid` marca o select e liga o `FieldError` a ele.
	</Example>
	<Example name="native-select/inline" title="Em linha">
		Numa barra de ferramentas, `style={{ width: "auto" }}` deixa ele do tamanho da maior opção, ao lado do rótulo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="native-select/context-pagination" title="Rodapé de tabela" uses="NativeSelect · Label · IconButton · Text" />
	<Context name="native-select/context-filters" title="Painel de filtros" uses="Fieldset · NativeSelect · Button" />
	<Context name="native-select/context-shipping" title="Entrega" uses="Card · Field · NativeSelect · Input · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="native-select/do-long-list" title="Listas longas e conhecidas.">
		Países, estados, anos: a pessoa passa o olho ou digita para achar.
	</Guideline>
	<Guideline kind="dont" name="native-select/dont-two-options" title="Um select para sim ou não.">
		Duas opções escondidas atrás de um clique. Use um `Switch`, um `Checkbox` ou um `RadioGroup`.
	</Guideline>
	<Guideline kind="do" name="native-select/do-neutral-first" title="Comece com uma opção neutra.">
		Em respostas que importam, "Escolha um motivo…" faz a pessoa escolher de fato.
	</Guideline>
	<Guideline kind="dont" name="native-select/dont-preselected" title="Uma resposta já marcada.">
		A pessoa pula o campo, e você coleta o seu padrão como se fosse a resposta dela.
	</Guideline>
</Guidelines>

## Props [#props]

O `NativeSelect` recebe todos os atributos de `<select>`. Estes são os mais usados:


<Props
	file="native-select"
	type="NativeSelectProps"
	include={["value", "defaultValue", "onChange", "disabled", "required", "name", "autoComplete"]}
	types={{"value": "string", "defaultValue": "string", "onChange": "(event: ChangeEvent<HTMLSelectElement>) => void", "disabled": "boolean", "required": "boolean", "name": "string", "autoComplete": "string"}}
	describe={{"value": "O `value` da opção escolhida, controlado ou não.", "defaultValue": "O `value` da opção escolhida, controlado ou não.", "onChange": "Roda quando a pessoa escolhe outra opção. Leia `event.target.value`.", "disabled": "Desativa o select e o tira da ordem de tabulação.", "required": "O formulário não é enviado enquanto a opção escolhida tiver valor vazio.", "name": "Identifica o valor no envio do formulário.", "autoComplete": "Deixa o navegador preencher, por exemplo `\"country\"` ou `\"address-level1\"`."}}
>
	`className` e `style` vão para o `<span>` de fora, para você definir o tamanho; os outros atributos vão para o `<select>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio select.

<StylingHooks
	slots={["native-select"]}
	attributes={[
		{ attr: "data-slot", value: '"native-select" (o invólucro)' },
		{ attr: ":disabled", value: "no select interno quando desativado" },
		{ attr: ":focus", value: "no select interno enquanto focado" },
		{ attr: "data-invalid", value: "no select interno quando o Field está inválido" },
	]}
>

```css
/* select sem borda dentro de uma barra de tabela */
.toolbar [data-slot="native-select"] > select {
  --cml-border-control: transparent;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco ao select." },
		{ key: "Arrow Up · Arrow Down", description: "Troca a opção escolhida (no macOS, abre a lista)." },
		{ key: "Alt + Arrow Down", description: "Abre a lista de opções." },
		{ key: "A–Z", description: "Pula para a próxima opção que começa com a letra digitada." },
	]}
	notes={[
		"É o select do próprio navegador, então leitores de tela, controle por voz e celulares já conhecem.",
		"Dentro de um Field, o rótulo, a descrição e o erro ficam ligados ao select; fora dele, dê o nome com Label htmlFor.",
		"A seta é decorativa e fica escondida das tecnologias assistivas.",
		"O required usa a validação nativa: o formulário não é enviado e o navegador explica o motivo.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Select", description: "Um popup próprio, para listas curtas com opções ricas.", href: "/pt-br/docs/components/select" },
		{ title: "Combobox", description: "Busque numa lista longa enquanto digita.", href: "/pt-br/docs/components/combobox" },
		{ title: "Field", description: "Rótulo, descrição e erro para um controle.", href: "/pt-br/docs/components/field" },
	]}
/>


# Navigation menu (/pt-br/docs/components/navigation-menu)

<ComponentMeta file="navigation-menu" primitive="Base UI" pattern="WAI-ARIA Disclosure Navigation Menu" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe as partes que precisar. Os painéis renderizam num portal e mantêm o estilo, o modo e a cor da página em volta.

<Import names="NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink" />

## Anatomia [#anatomia]

O `NavigationMenu` renderiza o `<nav>`; dê a ele um `aria-label`. Cada `NavigationMenuItem` guarda um `NavigationMenuLink` ou um `NavigationMenuTrigger` com o seu `NavigationMenuContent`, o painel que abre embaixo dele.

<Anatomy
	tree={{
		slot: "navigation-menu-list",
		tag: "ul",
		note: "dentro do <nav>",
		children: [
			{
				slot: "navigation-menu-item",
				tag: "li",
				row: true,
				children: [
					{
						slot: "navigation-menu-trigger",
						tag: "button",
						note: "aria-expanded",
						children: [{ slot: "navigation-menu-icon", tag: "span", note: "seta" }],
					},
				],
			},
			{
				slot: "navigation-menu-item",
				tag: "li",
				children: [{ slot: "navigation-menu-link", tag: "a", note: "aria-current quando ativo" }],
			},
			{
				slot: "navigation-menu-positioner",
				tag: "div",
				note: "num portal",
				children: [
					{
						slot: "navigation-menu-popup",
						tag: "nav",
						children: [
							{
								slot: "navigation-menu-content",
								tag: "div",
								children: [{ slot: "navigation-menu-link", tag: "a" }],
							},
						],
					},
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima, e todo painel começa fechado.

<Preview name="navigation-menu/basic" compact />

<ExampleGrid>
	<Example name="navigation-menu/links-bar" title="Só links">
		Quando todo item do topo é uma página, você não precisa de painéis: uma barra de `NavigationMenuLink` é uma lista simples de links de verdade, cada um uma parada do Tab.
	</Example>
	<Example name="navigation-menu/mega-panel" title="Painel de produtos">
		Abra Produtos. Uma descrição curta embaixo de cada nome mostra qual produto serve antes do clique, e o ícone ajuda a achar de novo da próxima vez.
	</Example>
	<Example name="navigation-menu/featured" title="Card em destaque no painel">
		Destaque uma página do momento, como o webinar da semana que vem, ao lado dos links de sempre. Faça do card inteiro um link só, para ser uma parada só do Tab.
	</Example>
	<Example name="navigation-menu/current-page" title="Página atual">
		Clique nos links. O `active` coloca `aria-current="page"`, que o leitor de tela anuncia como "página atual" e o estilo sublinha, para não depender só da cor.
	</Example>
	<Example name="navigation-menu/delay" title="Atraso ao passar o mouse">
		Passe o mouse pela barra. O `delay` e o `closeDelay` evitam que os painéis pisquem quando a pessoa só está passando por cima a caminho da página.
	</Example>
	<Example name="navigation-menu/vertical" title="Vertical">
		Para as seções de uma área, como as configurações, empilhe a lista na lateral. O `orientation="vertical"` troca as setas para ↑ e ↓.
	</Example>
	<Example name="navigation-menu/landmarks" title="Regiões com nome">
		Quem usa leitor de tela pula entre regiões pelo nome. Com dois navs na página, "Principal" e "Rodapé" separam um do outro; dois navs sem nome são lidos os dois como "navegação".
	</Example>
</ExampleGrid>

A barra quebra a linha em vez de se recolher: ela não tem um layout próprio para celular. Abaixo de uns 640px, troque por um botão de menu que abre um [Drawer](/pt-br/docs/components/drawer) com os mesmos links.

## Em contexto [#em-contexto]

O navigation menu fica no cabeçalho de um site ou de uma seção. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="navigation-menu/context-site-header" title="Cabeçalho de site de produto" uses="NavigationMenu · Button · Card" />
	<Context name="navigation-menu/context-store" title="Departamentos de uma loja" uses="NavigationMenu · SearchInput · IconButton · Badge" />
	<Context name="navigation-menu/context-help-center" title="Artigo da central de ajuda" uses="NavigationMenu · Card · Badge" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="navigation-menu/do-destinations" title="Nomeie lugares para onde a pessoa vai.">
		"Notas fiscais", "Clientes", "Relatórios": cada rótulo é uma página, então a pessoa sabe onde vai parar e pode abrir numa nova aba.
	</Guideline>
	<Guideline kind="dont" name="navigation-menu/dont-commands" title="Comandos fantasiados de link.">
		"Exportar CSV" e "Arquivar" não levam a lugar nenhum. Coloque ações num Menu ou numa Menubar, onde elas são anunciadas como comandos.
	</Guideline>
	<Guideline kind="do" name="navigation-menu/do-describe" title="Poucos links, cada um com uma linha de ajuda.">
		Três opções com uma frase cada são mais rápidas de escolher do que uma lista de nomes para adivinhar.
	</Guideline>
	<Guideline kind="dont" name="navigation-menu/dont-wall" title="Todas as páginas num painel só.">
		Doze links sem grupos nem descrições viram um mapa do site. Divida por assunto, ou leve a uma página que liste todos.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="navigation-menu" type="NavigationMenuProps" include={["value", "defaultValue", "onValueChange", "delay", "closeDelay", "orientation"]}
	types={{ value: "any", defaultValue: "any", onValueChange: "(value, eventDetails) => void" }}
	describe={{ value: "O `value` do item cujo painel está aberto, para controlar pelo código. `null` fecha.", defaultValue: "O item cujo painel começa aberto. Deixe vazio: nada deve abrir sozinho.", onValueChange: "Chamado quando um painel abre ou fecha, com o motivo em `eventDetails`.", delay: "Quanto tempo o mouse precisa ficar num gatilho para o painel abrir, em milissegundos.", closeDelay: "Quanto tempo o painel espera para fechar depois que o mouse sai, em milissegundos.", orientation: "Quais setas passam entre os itens do topo: ← → ou ↑ ↓." }}
>
	Estas são as props do `NavigationMenu`. O `NavigationMenuLink` aceita `active` (coloca `aria-current="page"`) e `closeOnClick`. O `NavigationMenuTrigger` aceita `hideIcon`, e o `NavigationMenuContent` aceita `align` e `sideOffset`. Dê um `value` ao `NavigationMenuItem` quando controlar o menu pelo código.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio nav.

<StylingHooks
	slots={["navigation-menu-list", "navigation-menu-item", "navigation-menu-trigger", "navigation-menu-icon", "navigation-menu-link", "navigation-menu-popup", "navigation-menu-content"]}
	prefix="nav"
	attributes={[
		{ attr: "data-popup-open", value: "no gatilho cujo painel está aberto" },
		{ attr: "aria-current · data-active", value: "page · no link da página atual" },
		{ attr: "data-open", value: "no painel aberto" },
		{ attr: "data-side · data-align", value: "onde o painel fica em relação ao gatilho" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab / Shift + Tab", description: "Passa pelos links e gatilhos do topo. Cada um é uma parada do Tab, como qualquer lista de links." },
		{ key: "→ / ←", description: "Também passa pelos itens do topo (↓ / ↑ com orientation=\"vertical\"). Não troca o painel aberto." },
		{ key: "Enter / Espaço", description: "Num gatilho: abre ou fecha o painel. Num link: segue o link." },
		{ key: "↓", description: "Num gatilho de uma barra horizontal: abre o painel." },
		{ key: "Esc", description: "Fecha o painel e devolve o foco ao gatilho." },
	]}
	notes={[
		"A raiz é um <nav>: dê um aria-label para ela aparecer pelo nome entre as regiões da página.",
		"Os gatilhos são botões com aria-expanded; os links são <a href> de verdade, então o clique do meio e o \"abrir em nova aba\" funcionam.",
		"Marque a página em que a pessoa está com active, que coloca aria-current=\"page\".",
		"Passar o mouse abre o painel depois do delay (50 ms por padrão), e sair fecha depois do closeDelay. Os painéis também abrem pelo teclado, então nada depende do mouse.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Drawer", description: "Guarda os mesmos links no celular, atrás de um botão de menu.", href: "/pt-br/docs/components/drawer" },
		{ title: "Menubar", description: "Menus de comandos para um app, não links para páginas.", href: "/pt-br/docs/components/menubar" },
		{ title: "Menu", description: "Uma lista de ações atrás de um botão.", href: "/pt-br/docs/components/menu" },
	]}
/>


# Number field (/pt-br/docs/components/number-field)

<ComponentMeta file="number-field" primitive="Base UI" pattern="WAI-ARIA Spinbutton (keyboard)" />

<Playground
	name="number-field/playground"
	component="NumberField"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Coloque dentro de um `Field` para ganhar um rótulo.

<Import names="NumberField, Field, FieldLabel" />

## Anatomia [#anatomia]

Uma caixa com três partes: o botão de menos, o input e o botão de mais.

<Anatomy
	keys={[
		{ label: '[data-slot="number-field"] · [data-slot="number-field-group"]', color: "#8be36f" },
		{ label: '[data-slot="number-field-button"]', color: "#ffcf7a" },
		{ label: '[data-slot="number-field-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">−</span>
	<span className="a-label">2</span>
	<span className="a-part">+</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="number-field/basic" compact />

<ExampleGrid>
	<Example name="number-field/bounds" title="Mínimo e máximo">
		Clique no mais até parar. No `max` o botão se desativa, e a descrição explica o motivo antes de a pessoa chegar lá.
	</Example>
	<Example name="number-field/total" title="Total ao vivo">
		Mude as licenças. `value` e `onValueChange` atualizam o preço abaixo, anunciado com `aria-live`.
	</Example>
	<Example name="number-field/percent" title="Porcentagem, com passos">
		O `format={{ style: "percent" }}` trabalha com frações, então `step={0.05}` são 5 pontos; o `largeStep` é o que Shift + seta soma.
	</Example>
	<Example name="number-field/currency" title="Moeda">
		Passe `format` e `locale` e o campo mostra o R$ e os separadores que a pessoa espera, enquanto o valor continua um número.
	</Example>
	<Example name="number-field/unit" title="Com unidade">
		Um formato `unit` coloca o "kg" dentro do campo, então o rótulo não precisa dizer e ninguém pensa em libras.
	</Example>
	<Example name="number-field/required" title="Obrigatório">
		Digite um número, apague e saia. Dentro de um `Field`, `required` e `FieldError match="valueMissing"` funcionam como em qualquer input.
	</Example>
	<Example name="number-field/labels" title="Botões com nome">
		Os botões só mostram − e +. O `decrementLabel` e o `incrementLabel` dão nome a eles, então traduza junto com a página.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="number-field/context-cart" title="Carrinho de compras" uses="Card · Field · NumberField · Button" />
	<Context name="number-field/context-booking" title="Reserva" uses="Card · Field · NumberField · Button" />
	<Context name="number-field/context-parcel" title="Tamanho do pacote" uses="Fieldset · Field · NumberField · NativeSelect" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="number-field/do-quantity" title="Quantidades pequenas que a pessoa ajusta.">
		Hóspedes, ingressos, licenças: um clique ou uma seta chega lá mais rápido do que digitar.
	</Guideline>
	<Guideline kind="dont" name="number-field/dont-zip" title="Códigos que são só dígitos.">
		CEP, telefone e número de cartão não são quantidades: os botões e os separadores estragam o valor. Use um `Input` com `inputMode="numeric"`.
	</Guideline>
	<Guideline kind="do" name="number-field/do-unit" title="Mostre a unidade no valor.">
		"45 min" não deixa dúvida.
	</Guideline>
	<Guideline kind="dont" name="number-field/dont-no-unit" title="Um número solto.">
		45 são minutos, horas ou pessoas? Não faça a pessoa adivinhar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="number-field" type="NumberFieldProps"
	include={["value", "defaultValue", "onValueChange", "min", "max", "step", "largeStep", "format", "locale", "disabled", "readOnly", "required", "name"]}
	types={{ onValueChange: "(value: number | null, details) => void", format: "Intl.NumberFormatOptions", locale: "Intl.LocalesArgument" }}
	describe={{
		placeholder: "Dica mostrada no input vazio. Não substitui o rótulo.",
		decrementLabel: "Nome acessível do botão de menos. Traduza junto com a página.",
		incrementLabel: "Nome acessível do botão de mais. Traduza junto com a página.",
		value: "O valor, controlado. `null` quando o campo está vazio.",
		defaultValue: "O valor inicial, não controlado.",
		onValueChange: "Roda a cada mudança de valor, por digitação, botões ou teclado.",
		min: "O menor valor permitido.",
		max: "O maior valor permitido.",
		step: "Quanto os botões e as setas somam ou subtraem.",
		largeStep: "Quanto Shift + seta e Page Up / Page Down somam ou subtraem.",
		format: "Opções do `Intl.NumberFormat`: moeda, porcentagem, unidade, casas decimais.",
		locale: "O idioma usado na formatação, como `\"pt-BR\"`.",
		disabled: "Desativa o campo e os botões.",
		readOnly: "Mostra o valor sem deixar mudar.",
		required: "Exige um valor no envio do formulário.",
		name: "Identifica o valor no envio do formulário.",
	}}
>
	As outras props da raiz do Base UI passam direto, como `smallStep`, `snapOnStep`, `allowWheelScrub` e `onValueCommitted`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio campo.

<StylingHooks
	slots={["number-field", "number-field-group", "number-field-input", "number-field-button"]}
	prefix="number"
	attributes={[
		{ attr: "data-slot", value: '"number-field" · "number-field-group" · "number-field-input" · "number-field-button"' },
		{ attr: "data-disabled", value: "na raiz quando desativado, num botão quando chega ao limite" },
		{ attr: "data-readonly", value: "presente quando só leitura" },
		{ attr: "data-invalid", value: "presente quando inválido" },
		{ attr: "data-scrubbing", value: "presente enquanto arrasta para mudar o valor" },
	]}
>

```css
/* botões redondos, só no carrinho */
.cart [data-slot="number-field"] {
  --cml-number-btn-radius: 999px;
  --cml-number-divider: 0;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Arrow Up · Arrow Down", description: "Soma ou subtrai um passo." },
		{ key: "Shift + Arrow", description: "Soma ou subtrai o largeStep." },
		{ key: "Home · End", description: "Vai ao min ou ao max, quando definidos." },
		{ key: "Tab", description: "Leva o foco ao input. Os botões ficam fora, já que as setas fazem o mesmo." },
	]}
	notes={[
		"O input é uma caixa de texto anunciada como campo numérico (aria-roledescription), com o nome vindo do rótulo do Field.",
		"Os botões recebem nome pelo decrementLabel e pelo incrementLabel; o padrão é em inglês, então passe os traduzidos.",
		"No limite, o botão correspondente fica desativado, então ele nunca falha em silêncio.",
		"Ele usa inputmode=\"numeric\", então o celular abre o teclado numérico; com passo ou format fracionário e min ≥ 0, usa \"decimal\", que traz a vírgula.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Field", description: "Rótulo, descrição e erro para um controle.", href: "/pt-br/docs/components/field" },
		{ title: "Slider", description: "Escolha um valor num intervalo arrastando.", href: "/pt-br/docs/components/slider" },
		{ title: "Native select", description: "Escolha um valor de uma lista fixa.", href: "/pt-br/docs/components/native-select" },
	]}
/>


# OTP field (/pt-br/docs/components/otp-field)

<ComponentMeta file="otp-field" primitive="Base UI" pattern="HTML input (autocomplete=one-time-code)" />

<Playground
	name="otp-field/playground"
	component="OtpField"
	controls={[
		{ prop: "mask", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Coloque dentro de um `Field` para dar um rótulo.

<Import names="OtpField, Field, FieldLabel" />

## Anatomia [#anatomia]

Uma fileira de casas, cada uma um input. O `separator` põe um traço entre os grupos, só para os olhos.

<Anatomy
	keys={[
		{ label: '[data-slot="otp-field"]', color: "#8be36f" },
		{ label: '[data-slot="otp-separator"]', color: "#ffcf7a" },
		{ label: '[data-slot="otp-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">4</span>
	<span className="a-label">8</span>
	<span className="a-label">2</span>
	<span className="a-part">–</span>
	<span className="a-label">9</span>
	<span className="a-label">1</span>
	<span className="a-label">3</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="otp-field/basic" compact />

<ExampleGrid>
	<Example name="otp-field/verify" title="Colar, verificar e erro">
		Cole um código. O `onValueComplete` roda quando a última casa é preenchida, então você confere na hora; um código errado marca todas as casas como inválidas.
	</Example>
	<Example name="otp-field/expired" title="Código vencido">
		Quando o servidor recusa o código, use `invalid` no `Field` e diga o que fazer em seguida, não só que falhou.
	</Example>
	<Example name="otp-field/auto-submit" title="Enviar ao completar">
		Digite seis dígitos. O `autoSubmit` envia o formulário no último, e o `name` manda o código inteiro por um input oculto.
	</Example>
	<Example name="otp-field/pin-mask" title="Senha mascarada">
		O `mask` esconde cada dígito depois de digitado. Use para uma senha que alguém poderia ver por cima do ombro, não para um código que vence em minutos.
	</Example>
	<Example name="otp-field/recovery-code" title="Letras e números">
		O `validationType="alphanumeric"` aceita letras e abre o teclado completo; o `normalizeValue` passa tudo para maiúsculas, então "k7p" confere.
	</Example>
	<Example name="otp-field/cell-labels" title="Nomes das casas traduzidos">
		A primeira casa usa o rótulo do `Field` e as outras recebem o `getCellLabel`, então passe um no idioma da página.
	</Example>
	<Example name="otp-field/disabled" title="Desativado durante o envio">
		Desative enquanto um código novo está a caminho e diga isso na descrição, para ninguém digitar o antigo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="otp-field/context-two-factor" title="Verificação em duas etapas" uses="Card · Field · OtpField · Link · Button" />
	<Context name="otp-field/context-phone" title="Confirmar o celular" uses="Card · Field · OtpField · Button" />
	<Context name="otp-field/context-transfer" title="Confirmar um Pix" uses="Card · Field · OtpField · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="otp-field/do-say-where" title="Diga para onde o código foi.">
		A pessoa sabe qual app abrir e percebe um número errado.
	</Guideline>
	<Guideline kind="dont" name="otp-field/dont-bare" title="Só &quot;Código&quot;.">
		Do e-mail, do SMS ou do autenticador? A pessoa troca de app para adivinhar.
	</Guideline>
	<Guideline kind="do" name="otp-field/do-visible" title="Mostre os dígitos enquanto a pessoa digita.">
		Ela compara com o SMS num relance.
	</Guideline>
	<Guideline kind="dont" name="otp-field/dont-mask" title="Mascarar um código de uso único.">
		Ele vence em minutos e só vale uma vez; esconder só dificulta achar o erro de digitação.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="otp-field"
	type="OtpFieldProps"
	include={["length", "value", "defaultValue", "onValueChange", "onValueComplete", "validationType", "normalizeValue", "mask", "autoSubmit", "autoComplete", "name", "required", "disabled"]}
	types={{ getCellLabel: "(index: number, length: number) => string", onValueChange: "(value: string, details) => void", onValueComplete: "(value: string, details) => void", normalizeValue: "(value: string) => string", validationType: "\"numeric\" | \"alpha\" | \"alphanumeric\" | \"none\"" }}
	describe={{ separator: "Desenha um separador a cada `separator` casas (3 → 123–456).", getCellLabel: "Nome acessível das casas a partir da segunda (traduzível). A primeira usa o rótulo do campo, então dê nome ao campo inteiro com `Field` + `FieldLabel`.", length: "Quantidade de casas.", value: "O código, controlado.", defaultValue: "O código inicial, não controlado.", onValueChange: "Roda a cada mudança, ao digitar, colar ou pelo teclado. `details.reason` diz qual.", onValueComplete: "Roda quando todas as casas estão preenchidas, depois do `onValueChange`. Confira o código aqui.", validationType: "Quais caracteres são aceitos. Também escolhe o teclado do celular.", normalizeValue: "Transforma o valor depois do filtro, por exemplo para maiúsculas. Deve dar o mesmo resultado se rodar duas vezes.", mask: "Esconde os caracteres digitados, como num campo de senha.", autoSubmit: "Envia o formulário quando o código fica completo.", autoComplete: "O atributo autocomplete da primeira casa. Mantenha `one-time-code` para códigos por SMS e e-mail.", name: "Identifica o código no envio do formulário.", required: "Exige um valor antes de enviar o formulário.", disabled: "Desativa todas as casas." }}
>
	As outras props da raiz do Base UI também funcionam, como `readOnly`, `inputMode`, `form` e `onValueInvalid`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio campo.

<StylingHooks
	slots={["otp-field", "otp-input", "otp-separator"]}
	prefix="otp"
	attributes={[
		{ attr: "data-slot", value: '"otp-field" · "otp-input" · "otp-separator"' },
		{ attr: "data-filled", value: "numa casa com caractere; na raiz quando alguma casa tem um" },
		{ attr: "data-complete", value: "presente quando todas as casas estão preenchidas" },
		{ attr: "data-invalid", value: "presente quando o Field é inválido" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-focused", value: "presente enquanto alguma casa tem foco" },
	]}
>

```css
/* casas menores, só na tela de pagamento */
.payment-sheet [data-slot="otp-field"] {
  --cml-otp-cell-width: 2.25rem;
  --cml-otp-cell-height: 2.5rem;
  --cml-otp-gap: 0.375rem;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "0–9 · letras", description: "Preenche a casa e passa para a próxima. Caracteres que o validationType recusa são ignorados." },
		{ key: "Backspace", description: "Apaga a casa e volta para a anterior." },
		{ key: "Arrow Left · Arrow Right", description: "Anda entre as casas sem mudar nada." },
		{ key: "Ctrl + V · Cmd + V", description: "Cola o código inteiro e preenche todas as casas a partir da primeira." },
		{ key: "Tab", description: "Leva o foco para o campo e depois para o próximo controle." },
	]}
	notes={[
		"A primeira casa recebe o nome do rótulo do Field; as outras, do getCellLabel, que vem em inglês por padrão (\"Character 2 of 6\").",
		"O autocomplete=\"one-time-code\" vem ligado, então iOS e Android oferecem o código do SMS acima do teclado. Mantenha para códigos por SMS e e-mail.",
		"O separador é aria-hidden: o leitor de tela ouve as casas, não os traços.",
		"Um Field inválido marca aria-invalid em todas as casas, e cada casa é descrita pelo FieldDescription e pelo FieldError. Deixe o erro logo abaixo delas, onde a pessoa olha depois de digitar.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Field", description: "Rótulo, descrição e erro de um controle.", href: "/pt-br/docs/components/field" },
		{ title: "Input group", description: "Inputs com complementos, senha e busca.", href: "/pt-br/docs/components/input-group" },
		{ title: "Error summary", description: "Lista os erros do formulário depois do envio.", href: "/pt-br/docs/components/error-summary" },
	]}
/>


# Pagination (/pt-br/docs/components/pagination)

<ComponentMeta file="pagination" pattern="WAI-ARIA Landmark (navigation)" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O `DataTable` já traz a paginação; use ela sozinha para qualquer outra lista.

<Import names="Pagination" />

## Anatomia [#anatomia]

Um landmark `nav` em volta de uma lista. O primeiro e o último itens são Anterior e Próxima; entre eles, os números das páginas e os intervalos. A quantidade de itens não muda quando a página muda, então o controle não pula de largura.

<Anatomy
	tree={{
		slot: "pagination",
		tag: "nav",
		note: "aria-label, contém um ul",
		row: true,
		children: [
			{ slot: "pagination-item", tag: "a | button", note: "Anterior" },
			{ slot: "pagination-item", tag: "a | button", note: "aria-current=page" },
			{ slot: "pagination-ellipsis", tag: "li", note: "aria-hidden" },
			{ slot: "pagination-item", tag: "a | button", note: "última página" },
			{ slot: "pagination-item", tag: "a | button", note: "Próxima" },
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor da marca escolhidos na barra acima.

<Preview name="pagination/basic" compact />

<ExampleGrid>
	<Example name="pagination/with-links" title="Links, para páginas que se compartilham" wide>
		Passe `getHref` quando cada página tiver sua própria URL: os buscadores seguem os links, e as pessoas podem abrir uma página em outra aba ou compartilhar.
	</Example>
	<Example name="pagination/results" title="Uma lista no navegador">
		Mude de página. Com `onPageChange` os números são botões; o foco fica no que você apertou, e uma mensagem de status diz "Página 3 de 10".
	</Example>
	<Example name="pagination/compact" title="Compacta, para celular">
		Com setas em texto e uma vizinha, a fileira quebra em duas linhas abaixo de uns 420px. `siblings={0}` e os nomes das setas em `VisuallyHidden` deixam ela abaixo de 310px em todos os estilos, numa linha só num celular de 390px; o total vai para o texto acima.
	</Example>
	<Example name="pagination/page-size" title="Com tamanho da página e contagem" wide>
		Mude as linhas por página. "Mostrando 21–40 de 312" diz quanto conteúdo há, e a nova página mantém a primeira linha que você estava vendo.
	</Example>
	<Example name="pagination/first-last" title="Primeira e última sempre à vista" wide>
		A primeira e a última páginas nunca saem da fileira, então um só toque volta ao início ou vai direto ao fim de 48 páginas.
	</Example>
	<Example name="pagination/siblings" title="Vizinhas" wide>
		`siblings` define quantas páginas aparecem de cada lado da atual. Use 0 em lugares estreitos e 2 quando as pessoas costumam pular algumas páginas.
	</Example>
	<Example name="pagination/labels" title="Nomes para o leitor de tela" wide>
		Traduza o `aria-label`, as setas e o `pageLabel`. Com o total no `pageLabel`, cada número é lido como "Página 3 de 12".
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Estas são partes inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="pagination/context-blog" title="Arquivo do blog" uses="Card · Link · Badge · Pagination" />
	<Context name="pagination/context-orders" title="Tabela de pedidos" uses="Table · Badge · NativeSelect · Pagination" />
	<Context name="pagination/context-search" title="Resultados de busca" uses="SearchInput · Link · Pagination · VisuallyHidden" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="pagination/do-count" title="Diga onde a pessoa está e quanto há.">
		A página atual e "Mostrando 21–40 de 312" respondem às duas perguntas antes que alguém faça.
	</Guideline>
	<Guideline kind="dont" name="pagination/dont-bare" title="Só Anterior e Próxima.">
		Sem o número da página nem um total, a pessoa não sabe quanto já andou nem quanto falta.
	</Guideline>
	<Guideline kind="do" name="pagination/do-whole-list" title="Mostre uma lista curta inteira.">
		Cinco nomes cabem na tela. Ler todos leva menos tempo do que achar a próxima página.
	</Guideline>
	<Guideline kind="dont" name="pagination/dont-tiny" title="Paginar uma lista minúscula.">
		Três páginas de dois nomes escondem quase toda a lista atrás de cliques, e o Ctrl+F para de encontrá-los.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="pagination"
	type="PaginationProps"
	types={{ previousLabel: "ReactNode", nextLabel: "ReactNode" }}
	describe={{
		page: "A página atual, a partir de 1.",
		count: "O total de páginas.",
		siblings: "Páginas mostradas de cada lado da atual. A primeira e a última sempre aparecem.",
		getHref: "Renderiza links (que os buscadores seguem e que abrem em outra aba). Passe esta ou `onPageChange`.",
		onPageChange: "Renderiza botões e é chamada com a página escolhida, para estado no cliente.",
		previousLabel: "Conteúdo do controle de página anterior, depois da seta. Traduza.",
		nextLabel: "Conteúdo do controle de próxima página, antes da seta. Traduza.",
		"aria-label": "Nome acessível do landmark `nav`. Use um nome único quando a página tiver mais de uma paginação.",
		pageLabel: "Nome acessível de cada número de página. Traduza.",
	}}
>
	As demais props vão para o `nav`. Passe `getHref` (links) ou `onPageChange` (botões).
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria paginação.

<StylingHooks
	slots={["pagination", "pagination-item", "pagination-ellipsis"]}
	attributes={[
		{ attr: "aria-current", value: '"page" na página atual' },
		{ attr: "aria-disabled", value: '"true" em Anterior na página 1 e em Próxima na última' },
	]}
>

```css
/* números quadrados na tabela de pedidos */
.orders [data-slot="pagination-item"] {
  --cml-radius-control: 4px;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa por Anterior, cada número de página e Próxima, em ordem. Os intervalos … são pulados." },
		{ key: "Shift + Tab", description: "Volta pelos mesmos controles." },
		{ key: "Enter", description: "Vai para a página focada. Com botões, o Espaço também." },
		{ key: "Enter em Próxima na última página", description: "Com botões, não faz nada e o foco fica em Próxima: ela tem aria-disabled, não disabled. Com links, o controle da ponta não tem href e o Tab pula ele." },
	]}
	notes={[
		"É um landmark nav. Dê a ele o nome do que ele pagina (\"Páginas de pedidos\") e use um nome único quando a página tiver duas paginações.",
		"A página atual tem aria-current=\"page\". Cada número recebe o nome de pageLabel, \"Page 3\" por padrão; os intervalos … ficam escondidos do leitor de tela.",
		"Com onPageChange, o foco fica no controle apertado, para a pessoa continuar paginando. Anuncie a mudança numa mensagem role=\"status\" (\"Página 3 de 12\"); a lista atualizada está logo acima.",
		"Com getHref, cada página é uma nova URL e um carregamento completo; deixe o título da página dizer qual é (\"Pedidos, página 3 de 12\").",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "DataTable", description: "Ordenação, seleção e paginação para dados em tabela.", href: "/pt-br/docs/components/data-table" },
		{ title: "Breadcrumb", description: "Onde uma página fica na hierarquia do site.", href: "/pt-br/docs/components/breadcrumb" },
		{ title: "Native select", description: "A escolha de linhas por página ao lado dela.", href: "/pt-br/docs/components/native-select" },
	]}
/>


# Popover (/pt-br/docs/components/popover)

<ComponentMeta file="popover" primitive="Base UI" pattern="WAI-ARIA Dialog (non-modal)" />

<Playground
	name="popover/playground"
	component="Popover"
	controls={[{ prop: "modal", default: false }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose" />

## Anatomia [#anatomia]

O `PopoverContent` é renderizado num portal, com o estilo, o modo e a cor da página em volta do gatilho. Ele abre embaixo do gatilho, alinhado ao início dele (mude com `side` e `align`), e vai para o outro lado quando não há espaço. A seta está sempre lá. O seu conteúdo fica dentro do `popover-scroll`, então ponha o layout (grid, gap) num wrapper seu ou nesse slot, não no `PopoverContent`.

<Anatomy
	tree={{
		slot: "popover-positioner",
		tag: "div",
		note: "num portal",
		children: [
			{
				slot: "popover-popup",
				tag: "div",
				note: "role=dialog",
				children: [
					{ slot: "popover-arrow", tag: "div", note: "aponta para o gatilho" },
					{
						slot: "popover-scroll",
						tag: "div",
						note: "rola quando passa da altura da tela",
						children: [
							{ slot: "popover-title", tag: "h2", note: "dá nome ao diálogo" },
							{ slot: "popover-description", tag: "p", note: "opcional" },
							{ slot: "popover-close", tag: "button", note: "opcional" },
						],
					},
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Todos começam fechados: abra e teste Tab, Escape e um clique fora.

<Preview name="popover/basic" compact />

<ExampleGrid>
	<Example name="popover/rename" title="Um formulário curto">
		Clique em Renomear. O `initialFocus` põe o cursor no campo, Enter salva, e o foco volta para o botão enquanto uma mensagem de status confirma o novo nome.
	</Example>
	<Example name="popover/notifications" title="Controlado">
		Com `open` e `onOpenChange` você sabe quando ele fecha. Aqui isso marca as notificações como lidas e avisa.
	</Example>
	<Example name="popover/a11y-icon" title="A partir de um botão de ícone">
		O botão de ícone precisa de `aria-label`; o `PopoverTitle` dá nome ao painel. O leitor de tela avisa que ele abre um diálogo e se está expandido.
	</Example>
	<Example name="popover/with-close" title="Com botão de fechar">
		Celular não tem tecla Escape. Um `PopoverClose` com um × visível dá a todo mundo um jeito de sair.
	</Example>
	<Example name="popover/live-settings" title="Configurações que valem na hora">
		A página continua visível e usável atrás do popover, então as mudanças aparecem na hora, sem botão Aplicar.
	</Example>
	<Example name="popover/trap-focus" title="Foco preso dentro">
		Normalmente o Tab sai do popover e fecha ele. Com `modal="trap-focus"`, o Tab dá a volta por dentro, e o que já foi digitado não se perde.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="popover/context-share" title="Compartilhar um documento" uses="Popover · Switch · Field · Input · Button" />
	<Context name="popover/context-columns" title="Colunas da tabela" uses="Popover · CheckboxGroup · Table" />
	<Context name="popover/context-snooze" title="Adiar um lembrete" uses="Card · Popover · RadioGroup · Badge" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="popover/do-menu" title="Lista de comandos é um menu.">
		O `Menu` traz setas, busca pela primeira letra e os papéis certos para Editar, Duplicar e Excluir.
	</Guideline>
	<Guideline kind="dont" name="popover/dont-action-list" title="Um popover cheio de botões.">
		Cada um vira uma parada do Tab, e o leitor de tela anuncia um diálogo em vez de um menu.
	</Guideline>
	<Guideline kind="do" name="popover/do-tooltip" title="Um tooltip para um nome.">
		Passar o mouse ou dar foco mostra "Arquivar" na hora, e é o mesmo texto que o leitor de tela fala.
	</Guideline>
	<Guideline kind="dont" name="popover/dont-popover-label" title="Um clique para ler um rótulo.">
		Se ele só explica o botão, ninguém deveria precisar abrir e fechar um painel. Popover é para conteúdo com que a pessoa interage.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="popover"
	type="PopoverProps"
	include={["open", "defaultOpen", "onOpenChange", "modal"]}
	types={{ onOpenChange: "(open, eventDetails) => void" }}
	describe={{
		open: "Se o popover está aberto. Use junto com `onOpenChange` para controlar pelo código.",
		defaultOpen: "Se o popover começa aberto, sem controle pelo código.",
		onOpenChange: "Chamado quando o popover abre ou fecha, com o motivo em `eventDetails`.",
		modal: "`true` prende o foco, trava a rolagem e bloqueia cliques fora. `\"trap-focus\"` só prende o foco. O padrão é `false`.",
	}}
>
	O `PopoverContent` aceita `side`, `align` e as props do popup, incluindo `initialFocus` e `finalFocus`. O `PopoverTrigger` aceita `openOnHover` e `delay` para um painel que também abre com o mouse por cima; mantenha o clique, para funcionar no toque e no teclado.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio popup.

<StylingHooks
	slots={["popover-trigger", "popover-positioner", "popover-popup", "popover-arrow", "popover-scroll", "popover-title", "popover-description", "popover-close"]}
	attributes={[
		{ attr: "data-side", value: "bottom · top · left · right" },
		{ attr: "data-align", value: "start · center · end" },
		{ attr: "data-open · data-closed", value: "no popup" },
		{ attr: "data-starting-style · data-ending-style", value: "enquanto aparece e some" },
	]}
>

```css
/* um painel mais largo para o popover de compartilhar */
.share [data-slot="popover-popup"] {
  inline-size: min(26rem, calc(100vw - 2rem));
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "No gatilho, abre o popover e leva o foco para o primeiro controle, para o initialFocus, ou para o painel quando ele não tem controles." },
		{ key: "Tab", description: "Passa pelos controles. Depois do último, o foco vai para o que vem depois do gatilho e o popover fecha." },
		{ key: "Shift + Tab", description: "Do primeiro controle, volta para o gatilho; o popover continua aberto." },
		{ key: "Escape", description: "Fecha o popover e devolve o foco ao gatilho." },
	]}
	notes={[
		"Ele nunca passa do espaço na tela: daí em diante, o conteúdo rola dentro dele e a seta fica no lugar. Só com texto dentro, a caixa que rola vira uma parada de Tab para quem usa teclado conseguir rolar.",
		"É um diálogo não modal: o resto da página continua alcançável. Um clique fora fecha o popover.",
		"O gatilho tem aria-haspopup=\"dialog\" e aria-expanded, então o leitor de tela sabe o que abre e se está aberto.",
		"O PopoverTitle dá nome ao diálogo. Coloque um mesmo quando o painel é pequeno.",
		"O resultado de uma ação feita nele vai numa mensagem de status: o popover fecha e leva o texto junto.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Tooltip", description: "Um rótulo curto no hover ou no foco, nunca interativo.", href: "/pt-br/docs/components/tooltip" },
		{ title: "Menu", description: "Uma lista de comandos navegável pelas setas.", href: "/pt-br/docs/components/menu" },
		{ title: "Drawer", description: "Um painel maior que vem da borda, para tarefas mais longas.", href: "/pt-br/docs/components/drawer" },
	]}
/>


# ProgressCircle (/pt-br/docs/components/progress-circle)

<ComponentMeta file="data-display" primitive="Anel SVG" pattern="WAI-ARIA progressbar" />

<Playground
	name="progress-circle/playground"
	component="ProgressCircle"
	controls={[
		{ prop: "tone", options: ["brand", "warning", "danger"], default: "brand" },
		{ prop: "showValue", default: true },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="ProgressCircle" />

## Anatomia [#anatomia]

Uma raiz com o papel progressbar guarda o anel (um SVG com a trilha e o arco, e o valor por cima) e um rótulo opcional embaixo. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "progress-circle",
		tag: "div",
		note: "role progressbar",
		children: [
			{
				slot: "progress-circle-ring",
				tag: "div",
				children: [
					{
						slot: "progress-circle-svg",
						tag: "svg",
						row: true,
						children: [
							{ slot: "progress-circle-track", tag: "circle" },
							{ slot: "progress-circle-indicator", tag: "circle" },
						],
					},
					{ slot: "progress-circle-value", tag: "span", note: "some enquanto ocupado" },
				],
			},
			{ slot: "progress-circle-label", tag: "span", note: "opcional" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a marca da barra acima.

<Preview name="progress-circle/basic" compact />

<ExampleGrid>
	<Example name="progress-circle/tones" title="Travada ou com falha">
		Use `tone="warning"` quando a tarefa travar e `tone="danger"` quando ela falhar. Diga o motivo no rótulo também, para a cor não ser o único sinal.
	</Example>
	<Example name="progress-circle/sizes" title="Tamanhos">
		Mude `size` e `strokeWidth` juntos. Um traço fino num anel grande fica apagado, e um grosso num anel pequeno aperta o número.
	</Example>
	<Example name="progress-circle/indeterminate" title="Duração desconhecida">
		Passe `value={null}` quando ainda não der para medir o trabalho: o número some e o arco gira (ele pulsa com movimento reduzido). Deixar `value` de fora não é a mesma coisa, significa 0%.
	</Example>
	<Example name="progress-circle/custom-label" title="Contagem em vez de porcentagem">
		Defina `max` com o total real e mostre "3/5" em `valueLabel`. O `getAriaValueText` dá ao leitor de tela as palavras, "3 de 5 aulas", em vez de "60%".
	</Example>
	<Example name="progress-circle/inline" title="Anel pequeno ao lado do texto">
		Abaixo de uns 40 px o número não cabe. Esconda-o com `showValue={false}`, escreva o valor ao lado do anel e dê um nome a ele com `aria-label`.
	</Example>
	<Example name="progress-circle/meter" title="Uma medida, não uma tarefa">
		O armazenamento usado nunca caminha para "concluído". Passe `role="meter"` para o leitor de tela não anunciar isso como uma tarefa em andamento.
	</Example>
	<Example name="progress-circle/interactive-upload" title="Avise quando terminar">
		Clique até terminar. O leitor de tela não anuncia cada mudança do anel, então uma mensagem com `role="status"` avisa quando todas as fotos chegaram.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O anel cabe onde uma barra ficaria larga demais: ao lado de um título, num card ou numa fileira de metas. Estas são peças inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="progress-circle/context-upload" title="Envio em andamento" uses="Card · ProgressCircle · Button" />
	<Context name="progress-circle/context-fitness" title="Metas do dia" uses="Card · ProgressCircle" />
	<Context name="progress-circle/context-course" title="Card de curso" uses="Card · ProgressCircle · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="progress-circle/do-accessible-label" title="Diga o que está rodando.">
		"Importando contatos" diz à pessoa o que ela está esperando, e vira o nome acessível do anel.
	</Guideline>
	<Guideline kind="dont" name="progress-circle/dont-unlabeled-circle" title="Um anel só com o número.">
		40% de quê? Sem rótulo, a pessoa não sabe qual tarefa ele acompanha, e o leitor de tela só diz "Progresso".
	</Guideline>
	<Guideline kind="do" name="progress-circle/do-tone-problem" title="Guarde o vermelho para um problema real.">
		Um anel vermelho ao lado de "O envio falhou" leva a pessoa direto ao que precisa dela.
	</Guideline>
	<Guideline kind="dont" name="progress-circle/dont-static-danger" title="Vermelho para uma tarefa que só está rodando.">
		Uma configuração de perfil em 25% é normal. Vermelho ali ensina a pessoa a ignorar o vermelho quando algo quebrar de verdade.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="ProgressCircleProps"
	include={["value", "min", "max", "size", "strokeWidth", "tone", "label", "showValue", "valueLabel", "getAriaValueText"]}
	types={{ value: "number | null" }}
	describe={{
		value: "Quanto a tarefa avançou, entre `min` e `max` (limitado a eles). `null` indica duração desconhecida e o anel gira; deixar de fora significa 0.",
		min: "Valor mínimo da escala.",
		max: "Valor máximo da escala.",
		size: "Diâmetro externo do anel, em pixels.",
		strokeWidth: "Espessura da trilha e do arco, em pixels.",
		tone: "Cor do arco: `warning` quando a tarefa trava, `danger` quando falha.",
		label: "Texto abaixo do anel, que também dá nome a ele para o leitor de tela, a menos que `aria-label` exista. Sem nenhum dos dois, o nome é \"Progresso\" (ou o texto do `MessagesProvider`).",
		showValue: "Mostra o valor dentro do anel. Fica sempre escondido enquanto `value` é `null`.",
		valueLabel: "Texto visível que substitui a porcentagem, como \"3/5\". Uma string também é o que o leitor de tela ouve; senão, passe `getAriaValueText`.",
		getAriaValueText: "O que o leitor de tela ouve como valor (`aria-valuetext`). Recebe a porcentagem mostrada (como \"40%\") e o valor, os dois `null` enquanto indeterminado. Padrão: o `valueLabel` quando é string; senão, a porcentagem.",
	}}
>
	Os atributos nativos de `<div>` são repassados, como `aria-label`, `aria-valuetext` e `role`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio anel.

<StylingHooks
	slots={[
		"progress-circle",
		"progress-circle-ring",
		"progress-circle-svg",
		"progress-circle-track",
		"progress-circle-indicator",
		"progress-circle-value",
		"progress-circle-label",
	]}
	prefix="progress-circle"
	attributes={[
		{ attr: "data-tone", value: "brand · warning · danger, na raiz e no indicador" },
		{ attr: "data-indeterminate", value: "presente quando value é null" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "Não recebe foco. Ele informa um estado; os controles ao redor recebem o foco." }]}
	notes={[
		"Renderiza role=\"progressbar\" com aria-valuenow, aria-valuemin e aria-valuemax. O label dá o nome (qualquer conteúdo, não só string); sem label nem aria-label, o nome é só \"Progresso\", vindo do MessagesProvider.",
		"O leitor de tela ouve a porcentagem, ou o valueLabel quando é string. Quando não é, ou quando o texto visível é curto como \"3/5\", passe getAriaValueText para o leitor de tela ouvir a frase inteira.",
		"Com value={null}, aria-valuenow fica de fora, o que avisa a tecnologia assistiva que a duração é desconhecida.",
		"As mudanças não são anunciadas. Quando a tarefa terminar ou falhar, diga isso numa mensagem de status (role=\"status\").",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Progress", href: "/pt-br/docs/components/progress", description: "O mesmo retorno como uma barra inteira, com rótulo e valor em cima." },
		{ title: "Meter", href: "/pt-br/docs/components/meter", description: "Uma medida numa faixa conhecida, como o armazenamento usado." },
		{ title: "Spinner", href: "/pt-br/docs/components/spinner", description: "Sinal de carregamento para um botão ou uma área pequena, sem valor." },
	]}
/>


# Progress (/pt-br/docs/components/progress)

<ComponentMeta file="progress" primitive="Base UI" pattern="WAI-ARIA progressbar" />

<Playground
	name="progress/playground"
	component="Progress"
	controls={[
		{ prop: "showValue", default: true },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O estilo carregado cuida do visual.

<Import names="Progress" />

## Anatomia [#anatomia]

Uma raiz com um cabeçalho (rótulo e valor) e um trilho com o preenchimento. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="progress"]', color: "#8be36f" },
		{ label: '[data-slot="progress-track"] · [data-slot="progress-indicator"]', color: "#ffcf7a" },
		{ label: "rótulo · valor", color: "#7cc7ff" },
	]}
>
	<span className="a-part">trilho</span>
	<span className="a-part">preenchimento</span>
	<span className="a-label">Enviando nota-marco.pdf 65%</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="progress/basic" compact />

<ExampleGrid>
	<Example name="progress/indeterminate" title="Duração desconhecida">
		Quando ainda não dá para medir o trabalho, passe `value={null}`. O número some, um trecho desliza pela trilha (com movimento reduzido, ele pulsa no lugar) e o leitor de tela entende que a barra está ocupada, não parada em 0%.
	</Example>
	<Example name="progress/interactive-upload" title="Etapa por etapa">
		Clique para avançar. Dizer a etapa atual no `valueLabel` mostra o que está acontecendo, e não só quanto falta.
	</Example>
	<Example name="progress/custom-value" title="Quantidade em vez de porcentagem">
		Use o total real em `max` e mostre "16 de 20 fotos". Itens são mais fáceis de entender do que uma porcentagem.
	</Example>
	<Example name="progress/steps" title="Etapas de uma configuração">
		Num assistente curto, `value={3}` com `max={5}` vira "Etapa 3 de 5", e a pessoa sabe quanto falta.
	</Example>
	<Example name="progress/value-text" title="O que o leitor de tela ouve">
		O `valueLabel` muda só o texto visível. Passe também o `getAriaValueText`, para "1,2 de 3 GB" ser lido por extenso, e não como "40 por cento".
	</Example>
	<Example name="progress/upload-list" title="Lista de envios" wide>
		Uma barra por arquivo, cada uma com o nome dele, para a pessoa ver qual terminou, qual está enviando e qual está na fila.
	</Example>
	<Example name="progress/cancel" title="Com opção de cancelar">
		Clique. Tarefa longa precisa de uma saída. Depois de cancelar, diga o que aconteceu numa mensagem de status e ofereça tentar de novo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

A barra de progresso fica junto da tarefa que ela acompanha. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="progress/context-file-upload" title="Fila de envio" uses="Card · Progress · Button" />
	<Context name="progress/context-onboarding" title="Configuração do perfil" uses="Card · Progress · Button" />
	<Context name="progress/context-import" title="Importação de contatos" uses="Card · Progress · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="progress/do-label" title="Diga o que está rodando.">
		"Baixando a atualização 4.2" mostra pelo que a pessoa está esperando e ainda dá nome à barra para o leitor de tela.
	</Guideline>
	<Guideline kind="dont" name="progress/dont-unlabeled" title="Só um verbo e nenhum número.">
		Baixando o quê? Sem nome e sem valor, ninguém sabe se vale a pena esperar.
	</Guideline>
	<Guideline kind="do" name="progress/do-real-steps" title="Sem estimativa? Mostre que está ocupado.">
		Se não dá para medir o trabalho, use `value={null}` em vez de chutar um número.
	</Guideline>
	<Guideline kind="dont" name="progress/dont-fake-progress" title="Não invente uma porcentagem.">
		Uma barra que corre até 99% e para ali quebra a confiança. A pessoa desiste de uma barra em que não acredita.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="progress" type="ProgressProps" include={["value", "min", "max", "getAriaValueText", "format", "locale"]}
	types={{ value: "number | null", getAriaValueText: "(formattedValue, value) => string", format: "Intl.NumberFormatOptions", locale: "Intl.LocalesArgument" }}
	describe={{
		label: "Rótulo visível. Também é o nome da barra para o leitor de tela.",
		showValue: "Mostra o valor ao lado do rótulo.",
		valueLabel: "Troca o texto do valor, por exemplo por \"16 de 20 fotos\". Muda só o que aparece na tela.",
		value: "Quanto da tarefa já foi feito, entre `min` e `max`. `null` quer dizer que a duração é desconhecida.",
		min: "Valor do começo da tarefa.",
		max: "Valor da tarefa concluída. Use o total real, como o número de arquivos.",
		getAriaValueText: "O texto que o leitor de tela ouve para o valor. Por padrão, a porcentagem.",
		format: "Opções de Intl.NumberFormat para o valor formatado.",
		locale: "Idioma usado para formatar o valor.",
	}}
>
	As outras props da raiz de progresso do Base UI e os atributos nativos de `<div>` passam direto.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["progress", "progress-header", "progress-value", "progress-track", "progress-indicator"]}
	attributes={[
		{ attr: "data-progressing", value: "presente enquanto a tarefa roda" },
		{ attr: "data-complete", value: "presente quando value chega ao max" },
		{ attr: "data-indeterminate", value: "presente quando value é null" },
		{ attr: "data-slot", value: '"progress" · "progress-track" · "progress-indicator"' },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "Não recebe foco. Ela só informa o andamento; os controles ao redor é que recebem o foco." }]}
	notes={[
		"Renderiza role=\"progressbar\" com aria-valuenow, aria-valuemin e aria-valuemax, e o rótulo vira o nome acessível.",
		"Por padrão, o leitor de tela ouve a porcentagem. Quando o valor visível é uma quantidade ou um tamanho, passe o getAriaValueText para os dois dizerem a mesma coisa.",
		"Com value={null}, o aria-valuenow fica de fora, o que avisa a tecnologia assistiva que a duração é desconhecida.",
		"O leitor de tela não anuncia cada mudança. Quando a tarefa terminar ou falhar, avise numa mensagem de status (role=\"status\").",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Meter", href: "/pt-br/docs/components/meter", description: "Uma medida numa faixa conhecida, como o armazenamento usado." },
		{ title: "Spinner", href: "/pt-br/docs/components/spinner", description: "Indica que algo está ocupado num botão ou área pequena." },
		{ title: "File upload", href: "/pt-br/docs/components/file-upload", description: "Escolha arquivos para enviar, com o andamento de cada um." },
	]}
/>


# Radio group (/pt-br/docs/components/radio-group)

<ComponentMeta file="radio-group" primitive="Base UI" pattern="WAI-ARIA Radio Group" />

<Playground
	name="radio-group/playground"
	component="RadioGroup"
	controls={[
		{ prop: "disabled", default: false },
		{ prop: "readOnly", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Dê um nome ao grupo com `Fieldset` e `FieldsetLegend`, e envolva cada `Radio` num `Label`.

<Import names="RadioGroup, Radio, Fieldset, FieldsetLegend, Label" />

## Anatomia [#anatomia]

O `RadioGroup` guarda o valor. Cada `Radio` é um círculo com um ponto dentro, nomeado pelo `Label` em volta dele.

<Anatomy
	keys={[
		{ label: '[data-slot="radio-group"]', color: "#8be36f" },
		{ label: '[data-slot="radio"] · [data-slot="radio-indicator"]', color: "#ffcf7a" },
		{ label: 'texto do [data-slot="label"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">radio</span>
	<span className="a-label">Pro</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="radio-group/basic" compact />

<ExampleGrid>
	<Example name="radio-group/with-description" title="Com descrições">
		Quando só o nome não ajuda a escolher, ponha uma linha embaixo de cada opção e ligue com `aria-describedby`.
	</Example>
	<Example name="radio-group/controlled" title="Controlado">
		Clique numa opção. `value` e `onValueChange` deixam o resto da tela reagir, aqui o preço embaixo.
	</Example>
	<Example name="radio-group/required" title="Obrigatório, com erro">
		Envie sem escolher. Sem um padrão seguro, marque o grupo como `required` e diga o que fazer no `FieldError`.
	</Example>
	<Example name="radio-group/disabled-option" title="Uma opção desativada">
		Desative só a opção que não pode ser usada e diga como liberá-la. As setas pulam essa opção.
	</Example>
	<Example name="radio-group/horizontal" title="Em linha">
		Duas ou três opções curtas podem ficar lado a lado. Rótulos maiores se leem mais rápido em coluna.
	</Example>
	<Example name="radio-group/read-only" title="Somente leitura">
		Numa etapa de revisão, `readOnly` mostra a escolha e continua focável, ao contrário de `disabled`, que apaga o visual.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Um radio group faz uma pergunta por vez. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="radio-group/context-shipping" title="Tipo de entrega" uses="Card · RadioGroup · Separator · Button" />
	<Context name="radio-group/context-appearance" title="Ajustes de aparência" uses="Card · Fieldset · RadioGroup" />
	<Context name="radio-group/context-cancel" title="Pesquisa de cancelamento" uses="Card · RadioGroup · Textarea · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="radio-group/do-checkbox" title="Um checkbox para um único sim.">
		Dá para marcar e desmarcar de novo.
	</Guideline>
	<Guideline kind="dont" name="radio-group/dont-single" title="Um radio sozinho.">
		Depois de escolhido não dá para desfazer, então um radio solto prende a pessoa.
	</Guideline>
	<Guideline kind="do" name="radio-group/do-distinct" title="Opções que não se sobrepõem.">
		Cada resposta cabe em exatamente uma opção.
	</Guideline>
	<Guideline kind="dont" name="radio-group/dont-overlap" title="Faixas que dividem o limite.">
		Uma equipe de 10 cabe em duas opções, então a pessoa chuta.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="radio-group" type="RadioGroupProps" include={["value", "defaultValue", "onValueChange", "name", "required", "disabled", "readOnly"]}
	types={{ value: "any", defaultValue: "any", onValueChange: "(value, details) => void" }}
	describe={{ value: "O valor do radio escolhido (controlado). Para não controlar, use `defaultValue`.", defaultValue: "O valor escolhido no início (não controlado).", onValueChange: "Chamada quando a escolha muda.", name: "Nome do campo no envio do formulário.", required: "Se é preciso escolher uma opção para enviar o formulário.", disabled: "Ignora a interação em todas as opções.", readOnly: "Impede mudar a escolha, mas mantém o grupo focável e legível." }}
>
	O `Radio` recebe um `value` obrigatório (o que o grupo informa quando ele é escolhido) e `disabled`. Os atributos nativos passam direto.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio grupo.

<StylingHooks
	slots={["radio", "radio-indicator", "radio-group"]}
	prefix="radio"
	attributes={[
		{ attr: "data-slot", value: '"radio-group" · "radio" · "radio-indicator"' },
		{ attr: "data-checked", value: "presente no radio escolhido" },
		{ attr: "data-unchecked", value: "presente nos outros" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-readonly", value: "presente quando somente leitura" },
		{ attr: "data-invalid", value: "presente quando o Field está inválido" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco para dentro do grupo, no radio escolhido (ou no primeiro), e para fora de novo." },
		{ key: "Setas", description: "Vão para o radio anterior ou o próximo e o escolhem." },
		{ key: "Space", description: "Escolhe o radio com foco, se ainda não estiver escolhido." },
	]}
	notes={[
		"O grupo inteiro é uma parada de tabulação, então um formulário longo continua rápido de percorrer.",
		"Dê um nome a todo grupo: um FieldsetLegend, ou aria-labelledby apontando para um título visível.",
		"A área de toque tem pelo menos 24 × 24 px (WCAG 2.5.8) em todos os estilos, e o texto do rótulo também é clicável.",
		"Dentro de um Field, o erro fica ligado ao grupo pelo aria-describedby.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Checkbox", description: "Quantas opções quiser, ou um único sim.", href: "/pt-br/docs/components/checkbox" },
		{ title: "Select", description: "Uma escolha numa lista longa.", href: "/pt-br/docs/components/select" },
		{ title: "Toggle group", description: "Uma escolha como botões pressionados, para barras de ferramentas.", href: "/pt-br/docs/components/toggle" },
	]}
/>


# Range calendar (/pt-br/docs/components/range-calendar)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Grid" />

<Playground
	name="range-calendar/playground"
	component="RangeCalendar"
	controls={[
		{ prop: "weekdayStyle", options: ["narrow", "short", "long"], default: "short" },
		{ prop: "firstDayOfWeek", options: ["sun", "mon"], default: "sun" },
		{ prop: "allowsNonContiguousRanges", default: false },
		{ prop: "readOnly", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. As datas são objetos do `@internationalized/date`, reexportados pelo Camaleo.

<Import names="RangeCalendar, CalendarDate, isWeekend" />

## Anatomia [#anatomia]

As mesmas partes do `Calendar`. Os dias entre o início e o fim ganham o fundo do intervalo.

<Anatomy
	keys={[
		{ label: '[data-slot="range-calendar"]', color: "#8be36f" },
		{ label: '[data-slot="calendar-title"] · [data-slot="calendar-nav-button"] · [data-slot="calendar-footer"]', color: "#ffcf7a" },
		{ label: '[data-slot="calendar-grid"] · [data-slot="calendar-cell"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">título</span>
	<span className="a-part">‹ ›</span>
	<span className="a-label">início · intervalo · fim</span>
	<span className="a-part">rodapé</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="range-calendar/basic" compact />

<ExampleGrid>
	<Example name="range-calendar/nights" title="Controlado, com contagem de noites">
		Clique na entrada e depois na saída. `end.compare(start)` dá o número de noites, e o rodapé repete o período em palavras.
	</Example>
	<Example name="range-calendar/min-max" title="Mínimo e máximo">
		`minValue` e `maxValue` mantêm o intervalo dentro da temporada, e as setas param no primeiro e no último mês.
	</Example>
	<Example name="range-calendar/min-stay" title="Estadia mínima">
		Escolha uma noite só. Confira a duração no `onChange`, use `invalid` e diga a regra no rodapé, que é um status ao vivo.
	</Example>
	<Example name="range-calendar/booked" title="Noites reservadas">
		Tente passar pelo dia 20/10. Por padrão, um intervalo não atravessa dias indisponíveis, então ninguém reserva por cima de outro hóspede.
	</Example>
	<Example name="range-calendar/work-days" title="Atravessando fins de semana">
		`allowsNonContiguousRanges` deixa o intervalo passar por dias indisponíveis. Conte só os dias que importam, como os dias úteis de folga.
	</Example>
	<Example name="range-calendar/first-day" title="Semana começando na segunda">
		`firstDayOfWeek="mon"` faz uma sprint de duas semanas ocupar duas linhas inteiras.
	</Example>
	<Example name="range-calendar/read-only" title="Somente leitura">
		`readOnly` mostra uma hospedagem confirmada. A pessoa ainda percorre os dias pelo teclado e ouve as datas.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Intervalos movem reservas, pedidos e relatórios. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="range-calendar/context-hotel" title="Hospedagem com preço" uses="Card · RangeCalendar · Button" />
	<Context name="range-calendar/context-vacation" title="Pedido de férias" uses="Card · Badge · RangeCalendar · Button" />
	<Context name="range-calendar/context-report" title="Período de relatório com atalhos" uses="Card · ButtonGroup · RangeCalendar · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="range-calendar/do-summary" title="Resuma o intervalo em palavras.">
		"5 noites" confirma a escolha num relance e é lido pelo leitor de tela.
	</Guideline>
	<Guideline kind="dont" name="range-calendar/dont-no-summary" title="Só o destaque.">
		A pessoa conta as células para saber quanto escolheu, e erra por um.
	</Guideline>
	<Guideline kind="do" name="range-calendar/do-block-booked" title="Marque os dias reservados antes da escolha.">
		`isDateUnavailable` para o intervalo nas noites reservadas, e o rodapé diz o motivo.
	</Guideline>
	<Guideline kind="dont" name="range-calendar/dont-error-after" title="Recusar o intervalo depois de escolhido.">
		Todos os dias pareciam livres, então o erro pega de surpresa e a pessoa recomeça.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="RangeCalendarProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "isDateUnavailable", "allowsNonContiguousRanges", "firstDayOfWeek", "focusedValue", "defaultFocusedValue", "onFocusChange", "autoFocus"]}
	types={{ value: "{ start: DateValue; end: DateValue } | null", defaultValue: "{ start: DateValue; end: DateValue } | null", onChange: "(value: { start; end }) => void", minValue: "DateValue | null", maxValue: "DateValue | null", isDateUnavailable: "(date: DateValue) => boolean", firstDayOfWeek: "\"sun\" | \"mon\" | \"tue\" | \"wed\" | \"thu\" | \"fri\" | \"sat\"", focusedValue: "DateValue | null", defaultFocusedValue: "DateValue | null", onFocusChange: "(date: CalendarDate) => void" }}
	describe={{ className: "Classes do elemento raiz.", style: "Estilos inline do elemento raiz.", disabled: "Desativa todos os dias e as setas, e tira a grade da ordem do Tab.", readOnly: "Mostra o intervalo sem deixar a pessoa mudar. Os dias continuam focáveis.", invalid: "Marca o intervalo como inválido, para regras que a sua aplicação confere, como uma estadia mínima.", locale: "Idioma BCP 47 dos nomes dos meses, dos dias da semana e do primeiro dia da semana, como `\"pt-BR\"`. Por padrão, o do `I18nProvider` mais próximo ou o do navegador.", weekdayStyle: "Como os dias da semana aparecem no cabeçalho: `\"narrow\"`, `\"short\"` (padrão) ou `\"long\"`.", previousLabel: "Nome acessível da seta do mês anterior. Por padrão, o \"Anterior\" traduzido do React Aria.", nextLabel: "Nome acessível da seta do próximo mês. Por padrão, o \"Próximo\" traduzido do React Aria.", footer: "Conteúdo abaixo da grade: o período em palavras, as noites ou um total.", value: "O intervalo escolhido, com `start` e `end` (controlado).", defaultValue: "O intervalo escolhido no início (não controlado).", onChange: "Chamada quando a pessoa termina de escolher o intervalo.", minValue: "A primeira data que pode ser escolhida.", maxValue: "A última data que pode ser escolhida.", isDateUnavailable: "Devolve `true` para os dias que não podem ser escolhidos, como noites já reservadas.", allowsNonContiguousRanges: "Deixa o intervalo atravessar dias indisponíveis, como fins de semana numa folga.", firstDayOfWeek: "O dia que começa a semana. Por padrão, o do idioma.", focusedValue: "O dia focado (controlado). Define também o mês visível.", defaultFocusedValue: "O dia focado quando o calendário aparece (não controlado). Define o mês inicial.", onFocusChange: "Chamada quando o dia focado muda, inclusive ao trocar de mês.", autoFocus: "Foca o calendário ao montar." }}
>
	O tipo do valor é exportado como `DateRange`. As outras props de range calendar do React Aria passam direto, como `pageBehavior` e `createCalendar`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio calendário.

<StylingHooks
	slots={["range-calendar", "calendar-header", "calendar-title", "calendar-nav", "calendar-nav-button", "calendar-grid", "calendar-header-cell", "calendar-cell", "calendar-footer"]}
	prefix="calendar"
	attributes={[
		{ attr: "data-slot", value: '"range-calendar" · "calendar-header" · "calendar-grid" · "calendar-cell" · "calendar-footer"' },
		{ attr: "data-selected", value: "presente em todos os dias do intervalo" },
		{ attr: "data-selection-start · data-selection-end", value: "presente no primeiro · no último dia do intervalo" },
		{ attr: "data-today", value: "presente na data de hoje" },
		{ attr: "data-unavailable", value: "presente nos dias que o isDateUnavailable recusa" },
		{ attr: "data-disabled · data-outside-month", value: "presente nos dias fora do mínimo/máximo · nos dias de outro mês" },
	]}
>

```css
/* uma faixa mais suave entre as duas pontas */
.booking [data-slot="range-calendar"] {
  --cml-calendar-range-bg: color-mix(in oklab, var(--cml-accent) 8%, transparent);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Setas", description: "Movem o foco um dia, ou uma semana para cima e para baixo. Depois do primeiro clique, o intervalo acompanha o foco." },
		{ key: "Enter / Espaço", description: "Escolhe o início e depois o fim do intervalo." },
		{ key: "Escape", description: "Cancela um intervalo que tem início mas ainda não tem fim." },
		{ key: "Home / End", description: "Levam o foco ao primeiro ou ao último dia do mês." },
		{ key: "Page Up / Page Down", description: "Vão para o mês anterior ou o próximo. Com Shift, um ano." },
	]}
	notes={[
		"A grade é nomeada pelo aria-label mais o mês visível, e o intervalo escolhido é anunciado quando muda.",
		"Cada dia é anunciado com a data completa e se está escolhido, se é hoje ou se está indisponível.",
		"O intervalo aparece pelo destaque e pelo formato das pontas; ponha um resumo em texto no rodapé para nunca depender só da cor.",
		"Um intervalo não atravessa dias indisponíveis, a não ser com allowsNonContiguousRanges.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Calendar", description: "Escolha um dia só.", href: "/pt-br/docs/components/calendar" },
		{ title: "Date range picker", description: "Dois campos de data com este calendário num popover.", href: "/pt-br/docs/components/date-range-picker" },
		{ title: "Slider", description: "Escolha um intervalo de números.", href: "/pt-br/docs/components/slider" },
	]}
/>


# Rating (/pt-br/docs/components/rating)

<ComponentMeta file="rating" primitive="Base UI" pattern="WAI-ARIA Radio Group" />

<Playground
	name="rating/playground"
	component="Rating"
	controls={[
		{ prop: "readOnly", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. O estilo carregado desenha as estrelas.

<Import names="Rating" />

## Anatomia [#anatomia]

Interativo, a raiz é um grupo de rádios com um rádio por estrela. Somente leitura, a raiz é uma imagem e cada estrela é só uma forma.

<Anatomy
	keys={[
		{ label: '[data-slot="rating"]', color: "#8be36f" },
		{ label: '[data-slot="rating-item"] · [data-slot="rating-star"]', color: "#ffcf7a" },
		{ label: 'ícone da estrela: [data-slot="icon"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">★</span>
	<span className="a-part">★</span>
	<span className="a-part">★</span>
	<span className="a-label">☆</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="rating/basic" compact />

<ExampleGrid>
	<Example name="rating/read-only" title="Somente leitura, com o número">
		O `readOnly` transforma as estrelas numa única imagem com o nome do `getLabel`. Escreva a média e o total ao lado, para todo mundo comparar de relance.
	</Example>
	<Example name="rating/half" title="Meias estrelas">
		Na leitura, qualquer fração vira meia estrela, então 4,5 e 3,5 ficam diferentes. A versão interativa só aceita estrelas inteiras.
	</Example>
	<Example name="rating/caption" title="Com legenda">
		Escolha uma estrela. Palavras como "Boa" ou "Excelente" na legenda e no nome de cada estrela dizem o que a nota significa.
	</Example>
	<Example name="rating/required" title="Obrigatório numa avaliação">
		Envie sem estrela. Confira o valor no envio e mostre um `FieldError`; dentro de um `Field` a mensagem fica ligada ao grupo.
	</Example>
	<Example name="rating/in-list" title="Várias na mesma tela">
		Quando cada linha da lista tem uma nota, dê a cada uma um `aria-label` com o nome do item, senão o leitor de tela repete "Sua avaliação" três vezes.
	</Example>
	<Example name="rating/disabled" title="Desativado, com motivo">
		Diga quando a avaliação abre. Uma fileira de estrelas cinza sem explicação parece quebrada.
	</Example>
	<Example name="rating/size" title="Tamanhos">
		Defina `--cml-star-size` no rating: pequeno em listas e cards, grande quando dar a nota é a tarefa inteira.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Notas aparecem em avaliações, cards e pesquisas depois do atendimento. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="rating/context-review" title="Avaliação de produto" uses="Card · Field · Rating · Textarea · Button" />
	<Context name="rating/context-product" title="Card de produto" uses="Card · Badge · Rating · Button" />
	<Context name="rating/context-feedback" title="Opinião sobre o atendimento" uses="Card · Rating · ChipGroup · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="rating/do-with-count" title="Mostre a nota e o total.">
		"4,8 · 128 avaliações" é preciso e diz quanto dá para confiar.
	</Guideline>
	<Guideline kind="dont" name="rating/dont-stars-only" title="Só as estrelas.">
		Ninguém distingue 4,6 de 4,8, e uma avaliação parece tão sólida quanto cem.
	</Guideline>
	<Guideline kind="do" name="rating/do-five" title="Cinco estrelas para uma opinião.">
		Uma escala curta é rápida de escolher e fácil de ler depois.
	</Guideline>
	<Guideline kind="dont" name="rating/dont-ten" title="Dez estrelas.">
		A diferença entre 6 e 7 não quer dizer nada, e os alvos ficam pequenos.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="rating" type="RatingProps" include={["readOnly", "disabled", "required", "name"]}
	types={{ getLabel: "(value, max) => string" }}
	describe={{
		max: "Quantidade de estrelas.",
		value: "A nota, quando você controla o estado. `0` quer dizer nenhuma estrela escolhida.",
		defaultValue: "A nota inicial, quando o componente guarda o próprio estado.",
		onValueChange: "Chamada com o número da estrela quando a pessoa escolhe uma.",
		id: "Vai para a primeira estrela (ou para a imagem, quando readOnly), para o ErrorSummary e o <label htmlFor> focarem.",
		readOnly: "Mostra o valor como estrelas (com meias) numa única imagem, por exemplo uma média de 4,8.",
		getLabel: "Nome acessível de cada estrela e da imagem somente leitura (traduzível).",
		disabled: "Desativa todas as estrelas.",
		required: "Marca o grupo como obrigatório no formulário.",
		name: "Identifica o valor no envio do formulário.",
	}}
>
	Dentro de um `Field`, o rótulo dá nome ao grupo, e `disabled` e `name` também podem vir de lá. Os outros atributos do grupo de rádios são repassados.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio rating.

<StylingHooks
	slots={["rating", "rating-item", "rating-star"]}
	prefix="star"
	attributes={[
		{ attr: "data-slot", value: '"rating" · "rating-item" · "rating-star"' },
		{ attr: "data-filled", value: "presente nas estrelas até o valor" },
		{ attr: "data-checked", value: "presente na estrela escolhida" },
		{ attr: "data-fill", value: "full · half · empty (estrelas somente leitura)" },
		{ attr: "data-readonly", value: "presente num rating somente leitura" },
		{ attr: "data-disabled", value: "presente quando desativado" },
	]}
>

```css
/* estrelas douradas, só nos cards de produto */
.product-card [data-slot="rating"] {
  --cml-star-color: var(--cml-warning);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco à estrela escolhida (ou à primeira) e sai do rating." },
		{ key: "→ / ↓", description: "Escolhe a próxima estrela." },
		{ key: "← / ↑", description: "Escolhe a estrela anterior." },
		{ key: "Space", description: "Escolhe a estrela focada." },
	]}
	notes={[
		"Interativo, é um grupo de rádios: uma parada de Tab, e cada estrela é um rádio com o nome do getLabel, como \"4 de 5 estrelas\".",
		"Somente leitura, é um único role=\"img\" com o getLabel como nome, então o leitor de tela ouve \"Nota 4,8 de 5\" uma vez, e não cinco formas.",
		"Dê nome ao grupo: um FieldLabel dentro de um Field, ou aria-label quando ele está sozinho. O id vai para a primeira estrela, então um link do ErrorSummary consegue focá-la.",
		"Estrelas preenchidas mudam de forma e preenchimento, não só de cor, e cada alvo tem pelo menos 24 × 24 px.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Radio group", description: "Uma escolha, cada uma com rótulo em texto.", href: "/pt-br/docs/components/radio-group" },
		{ title: "Slider", description: "Uma nota numa escala contínua.", href: "/pt-br/docs/components/slider" },
		{ title: "Chip", description: "Etiquetas rápidas para explicar a nota.", href: "/pt-br/docs/components/chip" },
	]}
/>


# ScrollArea (/pt-br/docs/components/scroll-area)

<ComponentMeta file="scroll-area" primitive="Base UI" pattern="Região rolável (WCAG 2.1.1)" />

<Playground
	name="scroll-area/playground"
	component="ScrollArea"
	controls={[{ prop: "orientation", options: ["vertical", "horizontal", "both"], default: "both" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. Ele renderiza no cliente.

<Import names="ScrollArea" />

## Anatomia [#anatomia]

A raiz recorta, o viewport rola. Dê uma altura à raiz, ou uma altura máxima para ela crescer com o conteúdo até ali e então rolar (uma largura, para rolar na horizontal): sem isso, a caixa só cresce com o conteúdo. As barras só aparecem quando há o que rolar.

<Anatomy
	tree={{
		slot: "scroll-area",
		tag: "div",
		note: "defina o tamanho",
		children: [
			{ slot: "scroll-area-viewport", tag: "div", note: "rola, focável quando transborda" },
			{ slot: "scroll-area-scrollbar", tag: "div", note: "vertical · horizontal", children: [{ slot: "scroll-area-thumb", tag: "div" }] },
			{ slot: "scroll-area-corner", tag: "div", note: "orientation=both" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor da marca escolhidos na barra acima. Clique dentro de um e use as setas, ou aperte Tab até a caixa ganhar o anel de foco.

<Preview name="scroll-area/basic" compact />

<ExampleGrid>
	<Example name="scroll-area/horizontal" title="Uma linha, para o lado">
		No celular, uma linha de filtros que rola para o lado ocupa menos espaço que uma que quebra em quatro linhas. O chip cortado na borda mostra que tem mais.
	</Example>
	<Example name="scroll-area/code" title="Linhas longas">
		Logs, diffs e comandos perdem a forma quando quebram. Mantenha as linhas inteiras e deixe a caixa rolar para o lado.
	</Example>
	<Example name="scroll-area/sidebar-nav" title="Uma lista entre um título e um botão">
		Só rola a parte que cresce. O título e o botão "Novo projeto" ficam onde as pessoas esperam.
	</Example>
	<Example name="scroll-area/both" title="Nas duas direções" wide>
		Uma planilha rola para os dois lados. Deixe a linha de cabeçalho e a primeira coluna fixas (sticky), para cada número manter seus rótulos.
	</Example>
	<Example name="scroll-area/new-messages" title="Mensagens novas">
		Envie uma resposta. A mensagem mais nova rola até ficar visível, e o `role="log"` na lista faz o leitor de tela anunciá-la sem mover o foco.
	</Example>
	<Example name="scroll-area/a11y-named" title="Com o nome do título">
		Quando o conteúdo transborda, o viewport entra na ordem do Tab. Dê `role="region"` à raiz e um nome com `aria-labelledby`, para a pessoa ouvir onde chegou.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="scroll-area/context-activity" title="Feed de atividades" uses="Card · ScrollArea · Avatar · Button" />
	<Context name="scroll-area/context-terms" title="Termos para aceitar" uses="Card · ScrollArea · Checkbox · Button" />
	<Context name="scroll-area/context-filter" title="Filtro de marcas" uses="Fieldset · SearchInput · ScrollArea · Checkbox" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="scroll-area/do-header-outside" title="Role só a parte que cresce.">
		O título e a ação dele continuam à vista enquanto a lista se move.
	</Guideline>
	<Guideline kind="dont" name="scroll-area/dont-nested" title="Uma área rolável dentro de outra.">
		A roda do mouse fica presa na caixa de dentro, e a pessoa perde a noção de qual está rolando. Encurte a lista de dentro ou deixe a página rolar.
	</Guideline>
	<Guideline kind="do" name="scroll-area/do-peek" title="Mostre que tem mais.">
		Uma linha cortada ao meio e a barra visível avisam que a lista continua.
	</Guideline>
	<Guideline kind="dont" name="scroll-area/dont-hidden-bar" title="Esconder a barra de rolagem.">
		Sem barra e com uma altura que termina certinho numa linha, a lista parece completa. A maioria nunca vai achar os últimos itens.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="scroll-area"
	type="ScrollAreaProps"
	include={["overflowEdgeThreshold", "render"]}
	types={{ overflowEdgeThreshold: "number | { xStart, xEnd, yStart, yEnd }", render: "ReactElement | (props, state) => ReactElement" }}
	describe={{
		orientation: "Quais barras de rolagem mostrar. O conteúdo rola de forma nativa de qualquer jeito; isto só escolhe as barras desenhadas.",
		overflowEdgeThreshold: "Quantos pixels a partir de uma borda até aparecerem os atributos data-overflow-*. Útil para esmaecer as bordas.",
		render: "Troca o elemento da raiz por outro, mantendo o comportamento.",
	}}
>
	As outras props (`style`, `className`, `role`, `aria-label`…) vão para a raiz. Defina o tamanho nela.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria caixa.

<StylingHooks
	slots={["scroll-area", "scroll-area-viewport", "scroll-area-scrollbar", "scroll-area-thumb", "scroll-area-corner"]}
	prefix="scrollbar"
	attributes={[
		{ attr: "data-orientation", value: "vertical · horizontal, em cada barra" },
		{ attr: "data-has-overflow-x · data-has-overflow-y", value: "presente quando o conteúdo é mais largo ou mais alto" },
		{ attr: "data-overflow-y-start · data-overflow-y-end", value: "presente enquanto há mais acima ou abaixo (também -x-)" },
		{ attr: "data-hovering · data-scrolling", value: "na barra, com o ponteiro sobre a caixa ou durante a rolagem" },
	]}
>

```css
/* esmaece a borda de baixo enquanto há mais abaixo */
.feed [data-slot="scroll-area"][data-overflow-y-end] [data-slot="scroll-area-viewport"] {
  mask-image: linear-gradient(to bottom, black calc(100% - 2rem), transparent);
}
/* barras sempre com força total */
.feed { --cml-scrollbar-idle-opacity: 1; }
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco ao viewport quando o conteúdo transborda. Sem transbordar, ele é pulado." },
		{ key: "↓ / ↑", description: "Rolam um pouco para baixo ou para cima." },
		{ key: "→ / ←", description: "Rolam para o lado quando o conteúdo é mais largo." },
		{ key: "Page Down / Page Up", description: "Rolam quase uma caixa inteira." },
		{ key: "Espaço / Shift + Espaço", description: "Rolam uma caixa para baixo ou para cima, como Page Down e Page Up." },
		{ key: "Home / End", description: "Vão para o início ou para o fim." },
	]}
	notes={[
		"A rolagem continua nativa: roda do mouse, toque, teclado e a busca na página do navegador seguem funcionando.",
		"O viewport só é focável enquanto algo transborda, então quem usa teclado sempre alcança o conteúdo escondido (axe: scrollable-region-focusable).",
		"Dê um nome quando for uma região: role=\"region\" com aria-label ou aria-labelledby na raiz.",
		"As barras servem ao ponteiro e ficam escondidas do leitor de tela (aria-hidden). Elas só esmaecem, nunca se movem, então movimento reduzido não pede nada a mais.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Table", description: "Uma tabela que já rola para o lado sozinha em telas pequenas.", href: "/pt-br/docs/components/table" },
		{ title: "Drawer", description: "Um painel lateral cujo corpo rola enquanto o cabeçalho e o rodapé ficam.", href: "/pt-br/docs/components/drawer" },
		{ title: "Dialog", description: "Conteúdo longo num modal, com as ações sempre à vista.", href: "/pt-br/docs/components/dialog" },
	]}
/>


# Select (/pt-br/docs/components/select)

<ComponentMeta file="select" primitive="Base UI" pattern="WAI-ARIA Listbox (select-only combobox)" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe as partes que precisar; para listas longas, some `SelectGroup`, `SelectGroupLabel` e `SelectSeparator`. O estilo carregado cuida do gatilho e do popup.

<Import names="Select, SelectTrigger, SelectValue, SelectContent, SelectItem" />

## Anatomia [#anatomia]

O `Select` guarda o estado; o gatilho mostra o valor; o conteúdo é um popup renderizado num portal. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="select-trigger"]', color: "#8be36f" },
		{ label: '[data-slot="select-value"] · seta', color: "#ffcf7a" },
		{ label: '[data-slot="select-popup"] › [data-slot="select-item"]', color: "#7cc7ff" },
	]}
>
	<span className="a-label">Brasil</span>
	<span className="a-part">⌄</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="select/basic" compact />

<ExampleGrid>
	<Example name="select/placeholder" title="Com placeholder">
		Deixe o `defaultValue` de fora quando a escolha for da pessoa; o `placeholder` do `SelectValue` diz o que escolher sem fingir que já é um valor.
	</Example>
	<Example name="select/groups" title="Grupos e separadores">
		Passando de umas oito opções, `SelectGroup` com `SelectGroupLabel` deixa a pessoa pular para a seção certa em vez de ler linha por linha.
	</Example>
	<Example name="select/align-trigger" title="Alinhado ao gatilho">
		O `alignItemWithTrigger` abre a lista sobre o gatilho com a opção atual no lugar, e listas curtas ficam com cara de menu nativo.
	</Example>
	<Example name="select/controlled" title="Controlado">
		Escolha outra opção. Com `value` e `onValueChange` o resto do formulário reage, aqui o prazo e o preço abaixo do campo.
	</Example>
	<Example name="select/multiple" title="Vários valores">
		O `multiple` mantém a lista aberta e devolve um array; passe uma função ao `SelectValue` para o gatilho mostrar "Seg, Qua, Sex" em vez de um número.
	</Example>
	<Example name="select/disabled-items" title="Opções indisponíveis">
		Desative a opção em vez de removê-la, para a pessoa saber que ela existe, e diga quando volta.
	</Example>
	<Example name="select/validation" title="Obrigatório, com erro" wide>
		Dentro de um `Field`, o rótulo dá nome ao gatilho e o `FieldError` é lido junto; diga o que fazer, não só que está errado.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Um select quase nunca aparece sozinho. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="select/context-filters" title="Painel de filtros" uses="Card · Field · Select · Switch · Button" />
	<Context name="select/context-address" title="País e estado" uses="Fieldset · Field · Select · Input" />
	<Context name="select/context-pagination" title="Linhas por página" uses="Field · Select · IconButton · Text" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="select/do-label" title="Um rótulo visível acima.">
		O rótulo continua lá depois da escolha, então a pessoa sempre sabe que campo é aquele.
	</Guideline>
	<Guideline kind="dont" name="select/dont-placeholder-label" title="O placeholder como rótulo.">
		Escolhido um valor, "País" some e o campo fica sem nome na tela.
	</Guideline>
	<Guideline kind="do" name="select/do-radio" title="Duas ou três opções? Mostre todas.">
		Radio custa um clique e não esconde nada.
	</Guideline>
	<Guideline kind="dont" name="select/dont-two-options" title="Esconder duas opções num popup.">
		São dois cliques para ver uma escolha que caberia numa linha.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="select" type="SelectContentProps" include={["finalFocus", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement", finalFocus: "boolean | RefObject | (type) => …" }}
	describe={{ alignItemWithTrigger: "Abre o popup sobre o gatilho, com o item escolhido alinhado (como no macOS). Desligado, abre abaixo do gatilho.", finalFocus: "Para onde o foco vai quando o popup fecha. Por padrão, volta ao gatilho.", render: "Troca o elemento renderizado do popup, mantendo o comportamento." }}
>
	Estas são as props do `SelectContent`. O `Select` recebe as props da raiz do Base UI: `items` (um objeto ou `{ label, value }[]`, para o gatilho mostrar o rótulo antes de o popup abrir), `value`, `defaultValue`, `onValueChange`, `multiple`, `disabled`, `required`, `readOnly`, `name` e `open` / `onOpenChange`. O `SelectItem` recebe `value` e `disabled`; o `SelectValue` recebe `placeholder` ou uma função do valor como children.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio select.

<StylingHooks
	slots={["select-trigger", "select-value", "select-popup", "select-item", "select-group-label", "select-separator"]}
	prefix="select"
	attributes={[
		{ attr: "data-slot", value: '"select-trigger" · "select-value" · "select-positioner" · "select-popup" · "select-list" · "select-item" · "select-group" · "select-group-label" · "select-separator"' },
		{ attr: "data-popup-open", value: "no gatilho enquanto o popup está aberto" },
		{ attr: "data-placeholder", value: "no valor enquanto nada foi escolhido" },
		{ attr: "data-highlighted", value: "no item sob o teclado ou o mouse" },
		{ attr: "data-selected", value: "no(s) item(ns) escolhido(s)" },
		{ attr: "data-disabled", value: "no gatilho ou item desativado" },
		{ attr: "data-invalid", value: "no gatilho dentro de um Field inválido" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter / Space", description: "No gatilho, abre a lista; na lista, escolhe a opção destacada." },
		{ key: "↓ / ↑", description: "Abre a lista e depois anda entre as opções." },
		{ key: "Home / End", description: "Vai para a primeira ou a última opção." },
		{ key: "A–Z", description: "Vai para a próxima opção que começa com a letra." },
		{ key: "Esc", description: "Fecha a lista e devolve o foco ao gatilho." },
	]}
	notes={[
		"Dentro de um Field, o FieldLabel dá nome ao gatilho e o FieldDescription / FieldError são lidos em seguida.",
		"O gatilho informa aria-expanded e as opções têm aria-selected, então o leitor de tela anuncia o estado.",
		"O popup vai para um portal mas mantém o estilo pelo PortalScope, e o contraste passa no WCAG 2.2 AA nos 13 estilos.",
		"Para listas muito longas ou no celular, o NativeSelect usa o seletor do próprio sistema.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Combobox", description: "Um select em que você digita para filtrar.", href: "/pt-br/docs/components/combobox" },
		{ title: "NativeSelect", description: "O select do navegador, com o visual do estilo.", href: "/pt-br/docs/components/native-select" },
		{ title: "Menu", description: "Uma lista de ações, não um valor.", href: "/pt-br/docs/components/menu" },
	]}
/>


# Separator (/pt-br/docs/components/separator)

<ComponentMeta file="separator" primitive="Base UI" pattern="WAI-ARIA separator" />

<Playground
	name="separator/playground"
	component="Separator"
	controls={[
		{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O estilo que você carregar define o visual.

<Import names="Separator" />

## Anatomia [#anatomia]

Um `<div>` com `role="separator"`: 1px de altura na horizontal e 1px de largura na vertical. Ele tem um `data-slot` que você pode usar no CSS.

<Anatomy tree={{ slot: "separator", tag: "div", note: "role=\"separator\" · data-orientation" }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="separator/basic" compact />

<ExampleGrid>
	<Example name="separator/horizontal" title="Entre blocos empilhados">
		A linha ocupa toda a largura do elemento pai. Dê o espaço com o `gap` do pai, para ficar igual em cima e embaixo.
	</Example>
	<Example name="separator/vertical" title="Entre itens numa linha">
		Com `orientation="vertical"`, a linha pega a altura da fileira. Use para informações curtas lado a lado, como número de arquivos e tamanho.
	</Example>
	<Example name="separator/button-groups" title="Entre grupos de botões">
		Separe ações de tipos diferentes, como responder e excluir. Para uma barra de ferramentas de verdade, com setas do teclado, use o Toolbar e o separador dele.
	</Example>
	<Example name="separator/labelled" title='Com um texto, como "ou"'>
		Coloque a palavra entre dois separadores com `aria-hidden`. O leitor de tela lê "ou" uma vez só, em vez de "separador, ou, separador".
	</Example>
	<Example name="separator/decorative" title="Só enfeite">
		Esta linha curta de destaque não divide nada, então recebe `aria-hidden` e o leitor de tela pula. Guarde o papel de separador para linhas que dividem conteúdo de verdade.
	</Example>
	<Example name="separator/interactive-toggle" title="Mudando com o layout">
		Clique em Lado a lado. Quando os blocos passam para uma fileira, mude a orientação também, para a linha e o `aria-orientation` acompanharem.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Separadores dividem menus, listas e painéis em grupos fáceis de percorrer. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="separator/context-profile-menu" title="Card da conta" uses="Card · Separator · Link · Button" />
	<Context name="separator/context-feed-divider" title="Atividade por dia" uses="Separator" />
	<Context name="separator/context-sidebar-nav" title="Seções da barra lateral" uses="Separator" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="separator/do-semantic-divider" title="Uma linha entre grupos de verdade.">
		Um separador diz "aqui começa outra coisa". Use onde o assunto muda.
	</Guideline>
	<Guideline kind="dont" name="separator/dont-empty-spacing" title="Linhas empilhadas para dar espaço.">
		Use margem ou `gap` para o espaço. Linhas a mais parecem erro, e o leitor de tela anuncia cada uma.
	</Guideline>
	<Guideline kind="do" name="separator/do-vertical-flex" title="Deixe a linha vertical pegar a altura da fileira.">
		Coloque direto numa fileira flex. Ela estica junto com os itens, sem você definir altura.
	</Guideline>
	<Guideline kind="dont" name="separator/dont-inline-breaks" title="Barra vertical digitada como divisor.">
		Alguns leitores de tela falam "barra vertical" entre os itens. Use um separador vertical no lugar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="separator"
	type="SeparatorProps"
	describe={{
		orientation: "`horizontal` para uma linha entre blocos empilhados, `vertical` para uma linha entre itens lado a lado. O leitor de tela recebe isso como `aria-orientation`.",
	}}
>
	`Separator` também aceita os atributos de um `<div>`, como `aria-hidden` e `style`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio separador.

<StylingHooks
	slots={["separator"]}
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O separador não recebe foco. O Tab passa direto." }]}
	notes={[
		"Ele renderiza role=\"separator\" com aria-orientation, então o leitor de tela pode anunciar a quebra entre os grupos.",
		"Passe aria-hidden quando a linha for só enfeite, ou quando uma palavra como \"ou\" já diz o que ela significa.",
		"A linha é uma dica, não o único sinal. Os grupos também precisam fazer sentido pelos títulos ou rótulos.",
		"Dentro de Menu, Select ou Toolbar, use a parte de separador do próprio componente: ela tem o papel certo para aquele widget.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Card", description: "Uma caixa cujas seções muitas vezes são divididas por um separador.", href: "/pt-br/docs/components/card" },
		{ title: "Typography", description: "Títulos que dão nome aos grupos que o separador divide.", href: "/pt-br/docs/components/typography" },
		{ title: "Data list", description: "Linhas de rótulo e valor com divisórias próprias.", href: "/pt-br/docs/components/data-list" },
	]}
/>


# Sidebar (/pt-br/docs/components/sidebar)

<ComponentMeta file="sidebar" pattern="WAI-ARIA Landmarks (navigation)" />

<Playground
	name="sidebar/playground"
	component="Sidebar"
	controls={[{ prop: "collapsed", default: false }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Sidebar, SidebarHeader, SidebarNav, SidebarGroup, SidebarItem, SidebarFooter, SidebarToggle" />

## Anatomia [#anatomia]

Um `<aside>` com três linhas. Só o nav rola, então a marca e o rodapé ficam sempre à vista. `SidebarBrand` e `SidebarContent` são outros nomes para `SidebarHeader` e `SidebarNav`.

<Anatomy
	tree={{
		slot: "sidebar",
		tag: "aside",
		children: [
			{ slot: "sidebar-brand", tag: "div", note: "logo e nome" },
			{
				slot: "sidebar-nav",
				tag: "nav",
				note: "rola",
				children: [
					{
						slot: "sidebar-group",
						tag: "div",
						note: "role=group",
						children: [
							{ slot: "sidebar-group-label", tag: "span" },
							{
								slot: "sidebar-item",
								tag: "a",
								row: true,
								children: [
									{ slot: "sidebar-item-icon", tag: "span" },
									{ slot: "sidebar-item-label", tag: "span" },
									{ slot: "sidebar-item-count", tag: "span", note: "opcional" },
								],
							},
						],
					},
				],
			},
			{ slot: "sidebar-footer", tag: "div", note: "conta, sidebar-toggle" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo de verdade que você pode copiar. Todos usam o estilo, o modo e a cor da barra acima. Aperte Tab para passar pelos links.

<Preview name="sidebar/basic" compact />

<ExampleGrid>
	<Example name="sidebar/rail" title="Recolher para uma faixa">
		Aperte o botão lá embaixo. Os rótulos somem da tela, mas continuam dando nome a cada link para leitores de tela, e uma dica mostra o nome no hover e no foco.
	</Example>
	<Example name="sidebar/current" title="Página atual">
		Clique num link. `current` coloca `aria-current="page"`, e a barrinha ao lado mostra a página sem depender só da cor.
	</Example>
	<Example name="sidebar/router-link" title="Com o seu roteador">
		Passe `render={<NextLink href="…" />}`. O roteador cuida do clique sem recarregar a página, e o item mantém o estilo. Aqui o `current` vem do caminho, então o link para esta página fica marcado.
	</Example>
	<Example name="sidebar/counts" title="Contadores que fazem sentido ouvidos">
		O número é lido como parte do nome do link, então ponha a unidade num `VisuallyHidden`: "Entrada 12 não lidas", e não "Entrada 12".
	</Example>
	<Example name="sidebar/nested" title="Seções aninhadas">
		Um projeto com páginas próprias abre no lugar com um `Collapsible`. O cabeçalho dele é um botão, porque só mostra links e não leva a lugar nenhum.
	</Example>
	<Example name="sidebar/account-menu" title="Menu da conta no rodapé">
		A pessoa e as configurações dela ficam embaixo, longe das páginas. O menu abre para cima quando não há espaço abaixo.
	</Example>
	<Example name="sidebar/phone-drawer" title="No celular, numa gaveta">
		A Sidebar não tem um modo próprio para celular. Abaixo de uma largura, esconda a barra e ponha os mesmos links num `Drawer` à esquerda, que prende o foco e o devolve ao botão de menu.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São partes inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="sidebar/context-docs" title="Site de documentação" uses="Sidebar · Collapsible · Badge" />
	<Context name="sidebar/context-admin" title="Painel de uma loja" uses="Sidebar · Meter · Button" />
	<Context name="sidebar/context-projects" title="Espaço de trabalho de um time" uses="Sidebar · IconButton · Avatar" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="sidebar/do-groups" title="Poucos grupos com nome.">
		Dois ou três títulos deixam a pessoa pular direto para a parte do app que ela procura.
	</Guideline>
	<Guideline kind="dont" name="sidebar/dont-flat" title="Dez links numa lista só.">
		Sem grupos, a pessoa lê todos os links para achar um, e páginas parecidas ficam longe uma da outra.
	</Guideline>
	<Guideline kind="do" name="sidebar/do-short-labels" title="Uma ou duas palavras por link.">
		Nomes curtos cabem na coluna e são rápidos de ler. A página pode ter um título mais longo.
	</Guideline>
	<Guideline kind="dont" name="sidebar/dont-long-labels" title="Frases como rótulos.">
		Rótulos longos são cortados, e as palavras que diferenciam um do outro são justamente as que somem.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="sidebar"
	type="SidebarProps"
	types={{ onCollapseChange: "(collapsed: boolean) => void" }}
	describe={{
		collapsed: "Se a barra aparece como uma faixa de ícones. Use para controlar pelo código, junto com `onCollapseChange`.",
		defaultCollapsed: "Se começa como faixa, quando você não controla o estado.",
		onCollapseChange: "Chamado com o novo estado quando o `SidebarToggle` (ou `useSidebar().setCollapsed`) muda a barra.",
	}}
>
	O `SidebarItem` aceita `href`, `icon`, `count` e `current`, e também `render` para usar o link do seu roteador no lugar do `a`. O `SidebarGroup` aceita `label`. O `SidebarToggle` aceita `collapseLabel` e `expandLabel`; passe os dois no idioma da página (o padrão é "Collapse sidebar" e "Expand sidebar"). O `useSidebar()` lê e muda o estado de qualquer parte dentro da barra.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria barra.

<StylingHooks
	slots={["sidebar", "sidebar-brand", "sidebar-nav", "sidebar-group", "sidebar-group-label", "sidebar-item", "sidebar-item-icon", "sidebar-item-label", "sidebar-item-count", "sidebar-footer", "sidebar-toggle"]}
	prefix="sidebar"
	attributes={[
		{ attr: "data-collapsed", value: "na barra, enquanto ela é uma faixa" },
		{ attr: "data-current · aria-current", value: "page · no link da página mostrada" },
	]}
>

```css
/* uma barra mais larga e uma faixa mais fina */
.app [data-slot="sidebar"] {
  --cml-sidebar-width: 16rem;
  --cml-sidebar-rail-width: 3.25rem;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Vai para o próximo link, cabeçalho de seção ou botão, de cima para baixo. Na faixa também: os rótulos escondidos não viram paradas." },
		{ key: "Shift + Tab", description: "Volta para o anterior." },
		{ key: "Enter", description: "Num link, segue o link. No botão de recolher ou num cabeçalho de seção, recolhe ou expande." },
		{ key: "Espaço", description: "No botão de recolher ou num cabeçalho de seção, recolhe ou expande." },
	]}
	notes={[
		"Os links ficam num <nav>. Dê um aria-label, como \"Principal\", para ele aparecer pelo nome entre as regiões da página.",
		"Os grupos são role=\"group\" e levam o nome do rótulo, então o leitor de tela diz \"Espaço de trabalho, grupo\" quando você entra num deles.",
		"O botão de recolher tem aria-expanded e um nome que diz o que ele vai fazer. Na faixa, cada link mantém o nome completo; só o rótulo some da tela.",
		"A página atual recebe aria-current=\"page\", uma barrinha e um peso maior, não só uma cor.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Drawer", description: "Guarda os mesmos links no celular, atrás de um botão de menu.", href: "/pt-br/docs/components/drawer" },
		{ title: "Navigation menu", description: "Links no topo, para sites com poucas seções.", href: "/pt-br/docs/components/navigation-menu" },
		{ title: "Breadcrumb", description: "Mostra onde a página atual fica, acima do título.", href: "/pt-br/docs/components/breadcrumb" },
	]}
/>


# Skeleton (/pt-br/docs/components/skeleton)

<ComponentMeta file="display" pattern="aria-hidden" />

<Playground
	name="skeleton/playground"
	component="Skeleton"
	controls={[
		{ prop: "shape", options: ["line", "circle"], default: "line" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. O estilo carregado cuida do visual.

<Import names="Skeleton" />

## Anatomia [#anatomia]

Um `<span>` com um brilho suave. Você define a largura e a altura; o `shape` escolhe entre linha e círculo.

<Anatomy
	keys={[
		{ label: '[data-slot="skeleton"]', color: "#8be36f" },
		{ label: 'data-shape="line | circle"', color: "#ffcf7a" },
	]}
>
	<span className="a-part">formato</span>
	<span className="a-label">Espaço reservado</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="skeleton/basic" compact />

<ExampleGrid>
	<Example name="skeleton/shapes" title="Linha e círculo">
		Use `shape="circle"` para avatares e ícones e a `line`, que é o padrão, para títulos e textos. Dê a cada um o tamanho do que ele representa.
	</Example>
	<Example name="skeleton/paragraph" title="Um parágrafo de texto">
		Varie a largura das linhas e deixe a última curta. Barras iguais parecem um bloco, não um texto.
	</Example>
	<Example name="skeleton/card-loading" title="Do espaço reservado ao conteúdo">
		Clique. O cartão mantém cabeçalho, corpo e rodapé enquanto carrega, e o botão continua de verdade e funcionando.
	</Example>
	<Example name="skeleton/no-shift" title="Sem pulo ao carregar">
		Clique. Cada espaço reservado fica numa caixa com a altura de linha do texto que ele espera, então nada abaixo se mexe.
	</Example>
	<Example name="skeleton/list-loading" title="Uma lista marcada como ocupada">
		O leitor de tela ignora os skeletons. Coloque `aria-busy="true"` e um nome no contêiner, para a pessoa saber que a lista está carregando.
	</Example>
	<Example name="skeleton/table-loading" title="Uma tabela carregando" wide>
		Mantenha os cabeçalhos de verdade e preencha só as células. A pessoa já consegue ler o que a tabela vai mostrar.
	</Example>
	<Example name="skeleton/vs-spinner" title="Skeleton ou Spinner?">
		Skeleton quando você sabe o que vai aparecer, como um perfil ou uma lista. Spinner quando uma ação está rodando, como salvar.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O skeleton ocupa o lugar de pedaços inteiros de interface. São estados de carregamento para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="skeleton/context-profile" title="Cabeçalho de perfil" uses="Card · Skeleton" />
	<Context name="skeleton/context-feed" title="Publicação no feed" uses="Card · Skeleton" />
	<Context name="skeleton/context-article" title="Artigo de ajuda" uses="Card · Badge · Skeleton" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="skeleton/do-match-shape" title="Copie o formato do conteúdo.">
		Um círculo para o avatar e duas linhas do tamanho certo: a página fica igual quando os dados chegam.
	</Guideline>
	<Guideline kind="dont" name="skeleton/dont-generic-blocks" title="Uma caixa cinza grande.">
		Ela não diz nada sobre o que vem aí, e a página pula quando o layout de verdade aparece.
	</Guideline>
	<Guideline kind="do" name="skeleton/do-aria-busy" title="Marque a região como ocupada.">
		Dê um nome ao contêiner e use `aria-busy="true"`. Tire quando o conteúdo chegar.
	</Guideline>
	<Guideline kind="dont" name="skeleton/dont-interactive-skeleton" title="Skeleton no lugar de botão.">
		Você já sabe quais são as ações. Mostre os botões de verdade, desativados se ainda não funcionam, para a pessoa ver o que vai poder fazer.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="display"
	type="SkeletonProps"
	describe={{
		shape: "Formato do espaço reservado: `line` para textos, `circle` para avatares e ícones.",
	}}
>
	Os atributos nativos de `<span>` passam direto. Defina o tamanho com `style` ou `className`.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["skeleton"]}
	attributes={[
		{ attr: "data-shape", value: "line · circle" },
		{ attr: "aria-hidden", value: '"true", sempre' },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "Não recebe foco. Um skeleton é só um desenho do layout." }]}
	notes={[
		"Todo Skeleton tem aria-hidden=\"true\", então o leitor de tela pula ele.",
		"Avise que algo está carregando no contêiner: um nome e aria-busy=\"true\", ou uma mensagem de status para esperas longas.",
		"Com o movimento reduzido ativado, o brilho para e o espaço reservado fica parado.",
		"Não coloque parada de tabulação nem clique num skeleton; ainda não há nada para usar.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Spinner", href: "/pt-br/docs/components/spinner", description: "Indica que uma ação está rodando." },
		{ title: "Progress", href: "/pt-br/docs/components/progress", description: "Quanto de uma tarefa já foi feito, como um envio." },
		{ title: "Empty state", href: "/pt-br/docs/components/empty-state", description: "O que mostrar quando carregou e não veio nada." },
	]}
/>


# Slider (/pt-br/docs/components/slider)

<ComponentMeta file="slider" primitive="Base UI" pattern="WAI-ARIA Slider" />

<Playground
	name="slider/playground"
	component="Slider"
	controls={[
		{ prop: "thumbAlignment", options: ["center", "edge"], default: "center" },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. O estilo carregado cuida da trilha e dos marcadores.

<Import names="Slider" />

## Anatomia [#anatomia]

Um componente que renderiza o controle, a trilha, o preenchimento e um marcador por valor. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="slider"] › [data-slot="slider-control"]', color: "#8be36f" },
		{ label: '[data-slot="slider-track"] · [data-slot="slider-indicator"]', color: "#ffcf7a" },
		{ label: '[data-slot="slider-thumb"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">━━━━━━</span>
	<span className="a-label">●</span>
	<span className="a-part">──────</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="slider/basic" compact />

<ExampleGrid>
	<Example name="slider/range" title="Intervalo">
		Passe um array e você ganha um marcador por valor; dê nome a cada um com `getAriaLabel`, já que "mínimo" e "máximo" não aparecem na tela.
	</Example>
	<Example name="slider/visible-value" title="Com o valor à mostra">
		Arraste. Mostre o valor ao lado do rótulo e passe o mesmo `format` e `locale` para o leitor de tela dizer "R$ 25.000" em vez de "25000".
	</Example>
	<Example name="slider/step" title="Passos">
		O `step` encaixa nos valores que fazem sentido; o `largeStep` é o salto do Page Up e do Page Down.
	</Example>
	<Example name="slider/min-gap" title="Intervalo com distância mínima">
		O `minStepsBetweenValues` mantém os marcadores afastados, aqui pelo menos duas horas entre início e fim.
	</Example>
	<Example name="slider/committed" title="Salvar ao soltar">
		Arraste e solte. O `onValueCommitted` dispara uma vez no fim, então você salva ou busca uma vez, não a cada pixel.
	</Example>
	<Example name="slider/in-field" title="Dentro de um Field">
		O `FieldLabel` dá nome ao marcador e o `FieldDescription` explica a escala, sem precisar de `getAriaLabel`.
	</Example>
	<Example name="slider/vertical" title="Vertical">
		`orientation="vertical"` põe sliders lado a lado, como num equalizador; o `getAriaValueText` acrescenta a unidade, e o leitor de tela diz "+4 decibéis".
	</Example>
	<Example name="slider/disabled" title="Desativado, com o motivo">
		Um slider travado ainda mostra o valor atual; diga logo abaixo o que libera.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Sliders ficam em painéis e players. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="slider/context-player" title="Player de áudio" uses="Card · Slider · IconButton · Text" />
	<Context name="slider/context-price" title="Filtro de preço" uses="Card · Slider · Checkbox · Button" />
	<Context name="slider/context-display" title="Tamanho do texto" uses="Card · Field · Slider · Switch" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="slider/do-show-value" title="Mostre o número quando ele importa.">
		Quem escolhe um empréstimo precisa ver o valor, não adivinhar pela posição.
	</Guideline>
	<Guideline kind="dont" name="slider/dont-hide-value" title="Trilha sem número para um valor preciso.">
		Onde fica R$ 25.000 nessa barra? Ninguém sabe.
	</Guideline>
	<Guideline kind="do" name="slider/do-approximate" title="Valores aproximados.">
		Volume, brilho, zoom: o próprio efeito é o retorno.
	</Guideline>
	<Guideline kind="dont" name="slider/dont-exact" title="Valores exatos numa escala longa.">
		Arrastar até 1987 entre 90 anos é chato; use um NumberField ou um campo de texto.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="slider" type="SliderProps"
	include={["value", "defaultValue", "onValueChange", "onValueCommitted", "min", "max", "step", "largeStep", "minStepsBetweenValues", "format", "locale", "thumbAlignment", "thumbCollisionBehavior", "orientation", "disabled", "name"]}
	types={{ value: "number | number[]", defaultValue: "number | number[]", onValueChange: "(value, details) => void", onValueCommitted: "(value, details) => void", format: "Intl.NumberFormatOptions" }}
	describe={{
		getAriaLabel: "Nome acessível de cada marcador, por exemplo `(i) => [\"Mínimo\", \"Máximo\"][i]`. Dispensável dentro de um Field com rótulo.",
		getAriaValueText: "O valor falado de cada marcador, por exemplo `(texto) => texto + \" reais\"`. Por padrão, o valor formatado.",
		orientation: "A direção da trilha: horizontal ou vertical (de baixo para cima).",
		value: "O valor controlado. Um array cria um intervalo.",
		defaultValue: "O valor inicial, sem controle. Um array cria um intervalo.",
		onValueChange: "Chamado a cada mudança, inclusive durante o arraste.",
		onValueCommitted: "Chamado uma vez quando a pessoa solta o marcador ou termina pelo teclado.",
		min: "O menor valor.",
		max: "O maior valor.",
		step: "O passo entre valores.",
		largeStep: "O passo do Page Up / Page Down e das setas com Shift.",
		minStepsBetweenValues: "Quantos passos, no mínimo, entre os marcadores de um intervalo.",
		format: "Opções do Intl.NumberFormat para o valor lido pelo leitor de tela (aria-valuetext).",
		locale: "O idioma usado no format, por exemplo \"pt-BR\".",
		thumbAlignment: "Como o marcador se alinha às pontas: centralizado no valor ou contido na trilha.",
		thumbCollisionBehavior: "O que acontece quando os marcadores se encontram: empurrar, trocar ou parar.",
		disabled: "Desativa o slider.",
		name: "O nome do campo no envio do formulário.",
	}}
>
	Passe um array em `value` ou `defaultValue` para um intervalo. Dentro de um `Field`, o rótulo e a descrição chegam aos marcadores, e `disabled` / `name` também podem vir de lá.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio slider.

<StylingHooks
	slots={["slider", "slider-control", "slider-track", "slider-indicator", "slider-thumb"]}
	prefix="slider"
	attributes={[
		{ attr: "data-slot", value: '"slider" · "slider-control" · "slider-track" · "slider-indicator" · "slider-thumb"' },
		{ attr: "data-dragging", value: "presente enquanto um marcador é arrastado" },
		{ attr: "data-orientation", value: '"horizontal" · "vertical"' },
		{ attr: "data-disabled", value: "presente quando desativado" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "→ / ↑", description: "Aumenta o valor em um passo." },
		{ key: "← / ↓", description: "Diminui o valor em um passo." },
		{ key: "Page Up / Page Down", description: "Muda o valor pelo largeStep." },
		{ key: "Home / End", description: "Vai para o mínimo ou o máximo." },
		{ key: "Tab", description: "Passa de um marcador para o outro, em ordem." },
	]}
	notes={[
		"Cada marcador é um input range nativo com role=\"slider\", aria-valuemin, aria-valuemax e aria-valuenow.",
		"Com format e locale, o aria-valuetext lê o valor formatado, como \"R$ 1.200\" ou \"9 horas\"; o getAriaValueText acrescenta o que o número sozinho não diz, como a unidade.",
		"Fora de um Field, dê nome a cada marcador com getAriaLabel.",
		"O controle tem pelo menos 24 px de altura em todos os estilos, o que atende ao tamanho de alvo do WCAG 2.2.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "NumberField", description: "Digite ou ajuste um número exato.", href: "/pt-br/docs/components/number-field" },
		{ title: "Progress", description: "Mostra um valor que a pessoa não muda.", href: "/pt-br/docs/components/progress" },
		{ title: "Select", description: "Escolha entre opções com nome em vez de uma escala.", href: "/pt-br/docs/components/select" },
	]}
/>


# Spinner (/pt-br/docs/components/spinner)

<ComponentMeta file="spinner" pattern="ARIA status" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. Ele renderiza no servidor.

<Import names="Spinner" />

## Anatomia [#anatomia]

Um contêiner com `role="status"`, o anel girando e um rótulo escondido visualmente.

<Anatomy
	keys={[
		{ label: 'role="status"', color: "#8be36f" },
		{ label: '[data-slot="spinner"]', color: "#ffcf7a" },
		{ label: "rótulo (escondido visualmente)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">◌</span>
	<span className="a-label">Carregando</span>
</Anatomy>

## Exemplos [#exemplos]

<Preview name="spinner/basic" compact />

<ExampleGrid>
	<Example name="spinner/sizes" title="Tamanhos">
		Ele tem `1em` de largura, então segue o `font-size`. Dentro do texto, acompanha a linha.
	</Example>
	<Example name="spinner/tone" title="Cor">
		Ele usa `currentColor`. Defina a `color` com um token para manter o contraste em todos os estilos.
	</Example>
	<Example name="spinner/with-text" title="Com texto visível">
		Quando o texto está na tela, esconda-o da tecnologia assistiva (`aria-hidden`) para o status não ser lido duas vezes.
	</Example>
	<Example name="spinner/inline" title="No meio de uma frase">
		Ao lado do texto, ele acompanha a altura da linha. Diga quanto falta quando souber ("3 de 12").
	</Example>
	<Example name="spinner/in-button" title="Num botão">
		Não coloque um spinner à mão dentro do botão: use `Button loading`, que mantém a largura e o foco.
	</Example>
	<Example name="spinner/field" title="Verificando um campo" wide>
		Um spinner na descrição do campo enquanto o valor é validado no servidor.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

<ContextGrid>
	<Context name="spinner/context-table" title="Carregando uma lista" uses="Card · Skeleton · Spinner" />
	<Context name="spinner/context-upload" title="Envio em andamento" uses="Card · Spinner · Text" />
	<Context name="spinner/context-page" title="Página carregando" uses="Spinner" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="spinner/do-label" title="Diga o que está carregando.">
		"Sincronizando" é melhor que um "Carregando" genérico, e o rótulo é o que o leitor de tela fala.
	</Guideline>
	<Guideline kind="dont" name="spinner/dont-long" title="Spinner para uma tarefa longa que dá para medir.">
		Se você sabe a porcentagem, mostre.
	</Guideline>
	<Guideline kind="do" name="spinner/do-progress" title="Use o Progress quando souber quanto falta.">
		A espera fica melhor quando a pessoa vê o fim.
	</Guideline>
	<Guideline kind="do" name="spinner/context-table" title="Combine com skeletons no conteúdo.">
		O skeleton mostra o formato do que vem; o spinner diz que está a caminho.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="spinner" type="SpinnerProps" describe={{ label: "Anunciado ao leitor de tela pelo `role=\"status\"`." }}>
	Todos os atributos de `<span>` passam direto: `style`, `className`, `aria-*`.
</Props>

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["spinner"]}
	attributes={[
		{ attr: "data-slot", value: '"spinner" (o anel)' },
		{ attr: "role", value: '"status" (o contêiner)' },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "Não recebe foco. Só anuncia o rótulo." }]}
	notes={[
		"O role=\"status\" anuncia o rótulo com educação, sem mover o foco.",
		"Com prefers-reduced-motion, a animação fica mais suave pelo --cml-spinner-ease.",
		"Marque a região que está carregando com aria-busy=\"true\" para a tecnologia assistiva esperar.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Button", description: "Já tem o estado de carregamento.", href: "/pt-br/docs/components/button" },
		{ title: "Progress", description: "Para tarefas com porcentagem conhecida.", href: "/pt-br/docs/components/progress" },
		{ title: "Skeleton", description: "Marcadores no formato do conteúdo.", href: "/pt-br/docs/components/skeleton" },
	]}
/>


# Splitter (/pt-br/docs/components/splitter)

<ComponentMeta file="splitter" pattern="WAI-ARIA Window Splitter" />

<Playground
	name="splitter/playground"
	component="Splitter"
	controls={[{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Splitter, SplitterPanel, SplitterHandle" />

## Anatomia [#anatomia]

O valor é o tamanho do primeiro painel, em porcentagem; o segundo fica com o resto. Dê uma altura ao splitter. Os painéis recortam o conteúdo, então coloque uma `ScrollArea` dentro dos que podem crescer.

<Anatomy
	tree={{
		slot: "splitter",
		tag: "div",
		note: "defina a altura",
		row: true,
		children: [
			{ slot: "splitter-panel", tag: "div", note: "panel=first, recebe o valor" },
			{ slot: "splitter-handle", tag: "div", note: "role=separator", children: [{ slot: "splitter-grip", tag: "span" }] },
			{ slot: "splitter-panel", tag: "div", note: "panel=second, o resto" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor da marca escolhidos na barra acima. Arraste uma alça, ou aperte Tab até uma ganhar o anel de foco e use as setas.

<Preview name="splitter/basic" compact />

<ExampleGrid>
	<Example name="splitter/mail" title="Três colunas" wide>
		Coloque um segundo splitter dentro do segundo painel. Cada alça ganha seu próprio nome, para a pessoa saber qual divisa está movendo.
	</Example>
	<Example name="splitter/vertical" title="Empilhado">
		`orientation="vertical"` põe um painel sobre o outro, como um editor em cima do terminal. ↑ e ↓ movem a alça.
	</Example>
	<Example name="splitter/collapsible" title="Painel recolhível">
		Clique em "Ocultar filtros" ou aperte Enter na alça. Os dois recolhem o painel para 0 e depois o trazem de volta no tamanho que tinha; o painel recolhido fica oculto, então os controles dele saem da ordem do Tab.
	</Example>
	<Example name="splitter/controlled" title="Tamanho lembrado">
		Arraste a alça e depois restaure. Com `value` e `onValueChange`, você guarda o tamanho no perfil da pessoa.
	</Example>
	<Example name="splitter/limits" title="Limites">
		`min` e `max` mantêm os dois lados usáveis. Home e End vão direto para eles.
	</Example>
	<Example name="splitter/a11y-named" title="Um nome e um valor por extenso">
		A alça é um separador focável. Dê a ela o nome do que redimensiona e use `aria-valuetext` para o leitor de tela dizer "Barra lateral com 30% da largura" em vez de "30".
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context wide name="splitter/context-support" title="Caixa de suporte" uses="Splitter · ScrollArea · Badge · Avatar · Textarea · Button" />
	<Context wide name="splitter/context-query" title="Editor de consultas" uses="Splitter · Textarea · Button · Table" />
	<Context wide name="splitter/context-ide" title="Editor de código" uses="Splitter · TreeView · ScrollArea" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="splitter/do-min" title="Mínimos razoáveis.">
		Defina `min` para que o lado estreito sempre mostre palavras inteiras.
	</Guideline>
	<Guideline kind="dont" name="splitter/dont-tiny" title="Painéis que encolhem até sumir.">
		Uma barra lateral com 5% corta todos os nomes. A pessoa precisa arrastar de volta antes de conseguir ler.
	</Guideline>
	<Guideline kind="do" name="splitter/do-button" title="Um botão junto da alça.">
		Mostre e oculte o painel com um botão com rótulo, para quem não arrasta também chegar nele.
	</Guideline>
	<Guideline kind="dont" name="splitter/dont-drag-only" title="Conteúdo que só aparece arrastando.">
		Um painel com 0% e sem botão parece não existir. Conteúdo essencial precisa de um caminho visível.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="splitter"
	type="SplitterProps"
	types={{ onValueChange: "(value: number) => void" }}
	describe={{
		orientation: "`horizontal` põe os painéis lado a lado; `vertical` empilha.",
		value: "Tamanho do primeiro painel, em porcentagem do splitter. Use com `onValueChange` para controlar.",
		defaultValue: "Tamanho inicial do primeiro painel, em porcentagem, quando ele não é controlado.",
		onValueChange: "Chamado com o novo tamanho (porcentagem, já limitada) a cada movimento do arraste e a cada tecla.",
		min: "Menor tamanho do primeiro painel, em porcentagem. Home vai para ele.",
		max: "Maior tamanho do primeiro painel, em porcentagem. End vai para ele.",
		step: "Quanto uma seta move, em porcentagem; Shift + seta move cinco passos.",
		children: "Dois `SplitterPanel` com um `SplitterHandle` entre eles.",
	}}
>
	O `SplitterPanel` aceita `panel` (`"first"` ou `"second"`). O `SplitterHandle` aceita `aria-label` (o padrão é "Resize panel"; passe no idioma da página) e `aria-valuetext`. As outras props vão para os elementos.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio splitter.

<StylingHooks
	slots={["splitter", "splitter-panel", "splitter-handle", "splitter-grip"]}
	prefix="splitter"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical, em todas as partes" },
		{ attr: "data-panel", value: "first · second, nos painéis" },
		{ attr: "data-dragging", value: "no splitter e na alça enquanto ela é arrastada" },
	]}
>

```css
/* uma linha fina no lugar da barra, sem o grip */
.editor [data-slot="splitter"] {
  --cml-splitter-handle-size: 0.375rem;
  --cml-splitter-handle-bg: transparent;
}
.editor [data-slot="splitter-grip"] { display: none; }
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco à alça." },
		{ key: "← / →", description: "Lado a lado: deixa o primeiro painel mais estreito ou mais largo em um passo (1% por padrão)." },
		{ key: "↑ / ↓", description: "Empilhado: deixa o primeiro painel mais baixo ou mais alto em um passo." },
		{ key: "Shift + seta", description: "Move cinco passos de uma vez." },
		{ key: "Home / End", description: "Vão para o menor (min) ou o maior (max) tamanho." },
		{ key: "Enter", description: "Recolhe o primeiro painel para 0, ou o traz de volta no tamanho que tinha. Uma seta com o painel recolhido abre ele no min." },
	]}
	notes={[
		"A alça tem role=\"separator\" com aria-valuenow, aria-valuemin (0, já que o Enter pode recolher) e aria-valuemax em porcentagem, e aria-controls apontando para o primeiro painel.",
		"Dê a cada alça o nome do que ela redimensiona (\"Redimensionar barra lateral\"); o padrão \"Resize panel\" é em inglês.",
		"O Enter recolhe o primeiro painel, mas pouca gente conhece essa tecla. Quando esconder um painel importa, ofereça também um botão com aria-expanded.",
		"Os painéis não se empilham sozinhos em telas estreitas. No celular, troque para orientation=\"vertical\" ou mostre um painel por vez.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "ScrollArea", description: "Rola o conteúdo dentro de cada painel.", href: "/pt-br/docs/components/scroll-area" },
		{ title: "Tree view", description: "A árvore de arquivos ou pastas que costuma ocupar o primeiro painel.", href: "/pt-br/docs/components/tree-view" },
		{ title: "Drawer", description: "Um painel lateral para o celular, onde não há espaço para dividir.", href: "/pt-br/docs/components/drawer" },
	]}
/>


# Stack (/pt-br/docs/components/stack)

<ComponentMeta file="layout" pattern="CSS flexbox" />

<Playground
	name="stack/playground"
	component="Stack"
	controls={[
		{ prop: "direction", options: ["column", "row"], default: "column" },
		{ prop: "align", options: ["stretch", "flex-start", "center", "flex-end"], default: "stretch" },
		{ prop: "justify", options: ["flex-start", "center", "space-between", "flex-end"], default: "flex-start" },
		{ prop: "wrap", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. Ele não tem estado, então renderiza no servidor.

<Import names="Stack" />

## Anatomia [#anatomia]

Um elemento flex com `data-slot="stack"`. Stacks se aninham: este cabeçalho de página é uma linha cujos dois filhos são stacks também.

<Anatomy
	tree={{
		slot: "stack",
		tag: "header",
		note: 'direction="row" justify="space-between"',
		row: true,
		children: [
			{ slot: "stack", tag: "div", note: "gap={0}", children: [{ slot: "heading", tag: "h3" }, { slot: "text", tag: "p", note: "contagem" }] },
			{ slot: "stack", tag: "div", note: 'direction="row" gap={2}', row: true, children: [{ slot: "button", tag: "button" }, { slot: "button", tag: "button" }] },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="stack/basic" compact />

<ExampleGrid>
	<Example name="stack/gap-scale" title="O espaço mostra o que anda junto" wide>
		O `gap` conta passos de `--cml-space`, então o ritmo acompanha o estilo. Espaços pequenos juntam um rótulo ao valor; espaços grandes separam grupos.
	</Example>
	<Example name="stack/toolbar-row" title="Cabeçalho de página">
		`justify="space-between"` põe o título de um lado e as ações do outro. Com `wrap`, as ações descem para baixo do título no celular.
	</Example>
	<Example name="stack/wrap" title="Tags que quebram linha">
		Uma fileira de tags deve quebrar linha, não rolar para o lado nem espremer. Ela também é um `ul`, então o leitor de tela diz quantos assuntos são.
	</Example>
	<Example name="stack/direction-toggle" title="Linha ou coluna">
		Ligue o interruptor. Os mesmos três filhos passam de linha para coluna; só o `direction` muda, então a ordem de leitura continua a mesma.
	</Example>
	<Example name="stack/reading-order" title="Ordem visual igual à ordem do Tab">
		Ligue o `row-reverse` e aperte Tab: o foco começa pela direita. Para pôr a ação principal no fim, coloque por último no DOM e use `justify="flex-end"`.
	</Example>
	<Example name="stack/dividers" title="Linhas com divisórias">
		O Stack não tem prop de divisória. Coloque um `Separator` entre os filhos e o gap distribui o espaço igual acima e abaixo.
	</Example>
	<Example name="stack/as-list" title="Uma lista empilhada">
		`as="ul"` mantém a semântica de lista enquanto o Stack cuida do espaço. Tire os marcadores e o recuo com `listStyle` e `padding`.
	</Example>
	<Example name="stack/responsive" title="Responsivo sem breakpoints">
		Não existem props de breakpoint. Dê a cada filho uma largura mínima com `flex` e ligue o `wrap`: três campos numa linha viram uma coluna no celular.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="stack/context-order" title="Resumo do pedido" uses="Card · Stack · Separator · Button" />
	<Context name="stack/context-profile" title="Cabeçalho de perfil" uses="Card · Stack · Avatar · Badge · Button" />
	<Context name="stack/context-signup" title="Formulário de cadastro" uses="Card · Stack · Field · Input · Checkbox" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="stack/do-gap-groups" title="Espaço curto dentro do grupo, espaço largo entre grupos.">
		O título e o vencimento são lidos como uma coisa só, e a ação fica à parte.
	</Guideline>
	<Guideline kind="dont" name="stack/dont-even-gap" title="O mesmo espaço em tudo.">
		Cada linha fica à mesma distância da próxima, e nada diz o que anda junto.
	</Guideline>
	<Guideline kind="do" name="stack/do-dom-order" title="Ordene o DOM do jeito que se lê.">
		Cancelar vem primeiro e Publicar por último, empurrado para o fim com `justify="flex-end"`. O Tab segue o olhar.
	</Guideline>
	<Guideline kind="dont" name="stack/dont-reverse" title="row-reverse para mover o botão principal.">
		Fica idêntico, mas o Tab começa pela direita e anda para a esquerda, e o leitor de tela lê Publicar antes de Cancelar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="layout"
	type="StackProps"
	types={{ as: '"div" | "section" | "ul" | "form" | …', align: "CSS align-items", justify: "CSS justify-content" }}
	describe={{
		as: "Elemento renderizado, para a semântica certa (por exemplo `as=\"ul\"`).",
		direction: "Eixo principal. Os valores `-reverse` só invertem o desenho: a leitura e o Tab continuam seguindo o DOM.",
		gap: "Espaço entre os filhos, em múltiplos de `--cml-space` (0.25rem por padrão): `gap={4}` = 1rem.",
		align: "Alinhamento no eixo cruzado (`align-items`).",
		justify: "Distribuição no eixo principal (`justify-content`).",
		wrap: "Deixa os filhos quebrarem para a linha seguinte quando não cabem.",
	}}
>
	O `as` aceita as mesmas tags do [Box](/pt-br/docs/components/box). Todas as outras props vão para o elemento. O seu `style` entra depois das propriedades customizadas, então pode sobrescrever qualquer uma.
</Props>

## Styling hooks [#styling-hooks]

Cada prop vira uma propriedade customizada no elemento. Deixe uma prop de fora e o seu CSS pode definir essa propriedade, por exemplo num breakpoint.

<StylingHooks slots={["stack"]} prefix="stack" attributes={[{ attr: "data-slot", value: '"stack"' }]}>

```css
/* a barra de ações vira linha a partir de 40rem */
@media (min-width: 40rem) {
  .actions[data-slot="stack"] {
    --cml-stack-direction: row;
    --cml-stack-justify: flex-end;
  }
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O Stack não renderiza nenhum elemento interativo. O Tab passa pelos filhos na ordem do DOM." }]}
	notes={[
		"A ordem visual precisa ser a ordem do DOM. column-reverse e row-reverse só mexem no desenho: o Tab e o leitor de tela continuam seguindo o DOM, então reordene o JSX.",
		"Quebrar linha também mantém a ordem do DOM: os itens vão da esquerda para a direita e seguem na linha de baixo, que é a ordem de leitura.",
		"Espaço não é significado. Se os itens formam uma lista, renderize as=\"ul\"; se um grupo precisa de nome, dê um título a ele.",
		"Use o as para landmarks e formulários (as=\"form\", as=\"nav\") para a semântica vir junto com o layout.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Grid", description: "Quando os itens precisam se alinhar em linhas e colunas.", href: "/pt-br/docs/components/grid" },
		{ title: "Box", description: "A mesma escolha de elemento com as, sem o layout flex.", href: "/pt-br/docs/components/box" },
		{ title: "Separator", description: "Uma linha entre os filhos de um stack.", href: "/pt-br/docs/components/separator" },
	]}
/>


# Stat (/pt-br/docs/components/stat)

<ComponentMeta file="data-display" pattern="HTML article" />

<Playground
	name="stat/playground"
	component="StatDelta"
	label="+14,2%"
	controls={[{ prop: "trend", options: ["up", "down", "neutral"], default: "up" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Stat, StatLabel, StatValue, StatHelpText, StatDelta" />

## Anatomia [#anatomia]

Um `<article>` com o rótulo, o valor e uma linha de apoio. A variação costuma ficar dentro da linha de apoio, antes da comparação. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "stat",
		tag: "article",
		children: [
			{ slot: "stat-label", tag: "span" },
			{ slot: "stat-value", tag: "span" },
			{ slot: "stat-help", tag: "span", children: [{ slot: "stat-delta", tag: "span", note: "seta + variação" }] },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o skin, o modo e a marca escolhidos na barra acima.

<Preview name="stat/basic" compact />

<ExampleGrid>
	<Example name="stat/trend-up" title="Em alta">
		`trend="up"` coloca uma seta e a cor de sucesso. Sempre diga com o que você compara, como "em relação a setembro", senão a variação não quer dizer nada.
	</Example>
	<Example name="stat/trend-down" title="Em queda">
		`trend="down"` deixa a seta e a cor em tom de perigo. Escreva a variação na unidade do valor: pontos percentuais para uma taxa, não percentual de percentual.
	</Example>
	<Example name="stat/sentiment" title="Quando cair é bom">
		Em cancelamentos, latência ou custos, uma queda é boa notícia. Use `sentiment="positive"` para manter a seta para baixo com a cor de sucesso.
	</Example>
	<Example name="stat/trend-neutral" title="Sem mudança">
		`neutral` (o padrão) não mostra seta e usa uma cor discreta. Use quando a variação for zero ou pequena demais para importar.
	</Example>
	<Example name="stat/with-help-text" title="Comparado com a meta">
		A linha de apoio pode comparar com uma meta em vez de um período anterior. A pessoa vê quanto falta sem precisar ler um segundo número.
	</Example>
	<Example name="stat/custom-icon" title="Ícone próprio">
		Passe `icon` para usar os ícones do seu produto, ou `icon={null}` para mostrar só o número. Dê `aria-hidden` ao ícone, como na seta padrão.
	</Example>
	<Example name="stat/spoken-context" title="Sem linha de apoio">
		Num stat compacto, sem linha de apoio, acrescente a comparação com `VisuallyHidden`. Assim o leitor de tela fala "+6 desde ontem", e não um número solto.
	</Example>
	<Example name="stat/interactive-metric" title="Trocando o período">
		Escolha outro período. O grupo de toggles mantém a opção pressionada e o stat atualiza no lugar, sem pular o rótulo nem o layout.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Stats costumam aparecer em fileiras de três ou quatro dentro de um card, com um título para o grupo. Estas são partes inteiras de interface que você pode copiar, no skin que escolheu.

<ContextGrid>
	<Context name="stat/context-sales" title="Painel da loja" uses="Card · Stat" wide />
	<Context name="stat/context-mrr" title="Métricas de assinatura" uses="Card · Stat · Badge" wide />
	<Context name="stat/context-telemetry" title="Saúde do servidor" uses="Card · Stat · Badge" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="stat/do-accessible-delta" title="Escreva o sinal no texto.">
		A seta fica escondida do leitor de tela e nem todo mundo enxerga a cor. "+14,2%" diz a direção para todos.
	</Guideline>
	<Guideline kind="dont" name="stat/dont-color-only-delta" title="Direção só pela cor.">
		Sem o sinal e sem a seta, "14,2%" em verde parece um número qualquer para muita gente.
	</Guideline>
	<Guideline kind="do" name="stat/do-formatted-numbers" title="Formate o valor e mostre a unidade.">
		Moeda, separador de milhar e símbolo de porcentagem dizem o que é o número antes mesmo do rótulo.
	</Guideline>
	<Guideline kind="dont" name="stat/dont-missing-units" title="Números crus.">
		"48250" e "14,2" deixam a pessoa adivinhando: reais ou pedidos, percentual ou pontos.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="StatDeltaProps"
	include={["trend", "sentiment", "icon"]}
	describe={{
		trend: "Para onde o número foi. Define a seta (`neutral` fica sem seta) e, se `sentiment` não vier, a cor.",
		sentiment: "Se a mudança é boa notícia: `positive` é verde, `negative` é vermelho. Use quando cair é bom, como em cancelamentos ou latência: `trend=\"down\" sentiment=\"positive\"`. A cor é só visual; o texto precisa dizer o que aconteceu. Padrão: `positive` com `trend=\"up\"`, `negative` com `trend=\"down\"`, senão `neutral`.",
		icon: "Substitui a seta. Passe `null` para mostrar só o número. A seta fica escondida do leitor de tela, então o texto precisa trazer o sinal.",
	}}
>
	`Stat` aceita os atributos de `<article>`; `StatLabel`, `StatValue` e `StatHelpText`, os de `<span>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num skin ou no próprio stat.

<StylingHooks
	slots={["stat", "stat-label", "stat-value", "stat-help", "stat-delta"]}
	prefix="stat"
	attributes={[
		{ attr: "data-trend", value: "up · down · neutral (no stat-delta)" },
		{ attr: "data-sentiment", value: "positive · negative · neutral (no stat-delta, define a cor)" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "O stat não recebe foco. O Tab só passa pelos botões ou links que você colocar dentro dele." }]}
	notes={[
		"O leitor de tela lê as partes na ordem: rótulo, valor, variação e comparação. Mantenha essa ordem no código.",
		"A seta padrão tem aria-hidden e a cor é só visual, então o sinal no texto (+ ou −) precisa dizer a direção.",
		"Não use aria-label no StatDelta: ele é um span comum e a maioria dos leitores de tela ignora o rótulo ali. Acrescente palavras com VisuallyHidden.",
		"O StatValue usa números tabulares, então os dígitos não se mexem quando o valor atualiza.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Card", description: "O contêiner que agrupa uma fileira de stats sob um título.", href: "/pt-br/docs/components/card" },
		{ title: "Meter", description: "Mostra um valor dentro de uma faixa conhecida, como o uso de disco, em forma de barra.", href: "/pt-br/docs/components/meter" },
		{ title: "Data list", description: "Pares de rótulo e valor para os detalhes de um registro.", href: "/pt-br/docs/components/data-list" },
	]}
/>


# Stepper (/pt-br/docs/components/stepper)

<ComponentMeta file="stepper" pattern="Lista ordenada com aria-current=&quot;step&quot;" />

<Playground
	name="stepper/playground"
	component="Stepper"
	controls={[{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. É um componente de cliente: cada etapa lê sua situação do stepper.

<Import names="Stepper, Step, StepIndicator, StepTitle, StepDescription, StepSeparator" />

## Anatomia [#anatomia]

O `Stepper` é um `<ol>` e cada `Step` um `<li>`, então o leitor de tela diz "lista, 4 itens" e a posição de cada um. Passe `activeStep` ao stepper e cada etapa descobre sua situação: concluída antes dele, atual nele, futura depois. A linha entre as etapas é desenhada pela própria etapa, ou por um `StepSeparator` colocado por último nela; o indicador fica escondido do leitor de tela, então é o título que carrega o sentido. Um stepper horizontal com menos de 30rem de largura (uma container query, não a tela) esconde todos os títulos menos o da etapa atual.

<Anatomy
	tree={{
		slot: "stepper",
		tag: "ol",
		note: "data-orientation",
		children: [
			{
				slot: "step",
				tag: "li",
				note: "data-status · aria-current=step",
				row: true,
				children: [
					{ slot: "step-indicator", tag: "span", note: "número, ✓ ou ✕, aria-hidden" },
					{ slot: "step-title", tag: "span" },
					{ slot: "step-description", tag: "span", note: "opcional" },
					{ slot: "step-separator", tag: "span", note: "opcional, aria-hidden" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="stepper/basic" compact />

<ExampleGrid>
	<Example name="stepper/wizard" title="Voltar e Continuar" wide>
		Clique em Continuar. O foco vai para o título da nova etapa, então o leitor de tela diz "Etapa 2 de 4: Entrega" e quem usa teclado começa no topo do novo formulário.
	</Example>
	<Example name="stepper/status-text" title="Situação em palavras">
		Cor e um sinal de visto não bastam. Dê nome à lista com `aria-label` e uma palavra para cada situação, visível ou dentro de `VisuallyHidden`.
	</Example>
	<Example name="stepper/clickable" title="Voltar a uma etapa concluída">
		Clique em Carrinho. Só as etapas que a pessoa já alcançou são links; as seguintes ficam como texto, porque os dados delas ainda não existem.
	</Example>
	<Example name="stepper/error" title="Etapa com erro">
		`status="error"` deixa a etapa vermelha com um X e mantém o `aria-current` quando ela é a etapa ativa. Diga também em palavras o que deu errado, porque a cor e o ícone não são anunciados.
	</Example>
	<Example name="stepper/separator" title="Uma linha com estilo próprio">
		Coloque um `StepSeparator` por último na etapa quando uma linha precisa de outro visual, como uma linha tracejada até uma etapa que depende de outra pessoa.
	</Example>
	<Example name="stepper/vertical" title="Vertical, com descrições">
		Em coluna sobra espaço para uma linha embaixo de cada etapa. Use numa barra lateral ou num checklist de configuração que a pessoa retoma depois.
	</Example>
	<Example name="stepper/optional" title="Etapa opcional">
		Marque com um badge, não só com um texto mais claro, para a pessoa saber que pode seguir sem ela.
	</Example>
	<Example name="stepper/compact" title="Compacto no celular">
		Com menos de 30rem de largura, o stepper horizontal mostra só o título da etapa atual; os outros continuam na lista para o leitor de tela. Coloque "Etapa 2 de 4" acima dele para que todos vejam o tamanho do fluxo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="stepper/context-checkout" title="Finalizar compra" uses="Card · Stepper · Field · Input · Button" />
	<Context name="stepper/context-onboarding" title="Configuração da loja" uses="Card · Badge · Stepper · Field · Button" />
	<Context name="stepper/context-tracking" title="Rastreio do pedido" uses="Card · Badge · Stepper · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="stepper/do-short" title="De três a cinco etapas, com uma ou duas palavras.">
		A pessoa lê o fluxo inteiro de relance e sabe quanto falta para terminar.
	</Guideline>
	<Guideline kind="dont" name="stepper/dont-long" title="Frases como rótulos.">
		Elas não cabem lado a lado, então o stepper esconde todas menos a atual e a pessoa não vê o que vem depois. Coloque os detalhes no título de cada etapa.
	</Guideline>
	<Guideline kind="do" name="stepper/do-tabs" title="Abas para seções sem ordem.">
		Uma página de configurações não tem primeira nem última seção, e nada ali fica "concluído".
	</Guideline>
	<Guideline kind="dont" name="stepper/dont-tabs" title="Stepper para navegação livre.">
		Números e sinais de visto prometem uma ordem e um fim que não existem, e as etapas nem dão para clicar.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="stepper"
	type="StepperProps"
	include={["aria-label"]}
	types={{ "aria-label": "string" }}
	describe={{
		orientation: "Coloca as etapas em linha ou em coluna. A vertical comporta descrições e barras laterais estreitas.",
		activeStep: "Índice (a partir de 0) da etapa atual. As anteriores ficam `completed`, ela fica `current` e as seguintes `upcoming`, a não ser que um `Step` defina o próprio `status`.",
		"aria-label": "Dá nome à lista, por exemplo \"Etapas da compra\".",
	}}
>
	O `Step` recebe `status` (`"completed" · "current" · "upcoming" · "error"`) ou os atalhos `completed` e `current`; sem eles, a situação vem do `activeStep`, e é `"upcoming"` quando não há um. O `StepIndicator` usa a situação da sua etapa, ou o próprio `status`; com `"completed"` mostra um sinal de visto e com `"error"` um X no lugar dos filhos. O resto são as props nativas de `<ol>`, `<li>` e `<span>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio stepper.

<StylingHooks
	slots={["stepper", "step", "step-indicator", "step-title", "step-description", "step-separator"]}
	prefix="step"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical (no stepper)" },
		{ attr: "data-status", value: "completed · current · upcoming · error (na etapa e no indicador)" },
		{ attr: "aria-current", value: '"step" na etapa atual' },
	]}
>

```css
/* indicadores quadrados e linha mais grossa no checkout */
.checkout [data-slot="stepper"] {
  --cml-step-indicator-radius: 6px;
  --cml-stepper-line: 3px solid var(--cml-border-control);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Pula o stepper, a menos que uma etapa tenha um link ou botão; aí passa por eles, em ordem." },
		{ key: "Enter", description: "Num link de etapa, volta para aquela etapa." },
	]}
	notes={[
		"É um <ol>: o leitor de tela anuncia o número de etapas e a posição de cada uma. Dê nome a ele com aria-label.",
		"A etapa atual tem aria-current=\"step\". Concluída e não iniciada não são anunciadas pela cor nem pelo sinal de visto, que é aria-hidden: acrescente uma palavra como \"concluída\" em VisuallyHidden. Vale o mesmo para um erro: diga o que deu errado no título ou num StepDescription.",
		"Quando a etapa mudar, leve o foco para o título da nova etapa, com \"Etapa 2 de 4\" nele, para que leitor de tela e teclado comecem no lugar certo.",
		"Deixe clicáveis só as etapas já alcançadas. As seguintes ficam como texto, para ninguém cair num formulário sem as respostas anteriores.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Timeline", description: "Um histórico do que aconteceu, com datas, e não um fluxo a concluir.", href: "/pt-br/docs/components/timeline" },
		{ title: "Progress", description: "Uma barra para progresso sem etapas com nome.", href: "/pt-br/docs/components/progress" },
		{ title: "Error summary", description: "Lista o que corrigir antes da próxima etapa.", href: "/pt-br/docs/components/error-summary" },
	]}
/>


# StyleProvider (/pt-br/docs/components/style-provider)

<ComponentMeta file="style-provider" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe a folha de estilo de cada estilo que você renderiza, inclusive nas ilhas. Um estilo sem o CSS dele cai nos valores padrão.

<Import names="StyleProvider, useStyleScope, PortalScope, Portal, STYLE_NAMES" />

Para a página inteira, um Server Component pode espalhar `styleScopeProps({ styleName, mode, brand })` no `<html>`: os mesmos atributos, sem código no cliente. Veja em [Instalação](/pt-br/docs/installation) o CSS e as fontes.

## Anatomia [#anatomia]

O `StyleProvider` renderiza uma `<div>` com `data-style`, `data-mode` e os tokens da marca como variáveis inline. Cada elemento `[data-style]` redeclara todos os tokens e pinta o próprio fundo, a cor do texto e a fonte, então uma ilha aninhada começa do zero em vez de herdar o estilo do pai. Já o modo e a marca descem pela árvore até uma ilha definir os seus.

<Anatomy
	tree={{
		slot: "[data-style] [data-mode]",
		tag: "div",
		note: "StyleProvider · tokens da marca inline",
		children: [
			{ slot: "seu app", note: "usa o estilo" },
			{
				slot: "[data-style]",
				tag: "div",
				note: "StyleProvider aninhado: uma ilha",
				children: [{ slot: "sua seção" }],
			},
		],
	}}
/>

Os popups (Menu, Select, Popover, Dialog, Drawer…) são renderizados no `<body>`, fora de qualquer provider. Eles envolvem o conteúdo num elemento `portal-scope` que copia o escopo do provider de onde foram abertos.

<Anatomy
	tree={{
		slot: "portal-scope",
		tag: "div",
		note: "no <body> · display: contents · mesmo data-style, data-mode e marca",
		children: [{ slot: "menu-positioner · select-positioner · dialog-popup…" }],
	}}
/>

## Exemplos [#exemplos]

Cada prévia já fica dentro de um StyleProvider: o que a barra acima controla. Estes exemplos aninham um segundo, para você ver a ilha ao lado da página em volta.

<Preview name="style-provider/basic" compact />

<ExampleGrid>
	<Example name="style-provider/skins-gallery" title="Todos os estilos lado a lado" wide>
		Clique num quadro. Um seletor de tema mostra cada opção na própria ilha, e as pessoas veem o estilo antes de escolher. O modo e a marca continuam vindo da página.
	</Example>
	<Example name="style-provider/runtime-switch" title="Trocar de estilo em tempo de execução">
		Escolha um estilo e ligue o switch. Props novas só trocam atributos: nada é remontado e o estado lá dentro continua.
	</Example>
	<Example name="style-provider/tenant-brand" title="Uma marca por cliente">
		Defina só `brand` para dar a cada cliente a cor dele. Passe o estilo da página com `useStyleScope()`, porque `styleName` não é herdado.
	</Example>
	<Example name="style-provider/portal-menu" title="Popups mantêm o estilo da ilha">
		Abra o menu. Ele é renderizado no `<body>` e mesmo assim mantém o estilo, o modo e a marca da ilha, porque todo popup reaplica o escopo de onde foi aberto.
	</Example>
	<Example name="style-provider/custom-portal" title="Seu próprio portal">
		Clique em Pagar. O `Portal` move o conteúdo para outro nó e mantém o estilo da ilha; use-o, ou envolva o seu `createPortal` em `PortalScope`.
	</Example>
	<Example name="style-provider/read-scope" title="Ler o escopo atual">
		`useStyleScope()` devolve as props do provider mais próximo. Use para repassar o estilo, ou para colorir um gráfico ou canvas que não lê CSS.
	</Example>
	<Example name="style-provider/a11y-contrast" title="Cores de marca difíceis continuam legíveis">
		Amarelo, lima clara, quase preto: a escala da marca escolhe texto preto ou branco para cada tom, então os rótulos mantêm pelo menos 4,5:1 em qualquer estilo e modo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, com uma ilha dentro do estilo que você escolheu.

<ContextGrid>
	<Context name="style-provider/context-appearance" title="Configurações de aparência" uses="StyleProvider · Select · RadioGroup · Card · Switch" />
	<Context name="style-provider/context-campaign" title="Seção de campanha" uses="StyleProvider · Heading · Stat · Button" />
	<Context name="style-provider/context-booking" title="Widget de agendamento incorporado" uses="StyleProvider · useStyleScope · Card · Select · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="style-provider/do-section-island" title="Uma ilha para uma seção inteira.">
		Um painel de novidades, uma campanha ou um widget incorporado podem ter identidade própria. O resto da página fica com um estilo só.
	</Guideline>
	<Guideline kind="dont" name="style-provider/dont-mixed-form" title="Estilos diferentes num mesmo formulário.">
		Três campos em três estilos parecem quebrados, e as pessoas deixam de confiar no formulário.
	</Guideline>
	<Guideline kind="do" name="style-provider/do-keep-skin" title="Repasse o estilo quando mudar o modo.">
		`styleName={useStyleScope()?.["data-style"]}` com `mode="dark"` dá um card escuro no estilo da própria página.
	</Guideline>
	<Guideline kind="dont" name="style-provider/dont-drop-skin" title="Só o modo num provider aninhado.">
		Sem `styleName`, a ilha volta para `minimal`. Troque o estilo na barra acima: este card nunca muda.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="style-provider"
	type="StyleProviderProps"
	types={{ styleName: "StyleName (13 estilos)" }}
	describe={{
		styleName: "O estilo. Não é herdado: um provider aninhado sem ele volta para `minimal`. Importe também a folha de estilo dele (`@camaleo/styles/<nome>.css`).",
		mode: "`light`, `dark` ou `system`. Omita para herdar o modo do escopo pai (a raiz segue o sistema).",
		brand: "Qualquer cor CSS. Vira uma escala de 11 tons com texto legível em cada um; o estilo decide onde a marca aparece. Omita para herdar a marca do pai.",
	}}
>
	Todas as props de `<div>` passam adiante; `style` é mesclado com as variáveis da marca. `useStyleScope()` devolve `{ "data-style", "data-mode"?, style? }`, ou `null` fora de um provider. `PortalScope` recebe só `children`. `Portal` recebe `children` e `container` (padrão `document.body`). `styleScopeProps(opções)` devolve os mesmos atributos para um Server Component.
</Props>

## Styling hooks [#styling-hooks]

O provider é a fonte dos tokens que todo componente lê. Use os atributos dele para mudar um estilo, ou defina um token numa ilha para mudar só aquela seção.

<StylingHooks
	slots={["portal-scope"]}
	prefix="brand"
	attributes={[
		{ attr: "data-style", value: "minimal · neumorphism · retro-pixel · editorial · neubrutalism · retro · glass · swiss · progressive · clay · material · cupertino · y2k" },
		{ attr: "data-mode", value: "light · dark · system (ausente: herdado)" },
		{ attr: "style", value: "--cml-brand e --cml-brand-50 … -950, cada um com -fg e -hover" },
		{ attr: "data-slot", value: '"portal-scope" no invólucro do popup no <body>' },
	]}
>

```css
/* controles mais arredondados, só no estilo glass */
[data-style="glass"] {
  --cml-radius-control: 14px;
}

/* uma superfície mais suave numa ilha */
.central-de-ajuda[data-style] {
  --cml-surface: light-dark(var(--cml-brand-50), var(--cml-brand-950));
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "O provider não é interativo e não recebe foco. O teclado vem dos componentes dentro dele." }]}
	notes={[
		"Sem mode, a raiz segue prefers-color-scheme só com CSS (color-scheme e light-dark()), então não há piscada nem script antes da hidratação.",
		"Texto, anel de foco e bordas de controle passam no WCAG 2.2 AA nos 13 estilos, claro e escuro, com qualquer cor de marca. A biblioteca testa isso na CI.",
		"Cores forçadas (alto contraste do Windows) substituem o estilo: os componentes mantêm uma borda transparente e um outline no foco, então continuam visíveis.",
		"Movimento reduzido acalma as transições de todos os estilos, e transparência reduzida deixa o glass opaco. Os dois vêm do sistema, também em cada ilha.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "DirectionProvider", description: "Layouts e setas da direita para a esquerda.", href: "/pt-br/docs/components/direction-provider" },
		{ title: "Menu", description: "Um popup que mantém o escopo de onde abriu.", href: "/pt-br/docs/components/menu" },
		{ title: "Dialog", description: "Conteúdo em portal que reaplica o estilo da ilha.", href: "/pt-br/docs/components/dialog" },
	]}
/>


# Switch (/pt-br/docs/components/switch)

<ComponentMeta file="switch" primitive="Base UI" pattern="WAI-ARIA Switch" />

<Playground
	name="switch/playground"
	component="Switch"
	controls={[
		{ prop: "defaultChecked", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Envolva o switch num `Label` que dê nome ao ajuste.

<Import names="Switch, Label" />

## Anatomia [#anatomia]

Um trilho com um botão que desliza até o fim quando está ligado. As duas partes têm um `data-slot` que você pode usar no CSS.

<Anatomy
	keys={[
		{ label: '[data-slot="switch"]', color: "#8be36f" },
		{ label: '[data-slot="switch-thumb"]', color: "#ffcf7a" },
		{ label: 'texto do [data-slot="label"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">thumb</span>
	<span className="a-label">Salvar rascunhos automaticamente</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="switch/basic" compact />

<ExampleGrid>
	<Example name="switch/immediate" title="Vale na hora">
		Clique. O switch faz efeito assim que muda, então confirme o que mudou numa linha de status em vez de um botão Salvar.
	</Example>
	<Example name="switch/with-description" title="Com descrição">
		Explique o que o ajuste faz embaixo do rótulo e ligue com `aria-describedby`, para o nome continuar curto.
	</Example>
	<Example name="switch/list" title="Lista de ajustes">
		Switches relacionados ficam num `Fieldset` com uma legenda que funciona como o começo de cada rótulo.
	</Example>
	<Example name="switch/saving" title="Salvando no servidor">
		Clique. Quando a mudança demora um pouco, mantenha o foco no switch com `readOnly` e anuncie "Salvando…" e o resultado.
	</Example>
	<Example name="switch/dependent" title="Ajustes dependentes">
		Desligue o primeiro. Os ajustes filhos ficam desativados, não escondidos, para a pessoa ver o que vai recuperar.
	</Example>
	<Example name="switch/disabled" title="Desativado, com o motivo">
		Diga por que não dá para ligar e ligue o motivo com `aria-describedby`.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Switches moram nas telas de ajustes. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="switch/context-notifications" title="Ajustes de notificação" uses="Card · Switch · Separator" />
	<Context name="switch/context-flags" title="Recursos em teste" uses="Card · Switch · Badge" />
	<Context name="switch/context-pricing" title="Cobrança anual" uses="Card · Switch · Badge · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="switch/do-instant" title="Switch para uma mudança que vale agora.">
		O modo escuro liga assim que o switch se move.
	</Guideline>
	<Guideline kind="dont" name="switch/dont-submit" title="Um switch que espera o Salvar.">
		Parece feito, mas não está. Num formulário que se envia, use um `Checkbox`.
	</Guideline>
	<Guideline kind="do" name="switch/do-setting" title="Dê nome ao ajuste.">
		O próprio switch mostra ligado ou desligado; o leitor de tela anuncia pelo `aria-checked`.
	</Guideline>
	<Guideline kind="dont" name="switch/dont-state" title="Um rótulo que diz o estado.">
		"Ativado" muda a cada clique e nunca diz o que está ativado.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="switch" type="SwitchProps" include={["checked", "defaultChecked", "onCheckedChange", "name", "value", "required", "disabled", "readOnly"]}
	types={{ onCheckedChange: "(checked: boolean, details) => void" }}
	describe={{ checked: "Se o switch está ligado (controlado). Para não controlar, use `defaultChecked`.", defaultChecked: "Se o switch começa ligado (não controlado).", onCheckedChange: "Chamada quando o switch liga ou desliga.", name: "Nome do campo no envio do formulário.", value: "O valor enviado no formulário quando está ligado.", required: "Se o switch precisa estar ligado para enviar o formulário.", disabled: "Ignora a interação e tira o switch da ordem de tabulação.", readOnly: "Impede mudar o valor, mas mantém o switch focável e legível." }}
>
	Os atributos nativos passam direto para o trilho, um `<span role="switch">` com um input escondido para formulários.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio switch.

<StylingHooks
	slots={["switch", "switch-thumb"]}
	prefix="switch"
	attributes={[
		{ attr: "data-slot", value: '"switch" · "switch-thumb"' },
		{ attr: "data-checked", value: "presente quando ligado" },
		{ attr: "data-unchecked", value: "presente quando desligado" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-readonly", value: "presente quando somente leitura" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Space", description: "Liga ou desliga o switch com foco." },
		{ key: "Enter", description: "Liga ou desliga o switch com foco." },
		{ key: "Tab", description: "Vai para o próximo switch; cada um é uma parada de tabulação." },
	]}
	notes={[
		"Ele tem role=\"switch\" e aria-checked, então o leitor de tela diz \"ligado\" ou \"desligado\", não \"marcado\".",
		"Clicar no texto do rótulo também muda o switch, o que dá uma área de toque bem maior que o trilho.",
		"Quando o efeito não aparece na tela, confirme numa mensagem com role=\"status\".",
		"Um switch desativado continua mostrando ligado ou desligado, então a pessoa ainda lê o ajuste.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Checkbox", description: "Para escolhas que valem quando o formulário é enviado.", href: "/pt-br/docs/components/checkbox" },
		{ title: "Toggle", description: "Um botão pressionado para formatação e opções de visualização.", href: "/pt-br/docs/components/toggle" },
		{ title: "Radio group", description: "Uma escolha entre poucas.", href: "/pt-br/docs/components/radio-group" },
	]}
/>


# Table (/pt-br/docs/components/table)

<ComponentMeta file="display" pattern="WAI-ARIA table" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Table, TableCaption, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell" />

## Anatomia [#anatomia]

Uma `<table>` nativa dentro de uma caixa que rola para o lado quando a tabela não cabe. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "table-container",
		tag: "div",
		note: "rola quando não cabe",
		children: [
			{
				slot: "table",
				tag: "table",
				children: [
					{ slot: "table-caption", tag: "caption", note: "opcional" },
					{ slot: "table-header", tag: "thead", children: [{ slot: "table-row", tag: "tr", row: true, children: [{ slot: "table-head", tag: "th" }, { slot: "table-head", tag: "th" }] }] },
					{ slot: "table-body", tag: "tbody", children: [{ slot: "table-row", tag: "tr", row: true, children: [{ slot: "table-cell", tag: "td" }, { slot: "table-cell", tag: "td" }] }] },
					{ slot: "table-footer", tag: "tfoot", note: "opcional, totais" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="table/basic" compact />

<ExampleGrid>
	<Example name="table/with-caption" title="Com legenda">
		Uma `TableCaption` dá nome à tabela. O leitor de tela lê a legenda antes das linhas, e ela também nomeia a área de rolagem quando a tabela fica larga demais.
	</Example>
	<Example name="table/align" title="Números à direita">
		Passe `align="end"` no cabeçalho e nas células das colunas de números. Os algarismos ficam com a mesma largura, e dá para comparar valores de relance.
	</Example>
	<Example name="table/totals" title="Linha de total">
		Coloque o total num `TableFooter`, abaixo de uma linha mais forte. Ele fica separado dos dados, então ordenar ou incluir linhas não muda a posição dele.
	</Example>
	<Example name="table/status" title="Situação numa coluna">
		Um selo por linha é mais fácil de bater o olho do que uma frase. Use palavras curtas e as mesmas em todas as linhas.
	</Example>
	<Example name="table/empty" title="Ainda sem linhas">
		Mantenha os cabeçalhos e preencha o corpo com uma linha que ocupa todas as colunas. Diga por que está vazia e qual é o próximo passo.
	</Example>
	<Example name="table/interactive-sort" title="Coluna que ordena">
		Clique em Receita. O botão inverte a ordem, e o `aria-sort` no cabeçalho avisa o leitor de tela em que sentido as linhas estão.
	</Example>
	<Example name="table/wide" title="Tabela larga no celular" wide>
		Numa tela estreita esta tabela rola para o lado. Só nesse caso a caixa vira uma área de rolagem com nome e uma parada de Tab, para quem usa teclado rolar com as setas.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Tabelas costumam ficar num card ou numa seção da página, com as ações na última coluna. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="table/context-invoices" title="Faturas para baixar" uses="Table · Badge · Button" wide />
	<Context name="table/context-users" title="Pessoas do time" uses="Table · Avatar · Badge" wide />
	<Context name="table/context-inventory" title="Lista de estoque" uses="Table" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="table/do-tabular-nums" title="Alinhe números à direita.">
		Unidade fica embaixo de unidade, e o maior valor salta aos olhos sem ler linha por linha.
	</Guideline>
	<Guideline kind="dont" name="table/dont-left-align-numbers" title="Números alinhados à esquerda.">
		Os centavos ficam em lugares diferentes, e a pessoa precisa ler cada valor para comparar.
	</Guideline>
	<Guideline kind="do" name="table/do-caption" title="Dê nome a toda tabela.">
		Use uma `TableCaption`, ou `aria-label` quando o título já está na página. Assim a pessoa ouve do que se trata antes da primeira linha.
	</Guideline>
	<Guideline kind="dont" name="table/dont-unlabeled-table" title='Cabeçalhos como "Coluna A".'>
		O leitor de tela lê o cabeçalho junto com cada célula. Um cabeçalho vago deixa todas as células vagas.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="display"
	type="TableProps"
	describe={{ scrollLabel: "Nome da área de rolagem quando a tabela não cabe e não tem `<caption>`." }}
/>

<Props
	file="display"
	type="TableCellProps"
	describe={{
		align: "Alinha o conteúdo. Use `end` em colunas de números: eles vão para a direita e todos os algarismos ficam com a mesma largura, então os valores se alinham na coluna.",
	}}
>
	`TableHead` e `TableCell` aceitam `align`. Todas as partes também aceitam os atributos do elemento HTML, como `colSpan` e `aria-sort`. `TableCaption` (uma `<caption>`, a primeira coisa dentro do `Table`) e `TableFooter` (um `<tfoot>`) aceitam os atributos dos seus elementos.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria tabela.

<StylingHooks
	slots={["table-container", "table", "table-caption", "table-header", "table-body", "table-footer", "table-row", "table-head", "table-cell"]}
	attributes={[
		{ attr: "data-align", value: "start · end" },
		{ attr: "role", value: "region no table-container, só enquanto a tabela não cabe" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Passa pelos botões e links dentro das células. Quando a tabela não cabe, a área de rolagem é uma parada a mais." },
		{ key: "← / →", description: "Rolam a tabela larga para o lado enquanto a área de rolagem está com o foco." },
	]}
	notes={[
		"O TableHead coloca scope=\"col\", então o leitor de tela lê o cabeçalho da coluna junto com cada célula.",
		"Uma tabela que não cabe vira uma área de rolagem (role=\"region\") com o nome da legenda ou do scrollLabel. Uma tabela que cabe não ganha parada de Tab.",
		"Dê nome a toda tabela com uma TableCaption, ou com aria-label quando um título já diz do que ela trata.",
		"Botões só com ícone numa linha precisam de um nome que inclua a linha, como \"Baixar INV-4029\", e não só \"Baixar\".",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Data table", description: "Ordenar, filtrar, selecionar e paginar muitos dados.", href: "/pt-br/docs/components/data-table" },
		{ title: "Data list", description: "Pares de rótulo e valor para os detalhes de um registro.", href: "/pt-br/docs/components/data-list" },
		{ title: "Empty state", description: "Uma mensagem completa para uma página ou seção que ainda não tem nada.", href: "/pt-br/docs/components/empty-state" },
	]}
/>


# Tabs (/pt-br/docs/components/tabs)

<ComponentMeta file="tabs" primitive="Base UI" pattern="WAI-ARIA Tabs" />

<Playground
	name="tabs/playground"
	component="Tabs"
	controls={[{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Tabs, TabsList, Tab, TabsPanel" />

## Anatomia [#anatomia]

Um `Tab` e um `TabsPanel` com o mesmo `value` andam juntos. A lista é uma parada só na ordem do Tab; as setas passam de uma aba para outra.

<Anatomy
	tree={{
		slot: "tabs",
		tag: "div",
		children: [
			{
				slot: "tabs-list",
				tag: "div",
				note: "role=tablist, rola quando as abas não cabem",
				row: true,
				children: [
					{ slot: "tab", tag: "button", note: "role=tab" },
					{ slot: "tab", tag: "button" },
					{ slot: "tab", tag: "button" },
				],
			},
			{ slot: "tabs-panel", tag: "div", note: "role=tabpanel, só o ativo" },
		],
	}}
/>

## Exemplos [#exemplos]

Todo exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor da barra acima. Clique numa aba e depois experimente as setas.

<Preview name="tabs/basic" compact />

<ExampleGrid>
	<Example name="tabs/vertical" title="Vertical">
		Com `orientation="vertical"` a lista fica ao lado do painel e ↑ ↓ passam de uma aba para outra. Serve para configurações com mais seções do que cabem numa linha.
	</Example>
	<Example name="tabs/counts" title="Com ícones e contagens">
		Uma contagem mostra onde está o trabalho antes do clique. Seja breve: o número passa a fazer parte do nome da aba.
	</Example>
	<Example name="tabs/overflow" title="Muitas abas">
		Quando as abas não cabem, a lista rola para o lado e mantém a aba ativa à vista. Passando de umas oito, uma barra lateral ou um select fica mais fácil de ler.
	</Example>
	<Example name="tabs/controlled" title="Na URL">
		Clique numa aba e veja o endereço. Com `value` e `onValueChange` você guarda a aba na URL, e um link ou um recarregamento abre a mesma visão.
	</Example>
	<Example name="tabs/lazy" title="Carregar na primeira abertura">
		Abra Atividade. Um painel escondido não é renderizado, então você pode buscar os dados na primeira vez que ele abre e mostrar um skeleton enquanto isso.
	</Example>
	<Example name="tabs/activate-on-focus" title="Seguir o foco">
		Por padrão as setas só movem o foco, e Enter ou Espaço abre a aba. Use `activateOnFocus` quando os painéis aparecem na hora, como esses números.
	</Example>
	<Example name="tabs/disabled-reason" title="Desativada, com o motivo">
		As setas ainda chegam a uma aba desativada, mas não a abrem. Diga por que ela está desligada e quando abre, ligado com `aria-describedby` para ser lido no foco.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="tabs/context-product" title="Detalhes do produto" uses="Card · Tabs · DataList · Rating" />
	<Context name="tabs/context-order" title="Página do pedido" uses="Card · Badge · Tabs · Timeline" />
	<Context name="tabs/context-member" title="Membro da equipe" uses="Card · Avatar · Tabs · Checkbox · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="tabs/do-views" title="Visões de uma mesma coisa.">
		Resumo, pedidos e observações descrevem o mesmo cliente, e dá para ler em qualquer ordem.
	</Guideline>
	<Guideline kind="dont" name="tabs/dont-steps" title="Etapas de uma tarefa.">
		Uma compra tem ordem e próxima etapa. Abas deixam pular para a frente e escondem quanto já foi feito; use um stepper.
	</Guideline>
	<Guideline kind="do" name="tabs/do-links" title="Links para páginas.">
		Ir para outra página é navegação: links com `aria-current="page"` mantêm o botão Voltar, as novas abas do navegador e as URLs compartilhadas funcionando.
	</Guideline>
	<Guideline kind="dont" name="tabs/dont-page-nav" title="Abas como navegação do site.">
		O leitor de tela anuncia uma lista de abas, e a pessoa espera que o conteúdo mude ali, não a página inteira.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="tabs"
	type="TabsProps"
	include={["value", "defaultValue", "onValueChange", "orientation"]}
	types={{ onValueChange: "(value, eventDetails) => void" }}
	describe={{ value: "A aba ativa. Use com `onValueChange` para controlar o estado. `null` deixa nenhuma ativa.", defaultValue: "A aba ativa no início, sem controlar o estado.", onValueChange: "Chamado quando a aba ativa muda. `eventDetails.reason` diz o motivo, por exemplo `none` para um clique ou uma tecla.", orientation: "`horizontal` usa ← →; `vertical` põe a lista ao lado do painel e usa ↑ ↓." }}
>
	`Tab` e `TabsPanel` recebem um `value` que os liga. O `Tab` também aceita `disabled`.
</Props>

O `TabsList` decide como o teclado se comporta:

<Props
	file="tabs"
	type="TabsListProps"
	include={["activateOnFocus", "loopFocus"]}
	describe={{ activateOnFocus: "Abre a aba assim que ela recebe o foco pelas setas. Sem isso, Enter ou Espaço abre.", loopFocus: "Das pontas, as setas voltam para a primeira ou a última aba." }}
/>

O `TabsPanel` pode continuar na página enquanto está escondido:

<Props
	file="tabs"
	type="TabsPanelProps"
	include={["keepMounted"]}
	describe={{ keepMounted: "Mantém o painel no DOM quando escondido, por exemplo para não perder o que foi digitado num formulário." }}
/>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria lista.

<StylingHooks
	slots={["tabs", "tabs-list", "tab", "tabs-panel"]}
	prefix="tab"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical" },
		{ attr: "data-active", value: "na aba ativa" },
		{ attr: "data-disabled", value: "numa aba desativada" },
		{ attr: "data-activation-direction", value: "left · right · up · down, para onde a seleção andou" },
	]}
>

```css
/* abas em pílula sobre um trilho, só neste card */
.cobranca [data-slot="tabs-list"] {
  --cml-tabs-list-bg: var(--cml-surface-sunken);
  --cml-tabs-list-radius: var(--cml-radius-surface);
  --cml-tab-radius: var(--cml-radius-surface);
  --cml-tab-active-bg: var(--cml-surface-raised);
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Leva o foco para a lista, na aba ativa. De novo, leva ao painel." },
		{ key: "← / →", description: "Movem o foco para a aba anterior ou a próxima, voltando nas pontas. Numa lista vertical, ↑ e ↓." },
		{ key: "Home / End", description: "Movem o foco para a primeira ou a última aba." },
		{ key: "Enter / Espaço", description: "Abre a aba focada. Com activateOnFocus, a aba abre assim que recebe o foco." },
	]}
	notes={[
		"Cada aba tem role=tab e aria-selected; cada painel tem role=tabpanel e recebe o nome da sua aba por aria-labelledby.",
		"Dê um nome à lista com aria-label ou aria-labelledby, para a pessoa saber em qual grupo de abas está.",
		"O painel recebe foco, então quem usa teclado chega ao texto mesmo sem links ou campos.",
		"Uma aba desativada continua focável com aria-disabled, então a pessoa sabe que ela existe; Enter e Espaço não a abrem.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Accordion", description: "Seções que abrem no lugar, mais de uma por vez.", href: "/pt-br/docs/components/accordion" },
		{ title: "Toggle", description: "Um grupo de toggles muda uma opção, não uma visão.", href: "/pt-br/docs/components/toggle" },
		{ title: "Stepper", description: "Para uma tarefa feita em etapas, em ordem.", href: "/pt-br/docs/components/stepper" },
	]}
/>


# TagsInput (/pt-br/docs/components/tags-input)

<ComponentMeta file="tags-input" primitive="Base UI" pattern="WAI-ARIA Combobox" />

<Playground
	name="tags-input/playground"
	component="TagsInput"
	controls={[
		{ prop: "allowCustom", default: true },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe. Coloque dentro de um `Field` para o rótulo dar nome ao input.

<Import names="TagsInput, Field, FieldLabel, FieldDescription" />

## Anatomia [#anatomia]

Os chips e um input de texto dividem a mesma caixa. Cada chip tem seu botão de remover, e as sugestões abrem num popup logo abaixo.

<Anatomy
	keys={[
		{ label: '[data-slot="tags-input"]', color: "#8be36f" },
		{ label: '[data-slot="tag"] · [data-slot="tag-remove"]', color: "#ffcf7a" },
		{ label: '[data-slot="tags-input-input"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">design systems ✕</span>
	<span className="a-part">acessibilidade ✕</span>
	<span className="a-label">Adicionar tópico</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="tags-input/basic" compact />

<ExampleGrid>
	<Example name="tags-input/suggestions" title="Escolher de uma lista">
		Digite "py". Sem `allowCustom` só entram as `suggestions`, então todo perfil usa os mesmos nomes e a busca encontra todos.
	</Example>
	<Example name="tags-input/custom" title="Sugestões e tags novas">
		Digite uma etiqueta que não está na lista e aperte Enter. O `emptyText` avisa que o Enter cria a tag, então ninguém fica esperando aparecer uma opção.
	</Example>
	<Example name="tags-input/limit" title="Limite e duplicadas">
		Adicione "React" de novo, ou uma sexta competência. Uma tag repetida fica no campo sem chamar o `onValueChange`, então pegue-a no `onKeyDown`; recuse o limite no `onValueChange` e explique no `FieldError`.
	</Example>
	<Example name="tags-input/paste" title="Colar uma lista">
		Cole "joao@acme.com, lia@acme.com". Um `onPaste` separa por vírgulas e quebras de linha, então uma coluna copiada da planilha vira um chip por endereço.
	</Example>
	<Example name="tags-input/keyboard" title="Remover pelo teclado">
		Foque o input e aperte Backspace, ou ← e Delete. Cada botão de remover leva o nome da tag pelo `removeLabel`, no idioma da página.
	</Example>
	<Example name="tags-input/form" title="Num formulário">
		Clique em salvar. Com `name`, cada tag vai como um valor separado, e `formData.getAll("labels")` devolve a lista.
	</Example>
	<Example name="tags-input/disabled" title="Desativado, com motivo">
		O `disabled` trava os chips e o input. Diga na descrição o motivo e até quando, senão parece defeito.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Tags ficam ao lado de outros campos. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="tags-input/context-invite" title="Convidar pessoas por e-mail" uses="Card · Field · TagsInput · NativeSelect · Button" />
	<Context name="tags-input/context-article" title="Tags de um artigo" uses="Card · Field · Input · TagsInput · Switch · Button" />
	<Context name="tags-input/context-filters" title="Filtros de busca de vagas" uses="Fieldset · Field · TagsInput · Checkbox · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="tags-input/do-vocabulary" title="Uma grafia por tag.">
		Sugira as tags que já existem, assim filtros e relatórios contam tudo junto.
	</Guideline>
	<Guideline kind="dont" name="tags-input/dont-variants" title="Texto livre sem sugestões.">
		Cada pessoa escreve a mesma tag de um jeito, e o filtro por "bug" perde duas delas.
	</Guideline>
	<Guideline kind="do" name="tags-input/do-short" title="Uma ou duas palavras.">
		Tags curtas cabem numa linha e se leem de relance.
	</Guideline>
	<Guideline kind="dont" name="tags-input/dont-sentences" title="Frases como tag.">
		Elas enchem a linha, ninguém filtra por elas, e o lugar delas é num comentário.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="tags-input"
	type="TagsInputProps"
	include={["disabled"]}
	types={{ removeLabel: "(tag: string) => string" }}
	describe={{
		value: "As tags, de forma controlada.",
		defaultValue: "As tags iniciais, sem controle.",
		onValueChange: "Recebe a lista nova inteira quando uma tag entra ou sai.",
		suggestions: "Oferecidas num popup enquanto a pessoa digita; escolher uma adiciona a tag.",
		allowCustom: "O Enter adiciona o texto digitado como tag quando nenhuma sugestão está destacada. Uma tag repetida não entra de novo: o texto fica no campo e o onValueChange não é chamado.",
		removeLabel: "Nome acessível do botão de remover de cada chip (traduza).",
		emptyText: "Aparece no popup quando nenhuma sugestão combina.",
		name: "Envia cada tag como um valor do formulário com este nome.",
		defaultOpen: "Abre o popup de sugestões na primeira renderização.",
		disabled: "Desativa os chips e o input.",
	}}
>
	Outros atributos de `<input>`, como `placeholder`, `type`, `onKeyDown` e `onPaste`, vão para o input interno.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio campo.

<StylingHooks
	slots={["tags-input", "tag", "tag-remove", "tags-input-input", "combobox-popup", "combobox-item"]}
	prefix="tag"
	attributes={[
		{ attr: "data-slot", value: '"tags-input" · "tag" · "tag-remove" · "tags-input-input" · "combobox-popup" · "combobox-item"' },
		{ attr: "data-highlighted", value: "no chip ou na sugestão sob o teclado" },
		{ attr: "data-popup-open", value: "no input enquanto as sugestões estão abertas" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "data-invalid", value: "no input dentro de um Field inválido" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "Adiciona a sugestão destacada, ou o texto digitado com allowCustom. Uma tag que já está na lista fica no campo." },
		{ key: "↓ / ↑", description: "Abre as sugestões e move o destaque." },
		{ key: "Backspace", description: "Com o input vazio, remove a última tag." },
		{ key: "← / →", description: "Move o foco entre os chips e de volta ao input." },
		{ key: "Delete / Backspace", description: "Num chip focado, remove o chip." },
		{ key: "Esc", description: "Fecha as sugestões." },
	]}
	notes={[
		"O input tem role=\"combobox\"; dentro de um Field, o FieldLabel dá nome a ele, e a descrição e o erro são lidos junto.",
		"O botão de remover de cada chip precisa de nome: o removeLabel monta a partir da tag, como \"Remover financeiro\". Traduza.",
		"Quando você recusa uma tag (duplicada, limite, e-mail inválido), mostre o motivo em texto no FieldError; uma recusa em silêncio parece tecla quebrada.",
		"O popup vai para um portal mas mantém o estilo pelo PortalScope, e o contraste passa no WCAG 2.2 AA nos 13 estilos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Combobox", description: "Escolha um valor de uma lista longa.", href: "/pt-br/docs/components/combobox" },
		{ title: "Chip", description: "Chips de filtro e removíveis fora de um campo.", href: "/pt-br/docs/components/chip" },
		{ title: "Checkbox", description: "Várias escolhas quando todas cabem na tela.", href: "/pt-br/docs/components/checkbox" },
	]}
/>


# Time field (/pt-br/docs/components/time-field)

<ComponentMeta file="date" primitive="React Aria" pattern="WAI-ARIA Spinbutton (um por segmento)" />

<Playground
	name="time-field/playground"
	component="TimeField"
	controls={[
		{ prop: "granularity", options: ["hour", "minute", "second"], default: "minute" },
		{ prop: "readOnly", default: false },
		{ prop: "invalid", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. `Time` é um horário do dia; `ZonedDateTime` acrescenta data e fuso horário. Os dois são reexportados pelo pacote.

<Import names="TimeField, Time, ZonedDateTime, Field, FieldLabel" />

## Anatomia [#anatomia]

As mesmas partes do `DateField`: uma caixa com um segmento para cada parte do horário, e separadores como `:` entre eles.

<Anatomy
	keys={[
		{ label: '[data-slot="time-field"]', color: "#8be36f" },
		{ label: '[data-slot="date-input"]', color: "#ffcf7a" },
		{ label: '[data-slot="date-segment"]', color: "#7cc7ff" },
	]}
>
	<span className="a-part">input</span>
	<span className="a-label">10</span>
	<span className="a-label">00</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="time-field/basic" compact />

<ExampleGrid>
	<Example name="time-field/window" title="Início e fim">
		Mude qualquer um dos horários. Dois campos controlados dão a duração, e o fim fica inválido quando vem antes do início.
	</Example>
	<Example name="time-field/business-hours" title="Dentro do expediente">
		Escolha um horário das 08:00 às 18:00. `minValue` e `maxValue` marcam o resto como inválido, e o `FieldError` diz a faixa aceita.
	</Example>
	<Example name="time-field/hour-cycle" title="12 ou 24 horas">
		O idioma escolhe o relógio. O `hourCycle` força um deles, para uma grade de horários ou um público que espera aquele formato.
	</Example>
	<Example name="time-field/granularity" title="Segundos">
		O `granularity="second"` acrescenta um segmento para marcações de tempo e durações. Use `"hour"` quando só a hora importa.
	</Example>
	<Example name="time-field/time-zone" title="Com fuso horário">
		Um `ZonedDateTime` mostra o fuso num segmento só de leitura, então quem está em outra cidade sabe de quem são as 10:00. O `hideTimeZone` esconde ele.
	</Example>
	<Example name="time-field/placeholder-value" title="Valor de partida">
		Num campo vazio, as setas começam da meia-noite. O `placeholderValue` começa num horário provável, sem preencher nada.
	</Example>
	<Example name="time-field/read-only" title="Somente leitura">
		O `readOnly` mantém o horário focável e lido pelo leitor de tela. Diga quem define ele.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Horários vêm com datas e agendas. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="time-field/context-hours" title="Horário de funcionamento" uses="Card · Switch · TimeField · Button" />
	<Context name="time-field/context-meeting" title="Agendamento de reunião" uses="Card · DateField · TimeField · Button" />
	<Context name="time-field/context-reminder" title="Resumo diário" uses="Card · Switch · TimeField · Checkbox" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="time-field/do-time-zone" title="Mostre o fuso quando as pessoas estão em lugares diferentes.">
		Um `ZonedDateTime` escreve o fuso ao lado do horário, então ninguém entra uma hora antes.
	</Guideline>
	<Guideline kind="dont" name="time-field/dont-no-zone" title="Horário solto num evento global.">
		Cada pessoa lê "10:00" no próprio fuso, e a maioria erra.
	</Guideline>
	<Guideline kind="do" name="time-field/do-two-fields" title="Dois campos com rótulo para uma faixa.">
		Início e fim são validados e lidos cada um por si.
	</Guideline>
	<Guideline kind="dont" name="time-field/dont-free-text" title="Caixa de texto para horários.">
		"10h30 às 10h45, mais ou menos" não dá para interpretar, ordenar nem conferir.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="date"
	type="TimeFieldProps"
	include={["value", "defaultValue", "onChange", "minValue", "maxValue", "placeholderValue", "granularity", "hourCycle", "hideTimeZone", "shouldForceLeadingZeros", "name", "autoFocus"]}
	types={{ value: "TimeValue | null", defaultValue: "TimeValue | null", onChange: "(value: TimeValue | null) => void", minValue: "TimeValue", maxValue: "TimeValue", placeholderValue: "TimeValue", granularity: "\"hour\" | \"minute\" | \"second\"", hourCycle: "12 | 24" }}
	describe={{ className: "Classes adicionadas à raiz.", style: "Estilos inline da raiz.", disabled: "Desativa todos os segmentos. Dentro de um `Field`, vale o `disabled` do field quando este não é passado.", readOnly: "Mantém o valor focável e legível, mas não editável.", invalid: "Marca o campo como inválido. Dentro de um `Field`, vale o `invalid` do field quando este não é passado.", required: "Marca o campo como obrigatório para as tecnologias assistivas.", locale: "Idioma BCP 47 para o relógio e os rótulos AM/PM, como `\"pt-BR\"` ou `\"en-US\"`. Sem ele, vale o `I18nProvider` mais próximo ou o idioma do navegador.", value: "O horário atual (controlado).", defaultValue: "O horário inicial (não controlado).", onChange: "Roda a cada mudança de valor. Recebe `null` quando um segmento é apagado.", minValue: "O menor horário aceito. Antes dele, o campo fica inválido.", maxValue: "O maior horário aceito. Depois dele, o campo fica inválido.", placeholderValue: "O horário de onde as setas partem num campo vazio. Padrão: meia-noite.", granularity: "A menor unidade mostrada. Padrão: `\"minute\"`.", hourCycle: "Força o relógio de 12 ou 24 horas. Padrão: o do idioma.", hideTimeZone: "Esconde o segmento de fuso horário de um `ZonedDateTime`.", shouldForceLeadingZeros: "Mostra zero à esquerda na hora, mesmo que o idioma não use.", name: "Nome do input escondido enviado com o formulário, em formato ISO.", autoFocus: "Foca o primeiro segmento ao montar." }}
>
	`TimeValue` é `Time`, `CalendarDateTime` ou `ZonedDateTime`; o tipo que você passa é o tipo que volta no `onChange`. O `validationBehavior` tem padrão `"aria"`: um horário fora dos limites marca o campo como inválido, mas nunca bloqueia o formulário.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio campo.

<StylingHooks
	slots={["time-field", "date-input", "date-segment"]}
	prefix="segment"
	attributes={[
		{ attr: "data-slot", value: '"time-field" · "date-input" · "date-segment"' },
		{ attr: "data-invalid", value: "na raiz e nos segmentos quando inválido" },
		{ attr: "data-disabled · data-readonly", value: "na raiz e nos segmentos quando desativado · somente leitura" },
		{ attr: "data-placeholder", value: "num segmento ainda sem valor" },
		{ attr: "data-type", value: "a parte do segmento: hour · minute · second · dayPeriod · timeZoneName · literal" },
		{ attr: "data-focused", value: "no segmento com foco" },
	]}
>

```css
/* um rótulo de fuso mais discreto */
[data-slot="time-field"] [data-type="timeZoneName"] {
  color: var(--cml-fg-muted);
  font-size: 0.875em;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "0–9", description: "Digita no segmento focado e avança quando ele enche." },
		{ key: "A · P", description: "Escolhe AM ou PM no segmento de período, no relógio de 12 horas." },
		{ key: "Seta para cima · Seta para baixo", description: "Soma ou subtrai um, voltando ao início no fim do segmento." },
		{ key: "Seta para a esquerda · Seta para a direita", description: "Passa de um segmento para outro." },
		{ key: "Page Up · Page Down", description: "Anda um passo maior, como 15 minutos." },
		{ key: "Backspace", description: "Apaga o segmento focado." },
	]}
	notes={[
		"Cada segmento é um spinbutton com o nome da sua parte (hora, minuto, AM/PM) e o rótulo do campo.",
		"O valor inteiro é lido como texto, como \"10:00 BRT\", com o fuso incluído.",
		"FieldDescription e FieldError ficam ligados pelo aria-describedby, e um campo inválido marca aria-invalid.",
		"Passe sempre o locale: assim o servidor e o navegador formatam igual, e o relógio segue o idioma da página.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Date field", description: "Dia, mês e ano digitados em segmentos.", href: "/pt-br/docs/components/date-field" },
		{ title: "Date picker", description: "Um campo de data com calendário em popover.", href: "/pt-br/docs/components/date-picker" },
		{ title: "Field", description: "Rótulo, descrição e erro de um controle.", href: "/pt-br/docs/components/field" },
	]}
/>


# Timeline (/pt-br/docs/components/timeline)

<ComponentMeta file="data-display" pattern="Lista ordenada HTML" />

<Playground
	name="timeline/playground"
	component="TimelineItem"
	controls={[{ prop: "tone", options: ["neutral", "brand", "success", "warning", "danger"], default: "brand" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Timeline, TimelineItem, TimelineTitle, TimelineDescription, TimelineTime" />

## Anatomia [#anatomia]

Uma lista ordenada. Cada item é uma linha com o indicador, o texto e o horário; a linha entre os indicadores é desenhada pelo CSS. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "timeline",
		tag: "ol",
		children: [
			{
				slot: "timeline-item",
				tag: "li",
				row: true,
				children: [
					{ slot: "timeline-indicator", tag: "span", note: "aria-hidden", children: [{ slot: "timeline-dot", tag: "span" }] },
					{ slot: "timeline-body", tag: "div", children: [{ slot: "timeline-title", tag: "p" }, { slot: "timeline-description", tag: "p" }] },
					{ slot: "timeline-time", tag: "time" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o skin, o modo e a marca escolhidos na barra acima.

<Preview name="timeline/basic" compact />

<ExampleGrid>
	<Example name="timeline/tones" title="Tons">
		Use `tone` para destacar problemas num histórico longo. A cor é só visual, então o título ainda precisa dizer o que aconteceu.
	</Example>
	<Example name="timeline/custom-icons" title="Ícones">
		Um ícone por tipo de evento ajuda a pessoa a passar o olho numa lista longa. Passe em `icon`, com `aria-hidden`: o título já diz a mesma coisa.
	</Example>
	<Example name="timeline/with-time" title="Horário legível por máquina">
		Passe `dateTime` junto com `time` quando um programa precisar da data exata, para ordenar ou levar a um calendário. A pessoa continua lendo a forma curta.
	</Example>
	<Example name="timeline/current-step" title="Etapa atual">
		Num processo em andamento, coloque `aria-current="step"` no item atual e deixe as próximas etapas neutras. O badge mostra a etapa para todos, não só pela cor.
	</Example>
	<Example name="timeline/rich-content" title="Links e avatares">
		Os children ficam embaixo da descrição, então um evento pode levar ao que ele mudou. Dê nome à lista com `aria-label` quando a página tiver mais de uma.
	</Example>
	<Example name="timeline/interactive-filter" title="Filtrando eventos">
		Escolha Alertas. A lista mantém a ordem, e uma linha de status diz ao leitor de tela quantos eventos sobraram, já que a mudança acontece longe do foco.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

A timeline costuma ficar num card ou num painel lateral, embaixo do registro a que pertence. Estas são partes inteiras de interface que você pode copiar, no skin que escolheu.

<ContextGrid>
	<Context name="timeline/context-shipping" title="Rastreio de pedido" uses="Card · Timeline · Badge" wide />
	<Context name="timeline/context-ticket" title="Histórico de chamado" uses="Card · Timeline · Avatar · Badge" wide />
	<Context name="timeline/context-changelog" title="Notas de versão" uses="Card · Timeline · Badge" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="timeline/do-iso-time" title="Dê data e hora reais a cada evento.">
		A pessoa precisa saber quando algo aconteceu, e o `dateTime` dá a mesma resposta aos programas.
	</Guideline>
	<Guideline kind="dont" name="timeline/dont-ambiguous-time" title='"Há um tempo" em todos os eventos.'>
		Horários vagos não se comparam, então ninguém sabe quanto tempo uma etapa levou.
	</Guideline>
	<Guideline kind="do" name="timeline/do-logical-order" title="Mantenha uma ordem: mais antigo ou mais recente primeiro.">
		Mais antigo primeiro conta um processo passo a passo; mais recente primeiro serve para feeds de atividade. Escolha uma por lista.
	</Guideline>
	<Guideline kind="dont" name="timeline/dont-mixed-tenses" title="Eventos fora de ordem.">
		A lista é um `<ol>`, então o leitor de tela anuncia cada posição, e uma ordem errada conta a história errada.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="data-display"
	type="TimelineItemProps"
	include={["tone", "icon", "title", "description", "time", "children"]}
	describe={{
		tone: "Cor do indicador. É só visual (o indicador tem `aria-hidden`), então o título precisa dizer o que aconteceu.",
		icon: "Substitui o ponto dentro do indicador, como um ícone ou um avatar pequeno. Fica escondido do leitor de tela.",
		title: "O que aconteceu, em poucas palavras. Vira um `TimelineTitle`.",
		description: "Detalhes embaixo do título. Vira um `TimelineDescription`.",
		time: "Quando aconteceu, no fim da linha, num `<time>`.",
		dateTime: "A forma legível por máquina de `time`, como `2026-10-27T09:14`.",
		children: "Conteúdo extra embaixo da descrição, como um link, um badge ou um TimelineTime com dateTime.",
	}}
>
	`Timeline` aceita os atributos de `<ol>`, e `TimelineItem` os de `<li>`, como `aria-current`. `TimelineTitle` e `TimelineDescription` aceitam os de `<p>`, e `TimelineTime` os de `<time>`, como `dateTime`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num skin ou na própria timeline.

<StylingHooks
	slots={["timeline", "timeline-item", "timeline-indicator", "timeline-dot", "timeline-body", "timeline-title", "timeline-description", "timeline-time"]}
	prefix="timeline"
	attributes={[{ attr: "data-tone", value: "neutral · brand · success · warning · danger (no item e no indicador)" }]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "A timeline não recebe foco. O Tab só passa pelos links e botões dentro dos eventos." }]}
	notes={[
		"A Timeline é um <ol> com role=\"list\", então os leitores de tela anunciam quantos eventos há e a posição de cada um, também no Safari.",
		"O indicador tem aria-hidden: o tom e o ícone nunca são lidos. Diga o resultado no título, como \"Health check falhou\".",
		"A prop time gera um <time>; inclua dateTime quando a data exata importar.",
		"Marque a etapa atual de um processo em andamento com aria-current=\"step\" no TimelineItem.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Progress", description: "Mostra quanto falta de uma tarefa, quando as etapas em si não importam.", href: "/pt-br/docs/components/progress" },
		{ title: "Data list", description: "Pares de rótulo e valor para os detalhes de um registro.", href: "/pt-br/docs/components/data-list" },
		{ title: "Badge", description: "Um status curto, como Entregue ou Resolvido, ao lado do título da timeline.", href: "/pt-br/docs/components/badge" },
	]}
/>


# Toast (/pt-br/docs/components/toast)

<ComponentMeta file="toast" primitive="Base UI" pattern="WAI-ARIA status" />

<Playground
	name="toast/playground"
	component="Toast"
	controls={[
		{ prop: "type", options: ["info", "success", "warning", "danger"], default: "info" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar.

<Import names="ToastProvider, useToast" />

### Um provider para o app inteiro [#um-provider-para-o-app-inteiro]

Coloque o `ToastProvider` uma vez só, perto da raiz, dentro do `StyleProvider`. Ele cria o canto onde os toasts se empilham e a região que o leitor de tela lê. Com dois providers, você tem duas pilhas uma sobre a outra e o leitor de tela fala em dobro.

```tsx title="app/layout.tsx"
import { StyleProvider, ToastProvider } from "@camaleo/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<html lang="pt-BR">
			<body>
				<StyleProvider styleName="editorial">
					<ToastProvider closeLabel="Fechar">{children}</ToastProvider>
				</StyleProvider>
			</body>
		</html>
	);
}
```

Depois é só chamar `useToast()` em qualquer componente abaixo dele:

```tsx
const toast = useToast();
toast.add({ title: "Preferências salvas", type: "success" });
```

## Anatomia [#anatomia]

Um canto da tela (o viewport) que empilha os toasts. Cada toast tem o ícone do tom, um título, uma descrição e uma ação opcionais e um botão de fechar.

<Anatomy
	keys={[
		{ label: '[data-slot="toast-viewport"]', color: "#8be36f" },
		{ label: '[data-slot="toast"]', color: "#ffcf7a" },
		{ label: "título · descrição · ação · fechar", color: "#7cc7ff" },
	]}
>
	<span className="a-part">viewport</span>
	<span className="a-part">toast</span>
	<span className="a-label">Preferências salvas</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Cada um tem seu próprio `ToastProvider` só para funcionar sozinho nesta página; no seu app, use o da raiz.

<Preview name="toast/basic" compact />

<ExampleGrid>
	<Example name="toast/tones" title="Tons">
		Clique em cada um. O `type` define a cor e o ícone: informação para andamento, sucesso quando deu certo, atenção quando pode dar errado, erro quando falhou.
	</Example>
	<Example name="toast/action-undo" title="Com desfazer">
		Clique em arquivar e depois em desfazer. Ofereça desfazer em ações fáceis de reverter, em vez de perguntar "Tem certeza?" antes.
	</Example>
	<Example name="toast/duration" title="Mais tempo na tela">
		O `timeout` é em milissegundos, e o padrão é 5000. Dê mais tempo a uma mensagem longa, para a pessoa conseguir terminar de ler.
	</Example>
	<Example name="toast/persistent" title="Fica até fechar">
		Com `timeout: 0`, o toast fica até a pessoa agir ou fechar. Use quando a mensagem ainda importa depois, como uma versão nova para recarregar.
	</Example>
	<Example name="toast/loading" title="Carregando, depois pronto">
		Clique em enviar. O `toast.promise()` mostra um toast de carregamento com spinner e depois o troca pelo de sucesso ou de erro quando a promise termina. Um toast só conta a história toda.
	</Example>
	<Example name="toast/urgent" title="Urgente">
		O `priority: "high"` interrompe o leitor de tela. Guarde para problemas que a pessoa precisa saber na hora, como a internet cair.
	</Example>
	<Example name="toast/stacked-avoid" title="Um toast para o lote">
		Depois de uma ação em lote, resuma num toast só: "12 contatos atualizados", e não doze toasts.
	</Example>
	<Example name="toast/a11y-polite" title="Lido sem mexer no foco">
		O toast é lido quando o leitor de tela fica livre, e o foco continua onde estava. A pessoa segue digitando.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O toast confirma ações feitas em outro ponto da página. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="toast/context-archive" title="Arquivar uma conversa" uses="Card · Toast · Button" />
	<Context name="toast/context-upload" title="Exportar um arquivo" uses="Card · Toast · Button" />
	<Context name="toast/context-copy" title="Copiar um link de convite" uses="Card · Toast · Button" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="toast/do-brief" title="Confirme o que acabou de acontecer.">
		Poucas palavras, lidas de relance: o que foi feito e, se ajudar, onde encontrar.
	</Guideline>
	<Guideline kind="dont" name="toast/dont-block" title="Pedir uma decisão num toast.">
		Ele some sozinho, e quem usa teclado pode nem chegar até ele. Para escolhas obrigatórias, use um diálogo.
	</Guideline>
	<Guideline kind="do" name="toast/do-single" title="Um toast para uma ação em lote.">
		"4 conversas arquivadas" diz tudo de uma vez e deixa a tela limpa.
	</Guideline>
	<Guideline kind="dont" name="toast/dont-flood" title="Um toast por item.">
		Uma pilha de toasts cobre a página, e o leitor de tela lê cada um deles.
	</Guideline>
</Guidelines>

## Props [#props]

<Props file="toast" type="ToastProviderProps" include={["timeout", "limit"]}
	describe={{
		closeLabel: "Nome do botão de fechar de cada toast, lido pelo leitor de tela. Traduza para o idioma da página.",
		timeout: "Tempo padrão na tela, em milissegundos, para todos os toasts. Com `0`, eles ficam até a pessoa fechar.",
		limit: "Quantos toasts aparecem ao mesmo tempo. Os mais antigos recebem `data-limited` e ficam escondidos até um mais novo fechar.",
	}}
>
	O `useToast()` devolve `add`, `update`, `close`, `promise` e a lista `toasts`. O `add` recebe `title`, `description`, `type`, `timeout`, `priority`, `actionProps` e `onClose`, e devolve o id do toast. O `type` é `info`, `success`, `warning` ou `danger`; `loading` (com spinner) e `error` (igual a `danger`) também funcionam, e são os que o `promise` usa.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no viewport.

<StylingHooks
	slots={["toast-viewport", "toast", "toast-content", "toast-title", "toast-description", "toast-close"]}
	attributes={[
		{ attr: "data-tone", value: "info · success · warning · danger" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "F6", description: "Leva o foco para a pilha de toasts, de qualquer lugar da página." },
		{ key: "Tab", description: "Passa pelos botões de ação e de fechar dos toasts." },
		{ key: "Escape", description: "Fecha o toast que está com o foco." },
	]}
	notes={[
		"O toast é lido sem pressa, depois do que o leitor de tela está falando. Com priority: \"high\", ele interrompe.",
		"O toast nunca pega o foco, então nunca atrapalha quem está digitando.",
		"O tempo para enquanto o ponteiro está sobre a pilha ou o foco está dentro dela.",
		"Se o toast tem uma ação, garanta que dá para fazer a mesma coisa em outro lugar da página, ou use timeout: 0. Nem todo mundo chega nele em 5 segundos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Alert", description: "Uma mensagem que fica na página até a situação mudar.", href: "/pt-br/docs/components/alert" },
		{ title: "AlertDialog", description: "Para o fluxo para confirmar algo que não dá para desfazer.", href: "/pt-br/docs/components/alert-dialog" },
		{ title: "Progress", description: "Mostra quanto falta de uma tarefa longa, dentro da página.", href: "/pt-br/docs/components/progress" },
	]}
/>


# Toggle (/pt-br/docs/components/toggle)

<ComponentMeta file="toggle" primitive="Base UI" pattern="WAI-ARIA Button (aria-pressed)" />

<Playground
	name="toggle/playground"
	component="Toggle"
	controls={[
		{ prop: "defaultPressed", default: false },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar.

<Import names="Toggle, ToggleGroup" />

## Anatomia [#anatomia]

Um `Toggle` é um botão com `aria-pressed`. O `ToggleGroup` junta vários e move o foco entre eles com as setas.

<Anatomy
	keys={[
		{ label: '[data-slot="toggle-group"]', color: "#8be36f" },
		{ label: '[data-slot="toggle"][data-pressed]', color: "#ffcf7a" },
		{ label: "ícone ou rótulo (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">B</span>
	<span className="a-part">I</span>
	<span className="a-label">U</span>
</Anatomy>

## Exemplos [#exemplos]

<Preview name="toggle/formatting" compact />

<ExampleGrid>
	<Example name="toggle/with-text" title="Com rótulo">
		Um ícone e um rótulo curto. O rótulo dá nome à opção, não ao estado.
	</Example>
	<Example name="toggle/controlled" title="Controlado">
		Clique. Com `pressed` e `onPressedChange`, o resto da tela reage ao estado.
	</Example>
	<Example name="toggle/group-single" title="Um entre vários">
		O `ToggleGroup` deixa só um pressionado, como o alinhamento do texto. As setas passam de uma opção para outra.
	</Example>
	<Example name="toggle/group-multiple" title="Vários ao mesmo tempo">
		Com `multiple`, qualquer quantidade fica pressionada: negrito, itálico e sublinhado juntos.
	</Example>
	<Example name="toggle/with-tooltip" title="Só ícone, com tooltip">
		O `aria-label` é o próprio texto do tooltip: o leitor de tela fala o mesmo nome que quem enxerga vê ao passar o mouse.
	</Example>
	<Example name="toggle/disabled" title="Desativado">
		Mantém o estado pressionado visível, para a pessoa ainda ver o que está ligado.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

<ContextGrid>
	<Context name="toggle/context-editor" title="Barra do editor" uses="ToggleGroup · Toggle · Separator" />
	<Context name="toggle/context-view" title="Troca de visualização" uses="ToggleGroup · Card" />
	<Context name="toggle/context-favorite" title="Favorito" uses="Toggle · Card" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="toggle/do-stable-label" title="Mantenha o rótulo igual.">
		O visual pressionado mostra o estado; o leitor de tela anuncia pelo `aria-pressed`.
	</Guideline>
	<Guideline kind="dont" name="toggle/dont-action" title="Toggle para uma ação única.">
		"Enviar" acontece uma vez. Use um `Button`.
	</Guideline>
	<Guideline kind="do" name="toggle/do-group" title="Agrupe opções relacionadas.">
		O `ToggleGroup` dá a elas uma só parada de Tab e navegação pelas setas.
	</Guideline>
	<Guideline kind="dont" name="toggle/dont-loose" title="Toggles soltos que deveriam ser exclusivos.">
		Dois alinhamentos pressionados juntos é um estado que não faz sentido.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="toggle"
	type="ToggleProps"
	include={["pressed", "defaultPressed", "onPressedChange", "value", "disabled", "render"]}
	types={{ render: "ReactElement | (props, state) => ReactElement" }}
	describe={{
		pressed: "Se está pressionado (controlado).",
		defaultPressed: "Se começa pressionado (não controlado).",
		onPressedChange: "Chamada quando o estado muda.",
		value: "Identifica o toggle dentro de um ToggleGroup.",
		disabled: "Desativa o toggle.",
		render: "Troca o elemento renderizado.",
	}}
/>

O `ToggleGroup` recebe `value`, `defaultValue` e `onValueChange` (listas com o `value` dos toggles), `multiple` e `orientation`.

## Styling hooks [#styling-hooks]

<StylingHooks
	slots={["toggle", "toggle-group"]}
	prefix="toggle"
	attributes={[
		{ attr: "data-slot", value: '"toggle" · "toggle-group"' },
		{ attr: "data-pressed", value: "presente quando pressionado" },
		{ attr: "data-disabled", value: "presente quando desativado" },
		{ attr: "aria-pressed", value: '"true" · "false"' },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Space", description: "Pressiona ou solta o toggle." },
		{ key: "Enter", description: "Pressiona ou solta o toggle." },
		{ key: "Setas", description: "Num ToggleGroup, levam o foco ao toggle anterior ou ao próximo." },
		{ key: "Home / End", description: "Num ToggleGroup, levam o foco ao primeiro ou ao último." },
	]}
	notes={[
		"Toggle só com ícone precisa de aria-label; o estado vem do aria-pressed, então o rótulo nunca muda.",
		"Dê a todo ToggleGroup um aria-label com o nome da opção (\"Alinhamento\").",
		"O visual pressionado tem contraste de 3:1 contra o solto em todos os estilos.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Button", description: "Para ações que acontecem uma vez.", href: "/pt-br/docs/components/button" },
		{ title: "Switch", description: "Liga e desliga configurações que valem na hora.", href: "/pt-br/docs/components/switch" },
		{ title: "Toolbar", description: "Junta botões e toggles numa só parada de Tab.", href: "/pt-br/docs/components/toolbar" },
	]}
/>


# Toggletip (/pt-br/docs/components/toggletip)

<ComponentMeta file="toggletip" primitive="Base UI" pattern="Botão + região não modal" />

<Playground
	name="toggletip/playground"
	component="ToggletipContent"
	controls={[
		{ prop: "align", options: ["start", "center", "end"], default: "center" },
		{ prop: "hideArrow", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Toggletip, ToggletipTrigger, ToggletipContent, ToggletipTitle, ToggletipDescription, ToggletipClose" />

## Anatomia [#anatomia]

O gatilho é um botão redondo (`toggletip-trigger`). A dica é renderizada num portal, dentro de um escopo que mantém o estilo, o modo e a cor da página em volta do botão.

<Anatomy
	tree={{
		slot: "toggletip-positioner",
		tag: "div",
		note: "num portal",
		children: [
			{
				slot: "toggletip-popup",
				tag: "div",
				note: "role=region, recebe o foco",
				children: [
					{ slot: "toggletip-arrow", tag: "div", note: "aria-hidden" },
					{ slot: "toggletip-title", tag: "h2", note: "dá nome à região" },
					{ slot: "toggletip-description", tag: "p" },
					{ slot: "toggletip-close", tag: "button", note: "opcional" },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Clique num botão "?" ou chegue nele com Tab e aperte Enter.

Qual usar? O **Tooltip** dá nome a um controle em poucas palavras, no hover. O **HoverCard** mostra uma prévia de para onde um link vai, no hover. O **Toggletip** explica um termo com um clique, então é o que funciona no toque e o que o leitor de tela lê.

<Preview name="toggletip/basic" compact />

<ExampleGrid>
	<Example name="toggletip/form-label" title="Ao lado do rótulo do campo">
		Coloque o botão depois do rótulo, não dentro dele, para o nome do campo continuar "E-mail de cobrança" e a ajuda ficar a um clique.
	</Example>
	<Example name="toggletip/table-header" title="No cabeçalho da tabela">
		Explique como uma métrica é calculada sem nota de rodapé. O `align="end"` mantém a dica dentro de uma coluna alinhada à direita.
	</Example>
	<Example name="toggletip/settings-row" title="Numa linha de configuração">
		Diga o que o switch faz de verdade, com a data ou o valor, antes de a pessoa ligar.
	</Example>
	<Example name="toggletip/a11y-name" title="Com o nome do assunto">
		Cada botão diz "Mais sobre …" e o assunto. Na lista de botões do leitor de tela, cinco botões "Info" iguais não dá para distinguir.
	</Example>
	<Example name="toggletip/with-link" title="Com um link dentro">
		Abra pelo teclado: o foco vai para a dica e o Tab leva ao link, então dá para chegar nele sem mouse. No máximo um link, para a explicação completa.
	</Example>
	<Example name="toggletip/title-close" title="Título e botão de fechar">
		Clique. O título dá nome à dica para o leitor de tela, e o `ToggletipClose` dá a quem usa toque um jeito claro de fechar. Passe um `aria-label` traduzido.
	</Example>
	<Example name="toggletip/alignment" title="Alinhamento" wide>
		O `align` alinha a dica com o início, o centro ou o fim do botão. O `side` escolhe o lado em que ela abre; ela troca de lado quando não há espaço.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O toggletip explica os termos bem onde a pessoa encontra eles. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="toggletip/context-pricing" title="Comparação de planos" uses="Table · Toggletip" />
	<Context name="toggletip/context-form" title="Simulador de empréstimo" uses="Card · Field · Input · Button · Toggletip" />
	<Context name="toggletip/context-settings" title="Configurações de segurança" uses="Card · Switch · Label · Toggletip" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="toggletip/do-toggletip" title="Toggletip para explicações.">
		Ele abre com clique ou toque, então celular, teclado e leitor de tela recebem o texto.
	</Guideline>
	<Guideline kind="dont" name="toggletip/dont-tooltip" title="Tooltip para explicações.">
		Ele depende de hover ou foco, então nunca abre no celular, e o leitor de tela pula ele.
	</Guideline>
	<Guideline kind="do" name="toggletip/do-short" title="Uma ou duas frases.">
		O bastante para entender o termo e continuar preenchendo o formulário.
	</Guideline>
	<Guideline kind="dont" name="toggletip/dont-long" title="Uma política inteira numa dica.">
		Três parágrafos não cabem numa caixa pequena. Escreva na página, ou leve a um artigo de ajuda.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="toggletip"
	type="ToggletipContentProps"
	describe={{
		sideOffset: "Distância em pixels entre o botão e a dica.",
		align: "Alinhamento da dica ao longo da borda do botão.",
		side: "De que lado do botão a dica abre. Ela troca de lado quando não há espaço.",
		hideArrow: "Esconde a seta que aponta para o botão.",
		children: "Um `ToggletipTitle`, um `ToggletipDescription` e, se quiser, um `ToggletipClose`.",
	}}
>
	O `Toggletip` aceita `open`, `onOpenChange` e `defaultOpen`. O `ToggletipTrigger` precisa de um `aria-label` como "Mais sobre a taxa de juros". O `ToggletipClose` recebe `aria-label` (padrão "Close tip"; traduza).
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria dica.

<StylingHooks
	slots={["toggletip-trigger", "toggletip-positioner", "toggletip-popup", "toggletip-arrow", "toggletip-title", "toggletip-description", "toggletip-close"]}
	prefix="toggletip"
	attributes={[
		{ attr: "data-popup-open", value: "no gatilho enquanto a dica está aberta" },
		{ attr: "data-side", value: "bottom · top" },
		{ attr: "data-align", value: "start · center · end" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Enter", description: "No botão, abre a dica e leva o foco para a própria dica, para o texto ser lido primeiro. O Tab então chega ao link ou ao botão de fechar." },
		{ key: "Space", description: "O mesmo que Enter." },
		{ key: "Tab", description: "Dentro da dica, vai para o próximo link ou botão. Depois do último, o foco segue para o que vem depois do botão e a dica fecha." },
		{ key: "Escape", description: "Fecha a dica e devolve o foco ao botão." },
	]}
	notes={[
		"O foco entra na dica quando ela abre, então o leitor de tela lê: uma região com o nome do título e a descrição do texto. Não é uma live region, então nada é anunciado enquanto o foco está em outro lugar.",
		"O botão não tem texto visível. Dê a ele um aria-label com o assunto, como \"Mais sobre a taxa de juros\". Sem ToggletipTitle, passe aria-label também para o ToggletipContent.",
		"Um clique ou toque fora fecha a dica, e o resto da página continua usável: não é um diálogo, então o botão informa aria-expanded, mas não aria-haspopup.",
		"O foco vai para a própria dica, então o leitor de tela lê a explicação antes de qualquer link ou botão de fechar. Use no máximo um link, e mantenha o texto curto.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Tooltip", description: "Um rótulo curto para botão de ícone, no hover ou no foco.", href: "/pt-br/docs/components/tooltip" },
		{ title: "HoverCard", description: "Uma prévia do destino de um link, no hover ou no foco.", href: "/pt-br/docs/components/hover-card" },
		{ title: "Field", description: "Rótulo, descrição e erro de um controle de formulário.", href: "/pt-br/docs/components/field" },
	]}
/>


# Toolbar (/pt-br/docs/components/toolbar)

<ComponentMeta file="toolbar" primitive="Base UI" pattern="WAI-ARIA Toolbar" />

<Playground
	name="toolbar/playground"
	component="Toolbar"
	controls={[
		{ prop: "orientation", options: ["horizontal", "vertical"], default: "horizontal" },
		{ prop: "loopFocus", default: true },
		{ prop: "disabled", default: false },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="Toolbar, ToolbarGroup, ToolbarButton, ToolbarToggle, ToolbarLink, ToolbarInput, ToolbarSeparator" />

## Anatomia [#anatomia]

Um `div` com `role="toolbar"`. Só um controle dele fica na ordem do Tab por vez; as setas mudam qual é. Um `ToggleGroup` dentro entra na mesma ordem quando os toggles são renderizados pelo `ToolbarButton`.

<Anatomy
	tree={{
		slot: "toolbar",
		tag: "div",
		note: "role=toolbar, data-orientation",
		row: true,
		children: [
			{
				slot: "toolbar-group",
				tag: "div",
				note: "role=group",
				row: true,
				children: [
					{ slot: "toolbar-toggle", tag: "button", note: "aria-pressed" },
					{ slot: "toolbar-button", tag: "button" },
				],
			},
			{ slot: "toolbar-separator", tag: "div", note: "role=separator" },
			{ slot: "toolbar-link", tag: "a" },
			{ slot: "input", tag: "input", note: "ToolbarInput" },
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. Clique num deles e use o Tab e as setas.

<Preview name="toolbar/basic" compact />

<ExampleGrid>
	<Example name="toolbar/table-actions" title="Ações para as linhas selecionadas" wide>
		Selecione pedidos e clique em Exportar. A busca fica ao lado da toolbar, não dentro: ela procura na tabela, não na seleção, então tem sua própria parada do Tab.
	</Example>
	<Example name="toolbar/vertical" title="Paleta de ferramentas vertical">
		Com `orientation="vertical"`, as setas para cima e para baixo movem o foco. As ferramentas são um `ToggleGroup`, então só uma fica pressionada.
	</Example>
	<Example name="toolbar/icon-tooltips" title="Botões de ícone com nome">
		Todo botão só de ícone precisa de `aria-label`. Um tooltip com as mesmas palavras mostra esse nome também para quem enxerga.
	</Example>
	<Example name="toolbar/overflow" title="O que não cabe vai para Mais" wide>
		Estreite a janela. Abaixo de 420 px ficam só Responder e Responder a todos; o resto vai para o menu Mais em vez de quebrar a linha.
	</Example>
	<Example name="toolbar/disabled" title="Desativado, mas alcançável">
		Botões desativados continuam na ordem das setas, então a pessoa encontra o Desfazer e ouve por que ele está desligado. Passe `focusableWhenDisabled={false}` para pular um deles.
	</Example>
	<Example name="toolbar/input" title="Um campo dentro da toolbar">
		Digite um número de página e aperte Enter. O `ToolbarInput` entra na ordem das setas; dentro dele as setas movem o cursor e só saem do campo nas pontas do texto.
	</Example>
	<Example name="toolbar/links" title="Links ao lado de botões">
		O `ToolbarLink` leva a outra página e o `ToolbarButton` age nesta; os dois dividem a mesma ordem das setas.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="toolbar/context-email" title="Leitor de e-mail" uses="Card · Toolbar · Tooltip · Menu · Avatar" />
	<Context name="toolbar/context-files" title="Gerenciador de arquivos" uses="Card · Toolbar · ToggleGroup · Tooltip · Menu" />
	<Context name="toolbar/context-image" title="Visualizador de imagem" uses="Card · Toolbar · Tooltip" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="toolbar/do-group" title="Agrupe controles relacionados.">
		Histórico, formatação e inserir ganham cada um seu `ToolbarGroup` com nome, separados por divisórias.
	</Guideline>
	<Guideline kind="dont" name="toolbar/dont-flat" title="Uma fileira comprida sem ordem.">
		Negrito ao lado de Desfazer ao lado de Imagem: a pessoa varre a fileira inteira toda vez.
	</Guideline>
	<Guideline kind="do" name="toolbar/do-labels" title="Palavras para ações pouco conhecidas.">
		Negrito e Desfazer são reconhecidos pelo ícone. "Níveis" e "Vinheta", não.
	</Guideline>
	<Guideline kind="dont" name="toolbar/dont-ambiguous" title="Só ícones, para ações que ninguém reconhece.">
		O leitor de tela ouve os nomes, mas o resto das pessoas precisa adivinhar ou passar o mouse em cada um.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="toolbar"
	type="ToolbarProps"
	include={["orientation", "loopFocus", "disabled", "aria-label"]}
	types={{ "aria-label": "string", orientation: "\"horizontal\" | \"vertical\"" }}
	describe={{
		orientation: "Quais setas movem o foco: esquerda e direita, ou cima e baixo. Também coloca a toolbar em coluna.",
		loopFocus: "Se as setas voltam do último controle para o primeiro.",
		disabled: "Desativa todos os controles da toolbar.",
		"aria-label": "Dá nome à toolbar, por exemplo \"Formatação do texto\".",
	}}
>
	O `ToolbarToggle` recebe `pressed` e é controlado: inverta o valor no `onClick`. O `ToolbarButton` recebe `disabled` e `focusableWhenDisabled` (padrão `true`). O `ToolbarGroup` recebe `disabled` e um `aria-label`. O `ToolbarInput` recebe as props de `<input>`; dê nome a ele com `aria-label`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria toolbar.

<StylingHooks
	slots={["toolbar", "toolbar-group", "toolbar-button", "toolbar-toggle", "toolbar-link", "toolbar-separator"]}
	prefix="toolbar"
	attributes={[
		{ attr: "data-orientation", value: "horizontal · vertical" },
		{ attr: "aria-pressed · data-pressed", value: "num ToolbarToggle pressionado" },
		{ attr: "data-disabled", value: "num controle desativado" },
		{ attr: "data-focusable", value: "num controle desativado que continua focável" },
	]}
>

```css
/* alvos maiores no app de desenho */
.canvas-tools [data-slot="toolbar"] {
  --cml-toolbar-btn-size: 2.5rem;
}
```

</StylingHooks>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Entra na toolbar, no controle que teve o foco por último, e depois sai dela. A toolbar inteira é uma parada do Tab." },
		{ key: "Seta direita / Seta esquerda", description: "Vai para o controle seguinte ou anterior, incluindo os toggles de um ToggleGroup. Do último volta para o primeiro (loopFocus)." },
		{ key: "Seta para baixo / Seta para cima", description: "O mesmo, numa toolbar com orientation=\"vertical\". Ali, esquerda e direita não fazem nada." },
		{ key: "Enter / Space", description: "Ativa o botão, pressiona ou solta o toggle, ou abre o menu com o foco no primeiro item." },
		{ key: "Home / End", description: "Vai para o primeiro ou o último controle. Num ToolbarInput, movem o cursor do texto." },
		{ key: "Escape", description: "Num menu aberto pela toolbar, fecha o menu e devolve o foco ao botão dele." },
	]}
	notes={[
		"Dê nome a toda toolbar com aria-label (\"Formatação do texto\") e a todo ToolbarGroup ou ToggleGroup que reúna um conjunto (\"Alinhamento\").",
		"O ToolbarToggle marca aria-pressed, então o leitor de tela diz \"Negrito, botão de alternância, pressionado\". Mantenha o rótulo igual nos dois estados.",
		"Botões desativados continuam na ordem das setas com aria-disabled, então a pessoa ainda os encontra. Diga o motivo com aria-describedby.",
		"Dê nome ao ToolbarInput com aria-label. Um campo que serve a página toda, como uma busca, fica melhor ao lado da toolbar, com sua própria parada do Tab.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Toggle", description: "Um botão que fica pressionado, e grupos deles.", href: "/pt-br/docs/components/toggle" },
		{ title: "Menu", description: "Para onde vão as ações que não cabem.", href: "/pt-br/docs/components/menu" },
		{ title: "Tooltip", description: "Mostra o nome de um botão de ícone no hover e no foco.", href: "/pt-br/docs/components/tooltip" },
	]}
/>


# Tooltip (/pt-br/docs/components/tooltip)

<ComponentMeta file="popover" primitive="Base UI" pattern="WAI-ARIA Tooltip" />

<Playground
	name="tooltip/playground"
	component="TooltipContent"
	controls={[
		{ prop: "side", options: ["top", "bottom", "left", "right"], default: "top" },
		{ prop: "align", options: ["start", "center", "end"], default: "center" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no cliente.

<Import names="TooltipProvider, Tooltip, TooltipTrigger, TooltipContent" />

## Anatomia [#anatomia]

Um gatilho e um popup com seta. O popup é renderizado num portal, então um elemento pai com `overflow: hidden` não corta ele.

<Anatomy
	keys={[
		{ label: '[data-slot="tooltip-popup"]', color: "#8be36f" },
		{ label: '[data-slot="tooltip-arrow"]', color: "#ffcf7a" },
		{ label: "conteúdo (children)", color: "#7cc7ff" },
	]}
>
	<span className="a-part">arrow</span>
	<span className="a-part">popup</span>
	<span className="a-label">Baixar fatura</span>
</Anatomy>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima. O leitor de tela não lê o tooltip, então num botão de ícone o `aria-label` precisa dizer exatamente o que o tooltip diz.

<Preview name="tooltip/basic" compact />

<ExampleGrid>
	<Example name="tooltip/a11y-non-essential" title="Mesmo texto do rótulo">
		O tooltip mostra, para quem enxerga, o nome que o leitor de tela fala. Escreva uma vez e use no `aria-label` e no tooltip.
	</Example>
	<Example name="tooltip/with-kbd" title="Com atalho">
		Coloque um `Kbd` para ensinar o atalho e `aria-keyshortcuts` no gatilho, para quem usa leitor de tela aprender também.
	</Example>
	<Example name="tooltip/placements" title="Lados" wide>
		Aponte o tooltip para onde a ação vai: para cima em "Mover para cima", para a direita em "Próxima". Se não couber, ele vira para o outro lado.
	</Example>
	<Example name="tooltip/delay" title="Espera compartilhada na barra">
		Passe o mouse num botão e deslize para o próximo. Um `TooltipProvider` em volta do grupo só espera no primeiro tooltip; os outros abrem na hora.
	</Example>
	<Example name="tooltip/interactive-copy" title="Copiar e confirmar">
		Clique. O tooltip muda para "Copiado" para quem vê, e uma mensagem de status escondida diz "Link copiado" para o leitor de tela.
	</Example>
	<Example name="tooltip/disabled" title="Em botão desativado">
		Botão desativado não recebe hover nem foco, então o tooltip nunca abre. Use `focusableWhenDisabled` e ligue o motivo com `aria-describedby`.
	</Example>
	<Example name="tooltip/truncated" title="Nome cortado por inteiro">
		Mostre o nome completo do arquivo quando ele não couber. Deixe o nome inteiro no texto do link, para o leitor de tela ler tudo.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

O tooltip dá nome aos botões que só têm ícone. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="tooltip/context-toolbar" title="Barra de formatação" uses="Card · ButtonGroup · Tooltip · Kbd" />
	<Context name="tooltip/context-nav-rail" title="Menu lateral de ícones" uses="IconButton · Tooltip" />
	<Context name="tooltip/context-editor" title="Ações do editor de código" uses="Card · ButtonGroup · Tooltip" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="tooltip/do-short-text" title="Poucas palavras, iguais ao rótulo.">
		"Salvar alterações" se lê de relance e é exatamente o que o leitor de tela fala.
	</Guideline>
	<Guideline kind="dont" name="tooltip/dont-interactive-content" title="Links ou botões dentro do tooltip.">
		Ele fecha assim que o mouse sai, e quem usa teclado não consegue chegar lá. Use um popover.
	</Guideline>
	<Guideline kind="do" name="tooltip/do-keyboard-shortcut" title="Mostre o atalho.">
		A pessoa aprende na hora em que usa a ação, sem abrir a ajuda.
	</Guideline>
	<Guideline kind="dont" name="tooltip/dont-essential-info" title="Regras só no tooltip.">
		No celular não existe hover, e o leitor de tela não lê o tooltip. Coloque as regras da senha na descrição do campo.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="popover"
	type="TooltipContentProps"
	describe={{
		side: "De que lado do gatilho o tooltip aparece. Se não couber, ele vira para o lado oposto.",
		align: "Alinhamento do tooltip ao longo desse lado.",
	}}
>
	O `TooltipProvider` recebe `delay` (ms antes de abrir o primeiro tooltip, padrão 600) e `closeDelay` (ms antes de fechar). O `TooltipTrigger` aceita os mesmos dois para um tooltip só, e o `Tooltip` aceita `disabled`, `open` e `onOpenChange`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio popup.

<StylingHooks
	slots={["tooltip-trigger", "tooltip-positioner", "tooltip-popup", "tooltip-arrow"]}
	attributes={[
		{ attr: "data-side", value: "top · bottom · left · right" },
		{ attr: "data-align", value: "start · center · end" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Ao focar o gatilho, o tooltip abre depois da espera." },
		{ key: "Escape", description: "Fecha o tooltip. O foco continua no gatilho." },
	]}
	notes={[
		"O leitor de tela não lê o tooltip: nada liga ele ao gatilho. Num botão de ícone, o aria-label precisa ser o texto do tooltip, palavra por palavra.",
		"O que a pessoa precisa saber vai na página, não só no tooltip. Tela de toque não tem hover, então lá o tooltip nunca abre.",
		"Botão desativado não recebe hover nem foco. Deixe ele focável com focusableWhenDisabled, ou escreva o motivo ao lado do botão.",
		"Dá para levar o mouse até o tooltip sem ele fechar, como pede o WCAG 1.4.13.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Popover", description: "Um painel flutuante para links, formulários ou ações.", href: "/pt-br/docs/components/popover" },
		{ title: "Toggletip", description: "Abre com um clique, então funciona também em tela de toque.", href: "/pt-br/docs/components/toggletip" },
		{ title: "Kbd", description: "Mostra um atalho de teclado, num tooltip ou no texto.", href: "/pt-br/docs/components/kbd" },
	]}
/>


# TreeView (/pt-br/docs/components/tree-view)

<ComponentMeta file="tree-view" pattern="WAI-ARIA Tree View" />

<Playground
	name="tree-view/playground"
	component="TreeView"
	controls={[{ prop: "selectionMode", options: ["single", "multiple"], default: "single" }]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele roda no cliente, porque guarda os ramos abertos e a seleção.

<Import names="TreeView, TreeItem" />

## Anatomia [#anatomia]

Uma lista de itens, em que o item com filhos abre um grupo aninhado. Cada parte tem um `data-slot` que você pode usar no CSS.

<Anatomy
	tree={{
		slot: "tree-view",
		tag: "ul",
		children: [
			{
				slot: "tree-item",
				tag: "li",
				children: [
					{
						slot: "tree-item-row",
						tag: "div",
						row: true,
						children: [
							{ slot: "tree-item-chevron", tag: "span", note: "ramos" },
							{ slot: "tree-item-spacer", tag: "span", note: "folhas" },
							{ slot: "tree-item-icon", tag: "span" },
							{ slot: "tree-item-label", tag: "span" },
							{ slot: "tree-item-meta", tag: "span", note: "opcional" },
						],
					},
					{ slot: "tree-group", tag: "ul", note: "quando aberto", children: [{ slot: "tree-item", tag: "li" }] },
				],
			},
		],
	}}
/>

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="tree-view/basic" compact />

<ExampleGrid>
	<Example name="tree-view/default-expanded" title="Aberta no item atual">
		Abra os ramos que levam ao item selecionado com `defaultExpandedValues`. A pessoa vê onde está sem clicar, e o Tab cai nesse item.
	</Example>
	<Example name="tree-view/multi-selection" title="Vários itens de uma vez">
		Use `selectionMode="multiple"` quando a pessoa age sobre um lote, como mover arquivos. O Espaço adiciona ou tira um item e mantém os outros.
	</Example>
	<Example name="tree-view/custom-icons" title="Ícones para o tipo de item">
		Passe `icon` quando os itens são de tipos diferentes, como servidores e bancos. O ícone fica oculto para leitores de tela, então o rótulo precisa dizer tudo.
	</Example>
	<Example name="tree-view/with-meta" title="Uma informação por linha">
		Use `meta` para um valor curto, como tamanho ou contagem. Leitores de tela leem junto com o rótulo, então use poucos caracteres.
	</Example>
	<Example name="tree-view/interactive-file-tree" title="Reagir à seleção">
		Clique em um arquivo ou aperte Enter nele. Controle `selectedValues` quando outra parte da página mostra o que foi escolhido, como um editor ou uma prévia.
	</Example>
	<Example name="tree-view/labelled" title="Nomeada pelo título">
		Aponte `aria-labelledby` para o título visível, para o leitor de tela dizer o que a árvore contém. A árvore é uma parada de Tab; as setas andam dentro dela.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Árvores costumam ficar numa barra lateral ou num card, ao lado do conteúdo que abrem. Estas são peças inteiras de interface que você pode copiar, no estilo que escolheu.

<ContextGrid>
	<Context name="tree-view/context-filesystem" title="Explorador de arquivos" uses="Card · TreeView · Badge" wide />
	<Context name="tree-view/context-categories" title="Filtro por categoria" uses="Card · TreeView · Button" wide />
	<Context name="tree-view/context-mail" title="Pastas de e-mail" uses="Card · TreeView · Badge" wide />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="tree-view/do-nested" title="Use árvore para itens aninhados.">
		Pastas, categorias e seções com subseções são o motivo de existirem as setas de abrir e fechar.
	</Guideline>
	<Guideline kind="dont" name="tree-view/dont-flat-list" title="Árvore para uma lista simples.">
		Sem ramos, a árvore só acrescenta setas e anúncios à toa. Use uma lista, links ou um menu.
	</Guideline>
	<Guideline kind="do" name="tree-view/do-short-labels" title="Rótulos curtos, o caminho nos ramos.">
		O ramo acima já diz onde o item está, então o rótulo só precisa do próprio nome.
	</Guideline>
	<Guideline kind="dont" name="tree-view/dont-long-labels" title="O caminho inteiro em cada rótulo.">
		Rótulos longos são cortados em telas estreitas, e o leitor de tela repete as mesmas palavras em toda linha.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="tree-view"
	type="TreeViewProps"
	describe={{
		expandedValues: "Ramos abertos (controlado).",
		defaultExpandedValues: "Ramos abertos no início (não controlado).",
		onExpandedChange: "Chamado com a nova lista quando um ramo abre ou fecha.",
		selectedValues: "Itens selecionados (controlado). O primeiro também é onde o Tab entra.",
		defaultSelectedValues: "Itens selecionados no início (não controlado). O primeiro também é onde o Tab entra.",
		onSelectedChange: "Chamado com a nova lista quando a seleção muda.",
		selectionMode: "\"single\" seleciona um item, \"multiple\" vários e \"none\" desliga a seleção.",
	}}
/>

<Props
	file="tree-view"
	type="TreeItemProps"
	describe={{
		value: "Identificador único na árvore inteira, como o caminho do item.",
		label: "Texto visível da linha.",
		meta: "Valor curto à direita, como tamanho ou contagem. É lido junto com o rótulo.",
		icon: "Ícone no lugar da pasta ou do arquivo padrão.",
		children: "Itens filhos. Um item com filhos vira um ramo.",
	}}
>
	Cada item precisa de um `value` único na árvore inteira, como o caminho: dois itens com o mesmo valor abrem e são selecionados juntos. `TreeView` também aceita os atributos de `<ul>`, e `TreeItem` os de `<li>`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria árvore.

<StylingHooks
	slots={["tree-view", "tree-item", "tree-item-row", "tree-item-chevron", "tree-item-spacer", "tree-item-icon", "tree-item-label", "tree-item-meta", "tree-group"]}
	prefix="tree"
	attributes={[
		{ attr: "data-selected", value: "em tree-item e tree-item-row, quando selecionado" },
		{ attr: "data-expanded", value: "no tree-item de um ramo, quando aberto" },
		{ attr: "data-value", value: "o value do item, em tree-item" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[
		{ key: "Tab", description: "Entra na árvore, no item selecionado, e sai dela. A árvore inteira é uma parada." },
		{ key: "↓ / ↑", description: "Vai para o próximo item visível ou o anterior." },
		{ key: "→", description: "Abre um ramo fechado. Num ramo aberto, vai para o primeiro filho." },
		{ key: "←", description: "Fecha um ramo aberto. Num filho, volta para o pai." },
		{ key: "Home / End", description: "Vai para o primeiro ou o último item visível." },
		{ key: "Espaço", description: "Seleciona o item. Com seleção múltipla, adiciona ou tira o item." },
		{ key: "Enter", description: "Faz o mesmo que o Espaço e também abre ou fecha um ramo." },
	]}
	notes={[
		"A árvore é uma lista role=\"tree\". Ramos têm aria-expanded e abrem um role=\"group\"; itens têm aria-selected, e a seleção múltipla acrescenta aria-multiselectable.",
		"O Tab entra no item selecionado, ou no primeiro item quando nada selecionado está visível.",
		"Dê um nome à árvore com aria-label, ou com aria-labelledby apontando para o título.",
		"Não há busca ao digitar: em listas longas, coloque um campo de busca acima da árvore.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Accordion", description: "Seções que abrem e fecham, para conteúdo e não para uma lista de itens.", href: "/pt-br/docs/components/accordion" },
		{ title: "Data table", description: "Linhas e colunas com ordenação e filtros, para registros sem hierarquia.", href: "/pt-br/docs/components/data-table" },
		{ title: "Card", description: "A superfície que costuma conter a árvore numa barra lateral ou num painel.", href: "/pt-br/docs/components/card" },
	]}
/>


# Typography (/pt-br/docs/components/typography)

<ComponentMeta file="typography" pattern="WAI-ARIA heading / paragraph" />

<Playground
	name="typography/playground"
	component="Heading"
	controls={[
		{ prop: "level", options: [1, 2, 3, 4], default: 2 },
		{ prop: "size", options: ["display", "lg", "md", "sm"], default: "lg" },
	]}
/>

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o que precisar. Ele renderiza no servidor.

<Import names="Heading, Text" />

## Anatomia [#anatomia]

Dois elementos separados: `Heading` renderiza de `<h1>` a `<h4>`, e `Text` renderiza um `<p>`. Cada um tem um `data-slot` que você pode usar no CSS.

<Anatomy tree={{ slot: "heading", tag: "h1–h4", note: "data-size define o visual" }} />

<Anatomy tree={{ slot: "text", tag: "p", note: "data-variant · data-drop-cap" }} />

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

<Preview name="typography/basic" compact />

<ExampleGrid>
	<Example name="typography/heading-levels" title="Quatro tamanhos" wide>
		Use o maior tamanho uma vez só, no topo da página. Depois, o grande para seções, o médio para cards e painéis e o pequeno para grupos dentro deles.
	</Example>
	<Example name="typography/outline" title="Nível e tamanho separados">
		Aqui há um `h2` e dois `h3` num painel de configurações, mas desenhados pequenos. A estrutura continua certa para o leitor de tela, e o painel não grita.
	</Example>
	<Example name="typography/interactive-scale" title="Teste os tamanhos">
		Clique num tamanho. O título muda de visual, mas continua um `h2`, então a estrutura da página não muda.
	</Example>
	<Example name="typography/text-variants" title="Texto normal e pequeno">
		Use o texto normal para o que a pessoa lê. Use o pequeno para o que ela só bate o olho ou pula: datas, tempo de leitura, letras miúdas.
	</Example>
	<Example name="typography/inline" title="Destaque e links na frase">
		Use `<strong>` para o fato que a pessoa não pode perder e `<em>` para dar ênfase. Um `Link` dentro do `Text` mantém o tamanho do parágrafo.
	</Example>
	<Example name="typography/measure" title="Largura da linha" wide>
		Limite os parágrafos a uns 65 caracteres por linha com `maxInlineSize: "65ch"` no contêiner. Com linhas mais longas, fica difícil achar o começo da próxima.
	</Example>
	<Example name="typography/drop-cap" title="Letra capitular">
		Passe `dropCap` no primeiro parágrafo de um artigo longo. Guarde para páginas editoriais; num app ela só atrapalha.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Títulos e texto carregam quase toda a página. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="typography/context-blog" title="Abertura de artigo" uses="Heading · Text" />
	<Context name="typography/context-hero" title="Topo de landing page" uses="Heading · Text · Button" />
	<Context name="typography/context-legal" title="Termos de uso" uses="Heading · Text" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="typography/do-separate-level-size" title="Escolha o nível pela estrutura e o tamanho pelo espaço.">
		Um `h2` numa barra lateral pode usar `size="sm"`. Ele parece pequeno e continua sendo uma seção para o leitor de tela.
	</Guideline>
	<Guideline kind="dont" name="typography/dont-skip-levels" title="Um h4 só para mudar o tamanho.">
		Pular do `h2` para o `h4` deixa um buraco na estrutura, e quem navega por títulos acha que perdeu uma seção.
	</Guideline>
	<Guideline kind="do" name="typography/do-readable-measure" title="Mantenha as linhas entre 45 e 75 caracteres.">
		Nessa largura o olho acha a próxima linha com facilidade, mesmo em textos longos.
	</Guideline>
	<Guideline kind="dont" name="typography/dont-long-lines" title="Parágrafos da largura da tela.">
		Num monitor grande, uma linha passa de 150 caracteres e a pessoa se perde.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="typography"
	type="HeadingProps"
	describe={{
		level: "A tag do título, de h1 a h4. Escolha pela estrutura da página; o `size` define o tamanho que aparece.",
		size: "O tamanho que aparece: `display` para o topo da página, `lg` para seções, `md` para cards e painéis, `sm` para grupos pequenos.",
	}}
/>

<Props
	file="typography"
	type="TextProps"
	describe={{
		variant: "`body` para o texto que a pessoa lê, `small` para datas, legendas e letras miúdas.",
		dropCap: "Aumenta a primeira letra e encaixa ela nas primeiras linhas, para abrir artigos.",
	}}
>
	`Heading` e `Text` também aceitam os atributos do elemento HTML, como `id` e `className`.
</Props>

## Styling hooks [#styling-hooks]

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio elemento.

<StylingHooks
	slots={["heading", "text"]}
	attributes={[
		{ attr: "data-size", value: "display · lg · md · sm" },
		{ attr: "data-variant", value: "body · small" },
		{ attr: "data-drop-cap", value: "presente quando dropCap está ligado" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "—", description: "Títulos e parágrafos não recebem foco. Quem usa leitor de tela pula entre títulos com as teclas do próprio leitor (H no NVDA e no JAWS, o rotor no VoiceOver)." }]}
	notes={[
		"Use um h1 por página e desça um nível de cada vez. Nunca pule um nível para ter um tamanho menor: mude o size.",
		"O título deve dizer do que a seção trata. Muita gente passa pela lista de títulos antes de ler qualquer coisa.",
		"Deixe os parágrafos com uns 65 caracteres de largura e deixe o texto quebrar. Não corte texto que a pessoa precisa ler.",
		"Não use um título só para ter letra grande. Se ele não abre uma seção, use Text com o seu estilo.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Link", description: "Links dentro de frases e sozinhos numa linha.", href: "/pt-br/docs/components/link" },
		{ title: "Separator", description: "Uma linha entre seções quando só o espaço não basta.", href: "/pt-br/docs/components/separator" },
		{ title: "Code block", description: "Trechos de código com destaque de sintaxe e botão de copiar.", href: "/pt-br/docs/components/code-block" },
	]}
/>


# VisuallyHidden (/pt-br/docs/components/visually-hidden)

<ComponentMeta file="visually-hidden" pattern="Visually hidden content (clip pattern)" />

## Instalação [#instalação]

Configure o Camaleo uma vez ([Instalação](/pt-br/docs/installation)) e importe o componente. Ele não tem estado, então renderiza no servidor.

<Import names="VisuallyHidden" />

## Anatomia [#anatomia]

Um `<span>` reduzido a 1 × 1 px e recortado. Ele continua na página e na árvore de acessibilidade, então leitores de tela e ferramentas de tradução ainda recebem o texto.

<Anatomy
	tree={{
		slot: "visually-hidden",
		tag: "span",
		note: "position: absolute · 1 × 1 px · clip",
	}}
/>

### Por que não `display: none` ou `hidden`? [#por-que-não-display-none-ou-hidden]

`display: none`, `visibility: hidden` e o atributo `hidden` tiram o elemento da árvore de acessibilidade junto com a tela: ninguém recebe o texto. `aria-hidden="true"` faz o contrário do que você quer aqui: continua na tela e o leitor de tela pula. O VisuallyHidden é o único jeito de deixar um texto só para a tecnologia assistiva.

## Exemplos [#exemplos]

Cada exemplo é um arquivo real que você pode copiar. Ligue um leitor de tela (VoiceOver, NVDA ou TalkBack) para ouvir o texto escondido, ou abra a árvore de acessibilidade nas ferramentas de desenvolvedor do navegador.

<Preview name="visually-hidden/basic" compact />

<ExampleGrid>
	<Example name="visually-hidden/vs-display-none" title="Quatro jeitos de esconder" wide>
		Só o VisuallyHidden tira o texto da tela e mantém para o leitor de tela. `display: none` e `hidden` escondem de todo mundo; `aria-hidden` esconde só do leitor de tela.
	</Example>
	<Example name="visually-hidden/icon-button" title="aria-label ou texto escondido">
		Num `IconButton`, o `aria-label` basta. Quando parte do nome aparece na tela, acrescente o resto como texto escondido: é texto de verdade, então a tradução do navegador também traduz.
	</Example>
	<Example name="visually-hidden/live-status" title="Anunciando uma mudança">
		Adicione ao carrinho. O número muda na tela, e um `role="status"` escondido, renderizado vazio desde o início, conta a quem usa leitor de tela o que aconteceu.
	</Example>
	<Example name="visually-hidden/skip-link" title="Link para pular">
		Clique na dica e aperte Tab. O `SkipLink` fica no topo da página e aparece por cima dela no foco: use-o para pular para o conteúdo principal.
	</Example>
	<Example name="visually-hidden/focusable" title="Aparece no foco">
		Clique na dica e aperte Tab. Com `focusable`, o link "Pular para os resultados" aparece no lugar enquanto tem foco, e o Enter pula os filtros. Sem ele, o texto continua escondido mesmo com foco.
	</Example>
	<Example name="visually-hidden/table-caption" title="Legenda de tabela">
		Quando o layout já deixa claro para que serve a tabela, uma `<caption>` escondida ainda dá nome a ela, e à área de rolagem no celular.
	</Example>
	<Example name="visually-hidden/hidden-label" title="Um rótulo que não aparece">
		Uma caixa de busca sozinha ao lado de um botão de busca pode esconder o rótulo. Ele ainda precisa ser um `<label>` de verdade; o placeholder some assim que a pessoa digita.
	</Example>
	<Example name="visually-hidden/symbols" title="Símbolos em palavras">
		"★ 4,8 (312)" não diz nada em voz alta. Esconda os símbolos com `aria-hidden` e dê ao leitor de tela a frase inteira.
	</Example>
</ExampleGrid>

## Em contexto [#em-contexto]

Texto escondido está em toda interface bem feita. São pedaços inteiros de interface para copiar, no estilo que você escolheu.

<ContextGrid>
	<Context name="visually-hidden/context-invoices" title="Tabela de faturas" uses="Card · Table · Link · IconButton · VisuallyHidden" />
	<Context name="visually-hidden/context-header" title="Cabeçalho de loja" uses="SkipLink · Button · Badge · VisuallyHidden" />
	<Context name="visually-hidden/context-pricing" title="Comparação de planos" uses="Table · VisuallyHidden" />
</ContextGrid>

## Boas práticas [#boas-práticas]

<Guidelines>
	<Guideline kind="do" name="visually-hidden/do-context-links" title="Complete a frase dos links repetidos.">
		Na tela, "Editar" está na linha certa. Numa lista de links, "Editar fatura nº 4821" continua fazendo sentido.
	</Guideline>
	<Guideline kind="dont" name="visually-hidden/dont-repeated-links" title="Três links chamados Editar.">
		Quem lista os links no leitor de tela ouve "Editar, Editar, Editar" e não sabe qual é qual.
	</Guideline>
	<Guideline kind="do" name="visually-hidden/do-visible-labels" title="Rótulos visíveis quando cabe.">
		Todo mundo ganha com um rótulo: pessoas com dificuldade de memória ou atenção, e quem confere o que digitou.
	</Guideline>
	<Guideline kind="dont" name="visually-hidden/dont-hidden-labels" title="Esconder rótulos para economizar espaço.">
		Com os campos preenchidos, nada na tela diz qual é qual.
	</Guideline>
</Guidelines>

## Props [#props]

<Props
	file="visually-hidden"
	type="VisuallyHiddenProps"
	include={["children", "focusable", "role", "style"]}
	types={{ children: "ReactNode", style: "CSSProperties" }}
	describe={{
		children: "O texto a ler. Mantenha um espaço no começo quando ele continua um texto visível, como em \"Editar\" + \" fatura nº 4821\".",
		focusable: "Mostra o conteúdo enquanto ele, ou algo dentro dele, tem foco, como um link \"Pular para os resultados\". Precisa da folha de estilo do Camaleo.",
		role: "Use `\"status\"` (educado) ou `\"alert\"` (urgente) para anunciar mudanças. Renderize vazio primeiro e depois coloque o texto.",
		style: "Aplicado depois dos estilos que escondem, então pode sobrescrevê-los. Não faça isso, a menos que queira mostrar o texto.",
	}}
>
	Todos os atributos de um `<span>` passam adiante, como `id` (para apontar um `aria-describedby` para ele) ou `aria-live`.
</Props>

## Styling hooks [#styling-hooks]

Não há o que estilizar: os estilos que escondem são inline, então nenhuma folha de estilo os desfaz sem querer. Com `focusable` eles vêm da folha de estilo, porque estilos inline não reagem ao foco.

<StylingHooks
	slots={["visually-hidden"]}
	attributes={[
		{ attr: "data-slot", value: '"visually-hidden"' },
		{ attr: "data-focusable", value: "com focusable; escondido enquanto nada dentro tem foco" },
	]}
/>

## Acessibilidade [#acessibilidade]

<KeyboardTable
	keys={[{ key: "Tab", description: "O VisuallyHidden não recebe foco. Um link ou botão dentro dele só cabe com focusable, que o mostra enquanto tem foco; sem isso, ele receberia foco sem aparecer." }]}
	notes={[
		"O texto continua na árvore de acessibilidade: ele entra no nome acessível do link ou botão em volta.",
		"Sem focusable ele continua escondido no foco. Para pular para o conteúdo principal use o SkipLink; para um link que aparece no lugar, como \"Pular para os resultados\", use focusable.",
		"Para mensagens ao vivo, o elemento com role=\"status\" precisa estar na página antes de o texto mudar, ou o leitor de tela não anuncia.",
		"Texto escondido é para o contexto que quem enxerga tira do layout. Se todo mundo precisa dele, mostre.",
	]}
/>

## Relacionados [#relacionados]

<RelatedComponents
	items={[
		{ title: "Button", description: "O IconButton precisa de nome: aria-label ou texto escondido.", href: "/pt-br/docs/components/button" },
		{ title: "Link", description: "Links que fazem sentido fora do contexto.", href: "/pt-br/docs/components/link" },
		{ title: "Toast", description: "Mensagens visíveis que também são anunciadas.", href: "/pt-br/docs/components/toast" },
	]}
/>


# Personalizador de tema (/pt-br/docs/customizer)

<Customizer />

## O que cada escolha define [#o-que-cada-escolha-define]

Cada escolha escreve tokens `--cml-*` e mais nada. Escolhas que você não tocou mantêm os valores do estilo e ficam fora do arquivo.

| Escolha | Tokens |
| --- | --- |
| Estilo base, modo, marca | `styleName`, `mode` e `brand` no `StyleProvider`; o `createBrand` transforma a marca em `--cml-brand-*` |
| Raio dos controles | `--cml-radius-control`, `-sm`, `-lg` e `--cml-radius-field`; a última posição é `var(--cml-radius-pill)` |
| Raio das superfícies | `--cml-radius-surface`, e `--cml-radius-popover` com 80% dele |
| Espessura da borda | `--cml-border-width`, `--cml-field-border-width` |
| Altura dos controles | `--cml-control-height`, `-sm`, `-lg`, `--cml-field-height`, `--cml-item-height`, todos movidos na mesma medida |
| Fontes | `--cml-font-body`, `--cml-font-display` |
| Sombras | `--cml-shadow-surface`, `--cml-shadow-popover`, `--cml-card-shadow` |
| Movimento desligado | `--cml-motion-distance: 0px`, `--cml-motion-scale: 1`, `--cml-press-translate: 0px`, os valores que a biblioteca usa para movimento reduzido |

## Sobrescrever ou estilo novo [#sobrescrever-ou-estilo-novo]

**Sobrescrever** escreve as suas mudanças em `[data-style="<estilo>"]`, fora de qualquer camada. Todo o CSS da biblioteca está nas camadas `cml.*`, então CSS sem camada vence sem `!important`, inclusive em tokens que o estilo nunca define. Continue importando o CSS do estilo e passando o nome dele.

**Estilo novo** escreve um estilo próprio em `@layer cml.style`, a camada dos 13 estilos: os valores de token do estilo base com as suas mudanças por cima. Ele copia só tokens; as regras com escopo do estilo base (chanfros, divisórias, o desfoque do glass) ficam com o nome do estilo base. Se você quer o visual exato do estilo base, exporte uma sobrescrita. A prévia sempre roda o arquivo que você vai exportar.

Os pares de contraste abaixo da prévia são medidos na prévia renderizada, do mesmo jeito que o teste de matriz da biblioteca os lê: texto e texto da marca a 4,5:1, o anel de foco e as bordas de controle a 3:1. Veja [Cor da marca](/pt-br/docs/guides/brand-color) para entender por que o texto sobre a marca sempre passa, e [Criar um estilo](/pt-br/docs/guides/create-a-skin) para levar um estilo novo adiante.


# Acessibilidade (/pt-br/docs/guides/accessibility)

<Learn>

- O que você ganha de todo componente sem trabalho extra
- Como a biblioteca é testada nos 13 estilos, em claro e escuro, com cinco cores de marca difíceis
- O contraste medido das cores de texto e de controle de cada estilo
- Onde a aparência autêntica e a acessibilidade discordam, e qual vence

</Learn>

A meta é WCAG 2.2 AA em todos os estilos, em claro e escuro, com qualquer cor de marca. Um estilo pode mudar forma, profundidade, tipografia e movimento; não pode tirar um nome, uma tecla ou um anel de foco.

## O que todo componente garante [#o-que-todo-componente-garante]

- **Teclado.** Cada componente segue um padrão do WAI-ARIA Authoring Practices e herda o modelo de teclado da primitiva por baixo (Base UI, ou React Aria nas datas). As setas andam dentro de um widget, o Tab passa de um widget a outro, o Esc fecha popups e devolve o foco ao gatilho.
- **Foco.** O foco é desenhado com `outline`, nunca só com `box-shadow`, então sobrevive às cores forçadas. A cor dele, `--cml-focus-ring`, é testada com 3:1 ou mais contra a superfície em todos os estilos.
- **Nomes.** Botões e regiões embutidos têm nome (fechar, limpar, mostrar senha, página 3…), que você traduz com o `MessagesProvider`. Controles só com ícone que você monta ainda precisam de `aria-label`.
- **Alvos.** Checkboxes, rádios, links da trilha e outros controles pequenos mantêm uma área de clique de pelo menos 24 × 24 px, mesmo nos estilos densos.
- **Movimento reduzido.** Reduz, não remove: com `prefers-reduced-motion`, distâncias e escalas vão a zero, fades curtos ficam, painéis abrem de uma vez, o brilho do skeleton para e uma barra de progresso indeterminada pulsa no lugar.
- **Cores forçadas.** Os componentes reservam uma borda transparente que aparece no alto contraste do Windows, e os estados selecionados passam para cores do sistema (`Highlight`, `CanvasText`).
- **Transparência reduzida.** `glass` e `cupertino` trocam as superfícies translúcidas por opacas com `prefers-reduced-transparency: reduce` e em navegadores sem `backdrop-filter`.
- **Direita para a esquerda.** Os componentes invertem com o `DirectionProvider`; veja [Idiomas e RTL](/pt-br/docs/guides/i18n#da-direita-para-a-esquerda).

## Como é testado [#como-é-testado]

Os testes ficam em `packages/react/test` e rodam num navegador de verdade (Vitest em modo navegador com Playwright).

- **A matriz** (`matrix.test.tsx`) renderiza uma vitrine com todos os componentes em 13 estilos × claro e escuro × 5 cores de marca difíceis (`#2563eb`, `#facc15`, `#22d3ee`, `#ff7f50` e `#808080`): 130 escopos. Em cada um, roda o axe com as regras A/AA da WCAG 2.0, 2.1 e 2.2, confere que o anel de foco e a borda dos controles chegam a 3:1, que os tons de perigo, sucesso, aviso e informação chegam a 4,5:1, e depois abre 17 popups (diálogo, menu, select, seletor de data, toast…), um por vez, para conferir que cada um mantém o estilo pelo portal e também passa no axe. São 2.340 execuções.
- **Texto sobre imagem.** O axe não mede texto sobre gradiente e vidro e marca o caso como "incompleto". A matriz mede esses nós em pixels reais (`pixel-contrast.ts`): duas capturas, com e sem o texto, e o pior pixel das letras contra o fundo logo atrás.
- **Teclado** (`keyboard.test.tsx`): 30 testes que usam os componentes com teclas de verdade, do Espaço num checkbox ao PageUp num calendário.
- **As docs.** Cada página deste site, com os exemplos ao vivo, passa pelo axe em 4 estilos, claro e escuro, em larguras de desktop, tablet e celular, nos dois idiomas.

## Relatório de contraste [#relatório-de-contraste]

A tabela abaixo é medida, não digitada: o `apps/docs/scripts/contrast-report.mjs` carrega o `tokens.css` e o CSS de cada estilo num navegador, resolve os tokens com cada uma das cinco cores de marca da matriz e guarda a **menor** razão das cinco. Os números são arredondados para baixo, então 4,499 aparece como 4,49.

O que ele mede, sempre contra a cor da página do estilo, `--cml-surface`, salvo indicação:

- **Texto, 4,5:1 ou mais:** `--cml-fg` (texto corrido), `--cml-fg-secondary`, `--cml-fg-muted`, `--cml-accent-text` (texto e links na cor da marca), `--cml-accent-fg` sobre `--cml-accent` (texto num botão sólido da marca) e os tons `--cml-danger`, `--cml-success` e `--cml-warning`.
- **Não texto, 3:1 ou mais:** `--cml-border-control` (a borda de campos e opções) e `--cml-focus-ring`.

Ele não mede texto sobre superfícies elevadas, estados de hover nem painéis de vidro sobre o fundo; a matriz cobre esses casos nos componentes renderizados.

<ContrastTable
  label="Texto sobre a cor da página, meta 4,5:1"
  ids={["fg", "fgSecondary", "fgMuted", "accentText", "danger", "success", "warning"]}
/>

<ContrastTable
  label="Preenchimento da marca (meta 4,5:1) e bordas (meta 3:1)"
  ids={["accentFg", "borderControl", "focusRing"]}
/>

Todos os pares atingem a meta em todos os estilos e modos. Rode `node scripts/contrast-report.mjs` em `apps/docs` depois de mudar um estilo para atualizar os números.

## Autêntico ou acessível [#autêntico-ou-acessível]

Alguns estilos falham no contraste por natureza: o neumorphism não tem bordas, o vidro põe texto sobre o que estiver atrás, um sistema operacional clássico desenha um retângulo de foco pontilhado de 1 px. O projeto decidiu (decisão 9 do plano) que **todo estilo é acessível por padrão**, e que uma variante autêntica seria opcional e marcada como "não garante AA". Nenhuma variante autêntica existe ainda.

| Estilo | A aparência autêntica | O que o Camaleo faz por padrão |
| --- | --- | --- |
| `neumorphism` | Controles moldados só por luz e sombra, sem bordas | Borda de 1 px com 3:1 ou mais em campos e opções; os botões têm o nome no texto |
| `glass` | Painéis translúcidos sobre qualquer fundo | Manchas do fundo claras (no escuro, escuras) o bastante para o texto manter 4,8:1 no pico; opaco com transparência reduzida |
| `clay` | Peças pastel macias, sem contorno | Campos e opções mantêm uma borda de 3:1 ou mais |
| `cupertino` | Cromo fosco em menus e popups | Vidro escuro a 94% de opacidade para o texto manter 4,5:1; alternativa opaca |
| `y2k` | Botões "jelly" brilhantes com texto sobre o brilho | O texto fica só sobre o destaque liso; o brilho fica acima e abaixo dele |
| `retro` | Retângulo de foco pontilhado | Mantido dentro de botões, abas e toggles (na cor do rótulo); os campos ganham um anel sólido de 2 px fora do bisel |

<Callout kind="caution">

Um token ou regra que você muda pode quebrar o que os testes garantem. Depois de qualquer mudança de cor, rode a matriz de novo (`pnpm --filter @camaleo/react test`) ou pelo menos este relatório.

</Callout>

<Checklist>

- Botões só com ícone que você acrescenta têm `aria-label`
- Cores próprias vêm de tokens, então mantêm os pares testados
- Animações que você acrescenta respeitam `prefers-reduced-motion`
- Popups novos mantêm o estilo (use `PortalScope` nos seus portais)
- O relatório de contraste e a matriz continuam passando depois de mudar um estilo

</Checklist>


# Cor da marca (/pt-br/docs/guides/brand-color)

<Learn>

- Como o `createBrand` transforma uma cor em 34 tokens
- Por que o texto sobre a marca é sempre legível, seja qual for a cor
- Como a mesma cor aparece em estilos diferentes, e quais cores são as mais difíceis

</Learn>

## Uma prop [#uma-prop]

Defina `brand` num `StyleProvider` com qualquer cor CSS: hex, `rgb()`, `oklch()`, uma cor com nome. Se você omitir, ela é herdada do provider pai; no topo, o padrão é o azul `#2563eb`.

<FileCode file="app/providers.tsx" code={`
  <StyleProvider styleName="minimal" brand="#3fa34d">
    <App />
  </StyleProvider>
`} />

A barra de marca no topo deste site faz o mesmo para todas as prévias da página. Escolha uma cor lá e volte aqui.

## A escala de 11 passos [#a-escala-de-11-passos]

O `createBrand` (de `@camaleo/styles`) converte a cor para OKLCH, mantém o matiz e monta os passos de 50 a 950 com luminosidade fixa, de 0,97 até 0,24. Os passos claros usam uma parte pequena do croma da cor, os do meio usam tudo; o que fica fora do sRGB é trazido de volta para dentro. Teste uma cor:

<Preview name="guide-brand/scale" />

Cada passo vira três tokens, mais o `--cml-brand` com a cor que você passou:

| Token | O que é |
| --- | --- |
| `--cml-brand-600` | A cor do passo |
| `--cml-brand-600-fg` | Preto ou branco, o que for mais legível sobre ela |
| `--cml-brand-600-hover` | O passo deslocado 0,09 em luminosidade, para longe da cor do texto |

Você pode chamá-lo por conta própria, por exemplo para gravar os tokens num arquivo CSS estático durante o build:

<FileCode file="scripts/brand.ts" code={`
  import { createBrand } from "@camaleo/styles";

  const vars = createBrand("#3fa34d");
  // { "--cml-brand": "#3fa34d", "--cml-brand-50": "#…", "--cml-brand-50-fg": "#000000", … }
  const css = \`:root { \${Object.entries(vars).map(([k, v]) => \`\${k}: \${v};\`).join(" ")} }\`;
`} />

<Callout kind="caution">

O `createBrand` lança um erro quando não consegue interpretar o texto. Se a cor vem das pessoas que usam o app, valide antes (ou capture o erro e volte para um padrão).

</Callout>

## Como o contraste é garantido [#como-o-contraste-é-garantido]

O texto sobre um passo nunca é "a cor de texto da marca": é preto ou branco, escolhido passo a passo pelo contraste WCAG. Contra qualquer cor, o melhor entre preto e branco chega a pelo menos **4,58:1**, então todo `-fg` passa de 4,5:1, seja qual for a entrada. As cores de hover se afastam dessa cor de texto, então o hover nunca reduz o contraste.

Os estilos não usam a escala crua; eles a mapeiam para tokens semânticos e escolhem os passos que funcionam nas superfícies deles:

| Estilo | `--cml-accent` (claro / escuro) |
| --- | --- |
| minimal, e os estilos que mantêm o padrão | 600 / 400 |
| cupertino | 600 nos dois modos |
| neubrutalism | 500 nos dois modos |
| material | 600 / 300 |
| progressive, y2k | 600 / 500 |
| retro | 800 / 600 |
| editorial | a cor da tinta; a marca indica foco e seleção |

O texto da marca na página (links, o anel de foco, informações) usa `--cml-accent-text`, que é 700 no modo claro e 300 no escuro no estilo padrão. O teste de matriz confere que ele fica em 4,5:1 sobre a superfície, e que o anel de foco e as bordas dos controles ficam em 3:1.

## A mesma cor em 3 estilos [#a-mesma-cor-em-3-estilos]

Uma marca, três estilos: cada um escolhe o próprio passo, então um amarelo que é preenchimento num estilo pode virar um dourado escuro em outro. Troque também o modo na barra "visualizar em".

<Preview name="guide-brand/three-skins" />

## Cores difíceis [#cores-difíceis]

A maioria das cores é fácil. Estas cinco são as que quebram paletas ingênuas, e o teste de matriz roda cada estilo, no claro e no escuro, com cada uma delas:

| Cor | Por que é difícil |
| --- | --- |
| Azul `#2563eb` | A padrão: texto preto até o passo 500, branco a partir do 600 (5,3:1) |
| Amarelo `#facc15` | Matiz muito claro: o passo 600 é um dourado escuro (`#866c00`) e texto amarelo sobre branco não passaria |
| Ciano `#22d3ee` | Claro e saturado: branco sobre o passo 600 dá 4,86:1, o mais perto do mínimo entre os cinco |
| Coral `#ff7f50` | Preto e branco ficam quase iguais por volta dos passos 500 e 600 (5,35 e 5,46:1) |
| Cinza `#808080` | Nenhum croma, então a escala é só de cinzas |

<Callout>

Se a sua marca é uma cor clara como o amarelo, espere que os estilos que usam o passo 500 ou 600 como preenchimento a mostrem mais escura que o seu logo. É o preço do texto legível; use a cor exata em ilustrações e no marketing, não nos controles.

</Callout>

<Checklist>

- A marca é definida uma vez, no provider do topo (ou no `<html>` com `styleScopeProps`)
- Cores que vêm das pessoas são validadas antes de chegar ao `createBrand`
- Você muda o `--cml-accent`, não um passo da marca, quando quer outro tom
- Você conferiu a sua cor no claro e no escuro, em cada estilo que publica

</Checklist>


# Criar um estilo (/pt-br/docs/guides/create-a-skin)

<Learn>

- Quais tokens fazem uma aparência, e quais você pode deixar no padrão
- Como escrever o arquivo: `@layer cml.style`, `light-dark()`, `@scope … to ([data-style])`
- Como testar o contraste do jeito que a biblioteca testa os próprios 13 estilos

</Learn>

## Veja um sendo construído [#veja-um-sendo-construído]

Este é o "sunset", o estilo escrito nesta página. Cada passo acrescenta algo ao arquivo; a demo roda o resultado com a marca e o modo da barra "visualizar em".

<CodeSwitch
  name="guide-tokens/invite"
  label="Passo da construção"
  cumulative
  options={[
    { kicker: "Início", title: "Padrões", note: "um nome ainda sem tokens fica igualzinho ao minimal.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
        }
      }` },
    { kicker: "Passo 1", title: "Tipografia e cor", note: "fontes, superfícies, texto e bordas, cada um com um valor claro e um escuro.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
          --cml-font-body: "Fraunces", Georgia, serif;
          --cml-surface: light-dark(#fff7ef, #1c1410);
          --cml-surface-raised: light-dark(#fffdf9, #261b15);
          --cml-fg: light-dark(#2b1a14, #f6e9df);
          --cml-fg-secondary: light-dark(#5a4034, #d9c4b6);
          --cml-fg-muted: light-dark(#7a5a4a, #b39a8a);
          --cml-border: var(--cml-fg);
          --cml-border-control: light-dark(#8a6a58, #9a7f6e);
          --cml-accent: light-dark(var(--cml-brand-700), var(--cml-brand-300));
          --cml-accent-fg: light-dark(var(--cml-brand-700-fg), var(--cml-brand-300-fg));
          --cml-accent-hover: light-dark(var(--cml-brand-700-hover), var(--cml-brand-300-hover));
        }
      }` },
    { kicker: "Passo 2", title: "Forma e profundidade", note: "bordas mais grossas, controles redondos e uma sombra deslocada e dura, somados ao passo 1.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
          /* …passo 1, depois: */
          --cml-border-width: 2px;
          --cml-radius-control: 20px;
          --cml-radius-field: 12px;
          --cml-radius-surface: 24px;
          --cml-card-shadow: 6px 6px 0 var(--cml-border);
          --cml-shadow-popover: 4px 4px 0 var(--cml-border);
        }
      }` },
    { kicker: "Passo 3", title: "Uma regra com escopo", note: "estrutura que um token não expressa, limitada a este estilo e interrompida nas ilhas aninhadas.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        /* …passos 1 e 2, depois: */
        @scope ([data-style="sunset"]) to ([data-style]) {
          [data-slot="card-header"] {
            border-bottom: var(--cml-border-width) solid var(--cml-border);
          }
        }
      }` },
  ]}
/>

<Steps>

## Dê um nome e abra a camada [#dê-um-nome-e-abra-a-camada]

Escolha um nome em minúsculas e escreva tudo dentro de `@layer cml.style`, a camada que os 13 estilos usam. Isso põe o seu estilo acima dos padrões e das regras dos componentes, e deixa o CSS sem camada do seu app livre para sobrescrevê-lo.

<FileCode file="sunset.css" code={`
  @layer cml.style {
    [data-style="sunset"] {
      /* os tokens vão aqui */
    }
  }
`} />

## Defina os tokens que fazem a aparência [#defina-os-tokens-que-fazem-a-aparência]

Nenhum token é obrigatório: o que você deixar de fora mantém o padrão do `minimal`. Na prática, uma aparência vem destes grupos, mais ou menos nesta ordem de impacto:

| Grupo | Tokens para começar |
| --- | --- |
| Tipografia | `--cml-font-body`, e `--cml-font-display` / `--cml-font-control` se forem diferentes |
| Superfícies e texto | `--cml-surface`, `--cml-surface-raised`, `--cml-fg`, `--cml-fg-secondary`, `--cml-fg-muted` |
| Linhas | `--cml-border`, `--cml-border-control`, `--cml-border-width` |
| Acento | `--cml-accent`, `--cml-accent-fg`, `--cml-accent-hover`: quais passos da marca você usa |
| Forma | `--cml-radius-control`, `--cml-radius-field`, `--cml-radius-surface` |
| Profundidade | `--cml-shadow-control`, `--cml-shadow-surface`, `--cml-shadow-popover`, `--cml-card-shadow` |
| Densidade | `--cml-control-height`, `--cml-field-height`, `--cml-surface-padding` |

Escreva toda cor como `light-dark(light, dark)`, para que uma declaração cubra os dois modos. No acento, escolha **passos** da marca, nunca uma cor fixa, e sempre junte um passo ao `-fg` e ao `-hover` dele: é isso que mantém o texto legível com qualquer marca. A página [Tokens](/pt-br/docs/guides/tokens) lista todos, com os padrões.

<Callout>

Precisa de um preenchimento que não é superfície nem acento? Declare um token seu ao lado dos outros (o neubrutalism tem `--cml-ink` e `--cml-highlight`) e use-o nas suas regras com escopo.

</Callout>

## Acrescente regras com escopo, se precisar [#acrescente-regras-com-escopo-se-precisar]

Algumas aparências pedem uma estrutura que um token não expressa: um divisor, um chanfro, outro hover. Ponha essas regras num `@scope` com o seu estilo como raiz e `to ([data-style])` como limite, para que nunca cheguem a uma ilha aninhada em outro estilo.

<FileCode file="sunset.css" code={`
  @layer cml.style {
    @scope ([data-style="sunset"]) to ([data-style]) {
      [data-slot="card-header"] {
        border-bottom: var(--cml-border-width) solid var(--cml-border);
      }
    }
  }
`} />

<Callout kind="caution">

Cada regra que você acrescenta é uma regra que você precisa conferir nos dois modos, com movimento reduzido e com cores forçadas. Prefira um token de componente (eles estão listados em **Styling hooks** em cada página de componente) a uma regra.

</Callout>

## Use o estilo [#use-o-estilo]

Importe o arquivo depois do `base.css` e passe o nome. O `styleName` aceita qualquer nome que o seu CSS use, então o TypeScript aceita sem cast:

<FileCode file="app/providers.tsx" code={`
  import "@camaleo/styles/base.css";
  import "./sunset.css";
  import { StyleProvider } from "@camaleo/react";

  <StyleProvider styleName="sunset" mode="system">
    <App />
  </StyleProvider>
`} />

## Teste o contraste [#teste-o-contraste]

A biblioteca passa cada estilo × claro e escuro × cinco cores de marca difíceis (azul, amarelo, ciano, coral, cinza) pelo axe e por um conjunto de checagens de contraste. Faça o mesmo com o seu. As checagens leem os tokens computados, então precisam de um navegador de verdade (modo browser do Vitest ou Playwright):

<FileCode file="sunset.test.tsx" code={`
  import "@camaleo/styles/base.css";
  import "./sunset.css";
  import { StyleProvider } from "@camaleo/react";
  import { wcagContrast } from "culori";
  import { expect, it } from "vitest";
  import { render } from "vitest-browser-react";
  import { Screens } from "./screens";

  // Resolve um token para uma cor deixando o navegador computá-la.
  function token(scope: Element, name: string) {
    const probe = document.createElement("span");
    probe.style.color = \`var(\${name})\`;
    scope.append(probe);
    const color = getComputedStyle(probe).color;
    probe.remove();
    return color;
  }

  for (const mode of ["light", "dark"] as const)
    for (const brand of ["#2563eb", "#facc15", "#22d3ee", "#ff7f50", "#808080"])
      it(\`sunset / \${mode} / \${brand}\`, async () => {
        // As suas telas, no estilo, modo e marca testados.
        const screen = await render(
          <StyleProvider styleName="sunset" mode={mode} brand={brand}>
            <Screens />
          </StyleProvider>,
        );
        const root = screen.container.firstElementChild as Element;
        const surface = token(root, "--cml-surface");
        expect(wcagContrast(token(root, "--cml-fg-muted"), surface)).toBeGreaterThanOrEqual(4.5);
        expect(wcagContrast(token(root, "--cml-border-control"), surface)).toBeGreaterThanOrEqual(3);
        expect(wcagContrast(token(root, "--cml-focus-ring"), surface)).toBeGreaterThanOrEqual(3);
      });
`} />

Confira também `--cml-danger`, `--cml-success`, `--cml-warning` e `--cml-info` contra a sua superfície (4,5:1): os padrões deles foram ajustados para branco e quase preto, e uma superfície tingida pode jogá-los para baixo do limite. As superfícies quentes do sunset mantêm todos acima de 4,7:1.

</Steps>

## O arquivo completo [#o-arquivo-completo]

O estilo inteiro desta página, pronto para copiar:

<FileCode file="sunset.css" code={`
  /* Sunset: papel quente, contornos de tinta, controles redondos e uma sombra deslocada e dura. */
  @layer cml.style {
    [data-style="sunset"] {
      --cml-font-body: "Fraunces", Georgia, serif;

      --cml-surface: light-dark(#fff7ef, #1c1410);
      --cml-surface-raised: light-dark(#fffdf9, #261b15);
      --cml-fg: light-dark(#2b1a14, #f6e9df);
      --cml-fg-secondary: light-dark(#5a4034, #d9c4b6);
      --cml-fg-muted: light-dark(#7a5a4a, #b39a8a);
      --cml-border: var(--cml-fg);
      --cml-border-control: light-dark(#8a6a58, #9a7f6e);
      --cml-accent: light-dark(var(--cml-brand-700), var(--cml-brand-300));
      --cml-accent-fg: light-dark(var(--cml-brand-700-fg), var(--cml-brand-300-fg));
      --cml-accent-hover: light-dark(var(--cml-brand-700-hover), var(--cml-brand-300-hover));

      --cml-border-width: 2px;
      --cml-radius-control: 20px;
      --cml-radius-field: 12px;
      --cml-radius-surface: 24px;
      --cml-card-shadow: 6px 6px 0 var(--cml-border);
      --cml-shadow-popover: 4px 4px 0 var(--cml-border);
    }

    @scope ([data-style="sunset"]) to ([data-style]) {
      [data-slot="card-header"] {
        border-bottom: var(--cml-border-width) solid var(--cml-border);
      }
    }
  }
`} />

<Checklist>

- Texto com pelo menos 4,5:1, e bordas de controle e anel de foco com pelo menos 3:1, no modo claro e no escuro
- As cinco cores de marca difíceis testadas nos dois modos
- O anel de foco visível em toda superfície que você acrescentou
- Regras com escopo conferidas com movimento reduzido e cores forçadas
- As fontes carregadas em todo lugar onde o estilo é usado

</Checklist>


# Modo escuro (/pt-br/docs/guides/dark-mode)

<Learn>

- O que `mode="light" | "dark" | "system"` faz, e o que herda esse valor
- Por que não há piscada na primeira pintura, e como manter assim com uma escolha salva
- Como colorir a interface do navegador com `theme-color`

</Learn>

## Experimente [#experimente]

Esta ilha define `mode` no próprio `StyleProvider`, independente do que diz a barra "visualizar em". Escolha **Sistema** e mude a configuração do seu sistema operacional: ela acompanha sem recarregar.

<Preview name="guide-dark/modes" />

## Como funciona [#como-funciona]

Todo token de cor é escrito com `light-dark()`: um valor para cada modo numa única declaração. O navegador escolhe o lado pelo `color-scheme`, e o `data-mode` define esse valor:

<FileCode file="tokens.css (trecho)" lang="css" code={`
  :root { color-scheme: light dark; }
  [data-mode="light"] { color-scheme: light; }
  [data-mode="dark"] { color-scheme: dark; }
  [data-mode="system"] { color-scheme: light dark; }

  :where(:root, [data-style]) {
    --cml-surface: light-dark(#ffffff, #09090b);
    --cml-fg: light-dark(#09090b, #fafafa);
  }
`} />

`color-scheme: light dark` quer dizer "siga o `prefers-color-scheme`". O `color-scheme` é herdado, então um provider sem `mode` simplesmente pega o do pai, e a raiz da página segue o sistema sem script nenhum. As partes nativas (barras de rolagem, seletores de data, preenchimento automático) acompanham também.

| `mode` | `data-mode` | Resultado |
| --- | --- | --- |
| omitido | nenhum | Herda do pai; na raiz, segue o sistema |
| `"system"` | `system` | Segue o sistema, mesmo dentro de um pai claro ou escuro |
| `"light"` | `light` | Sempre claro |
| `"dark"` | `dark` | Sempre escuro |

<Callout>

Diálogos, menus e toasts renderizam num portal. Eles levam o modo do provider pelo contexto do React, então um popup aberto a partir de uma ilha escura também é escuro.

</Callout>

<Steps>

## Escolha um padrão [#escolha-um-padrão]

Na maioria dos apps, omita o `mode` ou use `"system"` no provider do topo: a página acompanha o sistema operacional desde o primeiro byte. Use um modo fixo em áreas que precisam ficar sempre iguais, como um painel de código escuro ou uma prévia de impressão clara.

<FileCode file="app/providers.tsx" code={`
  <StyleProvider styleName="minimal" mode="system">
    <App />
    <StyleProvider styleName="minimal" mode="dark">
      <CodePanel />
    </StyleProvider>
  </StyleProvider>
`} />

## Salve a escolha de quem visita sem piscar [#salve-a-escolha-de-quem-visita-sem-piscar]

Um botão que guarda a escolha no `localStorage` e a aplica depois da hidratação pinta o modo errado primeiro. Em vez disso, renderize o modo salvo no servidor: guarde-o num cookie e espalhe no `<html>` com `styleScopeProps`, que é seguro de chamar num Server Component.

<FileCode file="app/layout.tsx" code={`
  import { cookies } from "next/headers";
  import { styleScopeProps } from "@camaleo/react/style-scope";

  export default async function RootLayout({ children }: { children: React.ReactNode }) {
    const saved = (await cookies()).get("mode")?.value;
    const mode = saved === "light" || saved === "dark" ? saved : "system";
    return (
      <html lang="pt-BR" {...styleScopeProps({ styleName: "minimal", mode })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

O botão grava o cookie e o atributo; nada precisa renderizar de novo:

<FileCode file="mode-toggle.tsx" code={`
  "use client";

  export function setMode(mode: "light" | "dark" | "system") {
    document.cookie = \`mode=\${mode}; path=/; max-age=31536000; samesite=lax\`;
    document.documentElement.setAttribute("data-mode", mode);
  }
`} />

<Callout kind="caution">

Não dê `mode` aos providers internos se a raiz cuida disso: um `mode` fixo num provider aninhado vence o botão. E ler `cookies()` faz a rota renderizar a cada requisição.

</Callout>

Num site estático ou numa SPA sem servidor, a única opção sem piscada é um pequeno script inline no `<head>` que roda antes da primeira pintura:

<FileCode file="index.html" lang="html" code={`
  <script>
    try {
      document.documentElement.setAttribute("data-mode", localStorage.getItem("mode") || "system");
    } catch {}
  </script>
`} />

## Pinte a interface do navegador [#pinte-a-interface-do-navegador]

O `theme-color` tinge a barra de endereço e a tela de apps recentes nos navegadores de celular. Dê a ele um valor por esquema, usando a cor de superfície do seu estilo. No Next, exporte-o do layout raiz:

<FileCode file="app/layout.tsx" code={`
  import type { Viewport } from "next";

  export const viewport: Viewport = {
    themeColor: [
      { media: "(prefers-color-scheme: light)", color: "#ffffff" },
      { media: "(prefers-color-scheme: dark)", color: "#09090b" },
    ],
  };
`} />

As media queries seguem o sistema. Se quem visita pode forçar um modo, o botão também deve trocar o `content` das duas tags `theme-color` para a cor do modo forçado.

</Steps>

<Checklist>

- O provider do topo usa `"system"` ou nenhum `mode`
- Uma escolha salva é renderizada pelo servidor, ou aplicada por um script inline antes da pintura
- Só as áreas que precisam ficar sempre iguais têm um `mode` fixo
- O `theme-color` bate com a superfície do estilo nos dois modos

</Checklist>


# Perguntas frequentes (/pt-br/docs/guides/faq)

<Learn>

- Quanto custa: JavaScript, CSS e fontes
- Onde roda: renderização no servidor, Tailwind, estilos misturados e navegadores
- A licença, as marcas registradas e como relatar um bug

</Learn>

## Tem tree shaking? Qual é o tamanho? [#tem-tree-shaking-qual-é-o-tamanho]

O JavaScript tem. O `@camaleo/react` é só ESM, marcado com `"sideEffects": false` e gerado com um arquivo por componente, então o bundler mantém só o que você importa. Cada componente também tem a própria entrada (`@camaleo/react/button`), se você preferir imports explícitos.

O CSS é dividido por estilo, não por componente. O `base.css` traz os tokens e a estrutura de todos os componentes: cerca de 28 kB com gzip, antes de minificar. Cada estilo soma um arquivo, de cerca de 3 kB (`neumorphism`, `retro-pixel`) a 11 kB (`material`) com gzip. Estilos que você não importa não custam nada.

## Quais estilos precisam de fontes da web? [#quais-estilos-precisam-de-fontes-da-web]

Nenhum traz fontes junto, e toda pilha de fontes termina numa fonte do sistema, então nada quebra sem elas. Para ficar como foi desenhado, carregue as famílias de cada estilo: a tabela de fontes por estilo, e como carregá-las com o `next/font`, está em [Estilos e troca](/pt-br/docs/guides/skins#carregue-as-fontes).

## Funciona com Server Components e SSR? [#funciona-com-server-components-e-ssr]

Sim. As peças de layout e de exibição são Server Components, o estilo é definido no `<html>` por uma função comum e o modo escuro não precisa de script. Veja [Server Components e SSR](/pt-br/docs/guides/ssr).

## Posso misturar estilos na mesma página? [#posso-misturar-estilos-na-mesma-página]

Sim, é para isso que serve o `StyleProvider`. Cada provider renderiza um `<div data-style>` e vira uma ilha: parte do padrão em vez de herdar a aparência do pai, e os popups dele mantêm o estilo. Importe o CSS de cada estilo usado. A cor da marca passa para as ilhas aninhadas, a menos que elas definam a própria.

<FileCode file="app/page.tsx" code={`
  <StyleProvider styleName="editorial">
    <Article />
    <StyleProvider styleName="retro">
      <Guestbook />
    </StyleProvider>
  </StyleProvider>
`} />

## Preciso do Tailwind? [#preciso-do-tailwind]

Não. Os estilos são CSS puro em camadas de cascata e funcionam em qualquer app React. Se você já usa o Tailwind CSS v4, veja [Tailwind CSS](/pt-br/docs/guides/tailwind) para a ordem das camadas e o mapeamento dos tokens.

## Quais navegadores são suportados? [#quais-navegadores-são-suportados]

O CSS usa alguns recursos recentes. Estas são as versões em que cada um chegou:

| Recurso | Usado em | Chrome / Edge | Safari | Firefox |
| --- | --- | --- | --- | --- |
| `light-dark()` | Todas as cores, nos dois modos | 123 | 17.5 | 120 |
| `@scope` | Regras estruturais de cada estilo | 118 | 17.4 | 146 |
| Cores relativas (`oklch(from …)`) | Fundo do glass tingido pela marca | 119 | 18 | 128 |
| `@property` | Valores de `Stack` e `Grid` que não herdam | 85 | 16.4 | 128 |
| `corner-shape` | Cantos squircle no `cupertino` | 139 | — | — |
| `backdrop-filter` | Vidro no `glass` e no `cupertino` | 76 | 18 | 103 |

O `light-dark()` é o piso: sem ele, as cores não resolvem. Sem `@scope`, um estilo mantém os tokens mas perde as regras estruturais e parece aplicado pela metade. `corner-shape` e `backdrop-filter` degradam sozinhos: os cantos ficam redondos, e o vidro fica opaco por uma alternativa em `@supports`.

## Posso usar num projeto comercial? [#posso-usar-num-projeto-comercial]

Sim. O Camaleo é open source sob a licença MIT: use, altere e publique, mantendo o aviso de copyright.

## Tem ligação com o Google ou a Apple? [#tem-ligação-com-o-google-ou-a-apple]

Não. O `material` é inspirado no Material Design e o `cupertino`, nas Human Interface Guidelines da Apple. O Camaleo não tem ligação nem endosso do Google ou da Apple, e não usa fontes, ícones ou marcas deles (o `cupertino` usa Inter, não SF Pro).

## Como relato um bug? [#como-relato-um-bug]

Abra uma issue no [GitHub](https://github.com/GuilhermeDeitos/camaleo/issues). Ajuda muito incluir:

- o componente, o estilo, o modo (claro ou escuro) e a cor da marca;
- o navegador e a versão, e as versões do React e do Next.js se importarem;
- o menor código que mostra o problema, ou o exemplo das docs que já mostra;
- em bugs de acessibilidade, a tecnologia assistiva (leitor de tela, zoom, alto contraste) e o que você esperava ouvir ou ver.


# Formulários (/pt-br/docs/guides/forms)

<Learn>

- O que o `Field` liga para você, e o que fica com a sua marcação
- Dois jeitos de validar: no campo, ou com o seu próprio estado
- Quando usar um `ErrorSummary`, e para onde vai o foco depois de um envio com erro
- Como ligar react-hook-form e zod sem perder nada disso

</Learn>

<Steps>

## Ligue um campo [#ligue-um-campo]

O `Field` liga um rótulo, uma descrição e um erro ao controle que está dentro dele. O `FieldLabel` vira um `<label>` do controle, e `FieldDescription` e `FieldError` são ligados por `aria-describedby`, então o leitor de tela lê a dica e o erro quando o controle recebe foco.

<FileCode file="cadastro.tsx" code={`
  import { Field, FieldDescription, FieldError, FieldLabel, Input } from "@camaleo/react";

  <Field validationMode="onBlur">
    <FieldLabel>E-mail de trabalho</FieldLabel>
    <Input type="email" autoComplete="email" required />
    <FieldDescription>Respondemos em até um dia útil.</FieldDescription>
    <FieldError match="valueMissing">Informe seu e-mail de trabalho.</FieldError>
  </Field>
`} />

`Input`, `Textarea`, `NativeSelect`, `Select`, `Combobox`, `NumberField`, `Checkbox`, `Switch`, `Slider` e os campos de data entram no `Field` em que estão. Agrupe campos relacionados com `Fieldset` e `FieldsetLegend`. Para um checkbox ou switch sozinho, um `Label` em volta basta.

## Valide no campo [#valide-no-campo]

O `Field` roda as verificações do navegador (`required`, `type="email"`, `minLength`…) e a sua função `validate`. O `FieldError` mostra a mensagem; `match` escolhe qual falha ele informa, e o resultado do `validate` aparece como está.

O `validationMode` define quando a verificação acontece. O padrão do Base UI, `"onSubmit"`, foi feito para o componente `Form` dele, que o Camaleo não embrulha, então defina `"onBlur"` ou `"onChange"` no `Field`, ou deixe uma biblioteca de formulário decidir (abaixo).

<Preview name="field/validate" compact />

<FileCode file="usuario.tsx" code={`
  <Field
    validationMode="onChange"
    validate={(value) => (String(value ?? "").length < 3 ? "Use pelo menos 3 caracteres." : null)}
  >
    <FieldLabel>Nome de usuário</FieldLabel>
    <Input autoComplete="username" />
    <FieldError />
  </Field>
`} />

Quando o resultado vem de outro lugar (um servidor, uma biblioteca de formulário), defina `invalid` no `Field` e passe o mesmo valor para o `match` do `FieldError`, que então mostra o conteúdo dele como está. É assim que a receita abaixo funciona.

<Callout kind="tip">

Escreva erros que dizem como resolver: "Informe um e-mail como ana@empresa.com.br", não "Entrada inválida". Cada página de componente tem um par de faz/não faz sobre isso.

</Callout>

## Resuma os erros [#resuma-os-erros]

Quando o formulário tem mais que poucos campos, um envio com erro deve cair num `ErrorSummary` no topo: um alerta de perigo cujo título diz quantos campos precisam de correção, com um link por erro. Cada link leva o foco ao controle.

<FileCode file="checkout.tsx" code={`
  const summary = useRef<HTMLDivElement>(null);

  // Depois de um envio com erro, foque o resumo para ele ser lido primeiro.
  useEffect(() => {
    if (failedAttempts > 0) summary.current?.focus();
  }, [failedAttempts]);

  {errors.length > 0 && (
    <ErrorSummary
      ref={summary}
      tabIndex={-1}
      title={\`Corrija \${errors.length} campos para continuar.\`}
      errors={errors.map((e) => ({ target: e.id, message: e.message }))}
    />
  )}
`} />

O `target` é o `id` do controle. Gere cada id com `useId()`, para duas cópias do formulário na mesma página nunca colidirem.

## Use react-hook-form e zod [#use-react-hook-form-e-zod]

O react-hook-form guarda os valores e roda o schema; o Camaleo mostra o resultado. Envolva cada controle num `Controller`, passe `fieldState.invalid` para o `Field` e espalhe `field` no controle:

<FileCode file="pedir-demo.tsx" code={`
  const { control, handleSubmit } = useForm<Values>({
    resolver: zodResolver(schema),
    defaultValues: { email: "" },
    // O ErrorSummary recebe o foco, não o primeiro campo inválido.
    shouldFocusError: false,
  });

  <Controller
    name="email"
    control={control}
    render={({ field, fieldState }) => (
      <Field invalid={fieldState.invalid}>
        <FieldLabel>E-mail de trabalho</FieldLabel>
        <Input {...field} id={ids.email} type="email" autoComplete="email" />
        <FieldError match={fieldState.invalid}>{fieldState.error?.message}</FieldError>
      </Field>
    )}
  />
`} />

<Callout kind="caution">

Use `shouldFocusError: false` quando o formulário tiver um `ErrorSummary`. Senão o react-hook-form leva o foco antes para o primeiro campo inválido, e quem usa leitor de tela nunca ouve o resumo.

</Callout>

O `Checkbox` informa `checked` em vez de `value`, então ligue à mão: `checked={field.value}`, `onCheckedChange={field.onChange}` e `ref={field.ref}`.

</Steps>

## Um formulário completo [#um-formulário-completo]

Tudo acima num formulário só: cinco campos, um schema, o resumo com foco e uma confirmação que recebe o foco quando o formulário some. Envie vazio e depois corrija os campos um a um. Abra a aba Code para ver o arquivo inteiro.

<Preview name="guideb-forms/complete" />

<Checklist>

- Todo controle tem um rótulo visível, não só um placeholder
- Cada erro diz como resolver, no campo e no resumo
- Depois de um envio com erro, o foco vai para o resumo, e cada link chega ao campo
- `noValidate` no `<form>`, para os balões do navegador não competirem com as suas mensagens
- Os ids vêm de `useId()`, e dados pessoais têm `autoComplete`

</Checklist>


# Idiomas e RTL (/pt-br/docs/guides/i18n)

<Learn>

- Como o `MessagesProvider` traduz os textos embutidos, e como trocar só alguns
- Todas as chaves de mensagem, em inglês e português
- Qual locale os componentes de data usam, e como defini-lo
- Como o `DirectionProvider` vira a página da direita para a esquerda em qualquer estilo

</Learn>

## Textos embutidos [#textos-embutidos]

Quase todo texto numa interface feita com o Camaleo é seu: rótulos, títulos, texto dos botões. Alguns componentes também trazem textos próprios, como o nome de um botão de fechar, a mensagem de uma tabela vazia ou o "Página 3" lido pelo leitor de tela. Esses vêm em inglês por padrão.

Ponha um `MessagesProvider` perto da raiz para trocá-los. Escolha um idioma abaixo: só os textos dos componentes mudam.

<Preview name="guideb-i18n/messages" />

<FileCode file="app/layout.tsx" code={`
  import { MessagesProvider } from "@camaleo/react";

  <MessagesProvider locale="pt-BR">{children}</MessagesProvider>
`} />

O `locale` escolhe um pacote embutido: `"en"` (o padrão) ou `"pt-BR"`. A prop do componente sempre vence o provider, então `<Pagination previousLabel="Voltar" />` continua dizendo "Voltar".

## Troque só alguns textos [#troque-só-alguns-textos]

O `messages` aceita qualquer parte das chaves. Cada grupo que você passa é mesclado sobre o conjunto de baixo, então você só escreve o que muda:

<FileCode file="app/layout.tsx" code={`
  <MessagesProvider
    locale="pt-BR"
    messages={{ drawer: { close: "Fechar painel" }, dataTable: { empty: "Nenhum pedido ainda." } }}
  >
    {children}
  </MessagesProvider>
`} />

Providers podem ser aninhados. Um provider interno sem `locale` parte dos textos do pai, o que ajuda quando uma área tem o próprio vocabulário:

<FileCode file="app/pedidos/layout.tsx" code={`
  <MessagesProvider messages={{ dataTable: { empty: "Nenhum pedido com esses filtros." } }}>
    {children}
  </MessagesProvider>
`} />

Para um idioma que o Camaleo não traz, escreva um conjunto completo com o tipo `Messages` e passe em `messages`. O tipo garante que nenhuma chave fique faltando.

## Servidor ou cliente [#servidor-ou-cliente]

Algumas mensagens são funções, como `pagination.page(3)` → "Página 3". O React não passa funções de um Server Component para um de cliente, então:

- Num Server Component (um layout raiz), passe `locale` e `messages` só com textos.
- Para trocar uma função, ponha o provider num componente de cliente:

<FileCode file="app/messages.tsx" code={`
  "use client";
  import { MessagesProvider } from "@camaleo/react";

  export function AppMessages({ children }: { children: React.ReactNode }) {
    return (
      <MessagesProvider
        locale="pt-BR"
        messages={{ pagination: { page: (page) => \`Ir para a página \${page}\` } }}
      >
        {children}
      </MessagesProvider>
    );
  }
`} />

Leia os textos nos seus componentes com `useMessages()` (cliente) ou `<Message pick="spinner.label" />` (servidor). Veja [Server Components e SSR](/pt-br/docs/guides/ssr#o-auxiliar-message).

## Todas as chaves de mensagem [#todas-as-chaves-de-mensagem]

Esta é a interface `Messages` de `packages/react/src/messages.tsx`, com os valores dos pacotes `en` e `ptBR`. As chaves que são funções mostram o resultado de uma chamada de exemplo.

| Chave | English | Português |
| --- | --- | --- |
| `breadcrumb.label` | Breadcrumb | Trilha de navegação |
| `breadcrumb.more` | More pages | Mais páginas |
| `carousel.label` | Carousel | Carrossel |
| `carousel.previous` | Previous slide | Slide anterior |
| `carousel.next` | Next slide | Próximo slide |
| `carousel.play` | Play | Reproduzir |
| `carousel.pause` | Pause | Pausar |
| `carousel.indicators` | Choose slide | Escolher slide |
| `carousel.goToSlide(2)` | Go to slide 2 | Ir para o slide 2 |
| `codeBlock.copy` | Copy | Copiar |
| `codeBlock.copied` | Copied | Copiado |
| `codeBlock.label` | Code | Código |
| `combobox.clear` | Clear | Limpar |
| `combobox.showOptions` | Show options | Mostrar opções |
| `commandPalette.placeholder` | Type a command or search… | Digite um comando ou pesquise… |
| `commandPalette.empty` | No matching commands found. | Nenhum comando encontrado. |
| `dataTable.caption` | Data table | Tabela de dados |
| `dataTable.empty` | No records found. | Nenhum registro encontrado. |
| `dataTable.selectAll` | Select all rows | Selecionar todas as linhas |
| `dataTable.selectRow(0)` | Select row 1 | Selecionar linha 1 |
| `dataTable.pagination` | Table pagination | Paginação da tabela |
| `drawer.close` | Close | Fechar |
| `fileUpload.choose` | Choose files | Escolher arquivos |
| `image.failed` | Failed to load image | Não foi possível carregar a imagem |
| `image.unavailable` | Unavailable image | Imagem indisponível |
| `inputGroup.showPassword` | Show password | Mostrar senha |
| `inputGroup.hidePassword` | Hide password | Ocultar senha |
| `inputGroup.clear` | Clear search | Limpar busca |
| `numberField.decrease` | Decrease | Diminuir |
| `numberField.increase` | Increase | Aumentar |
| `otpField.cell(0, 6)` | Character 1 of 6 | Caractere 1 de 6 |
| `pagination.label` | Pagination | Paginação |
| `pagination.previous` | Previous | Anterior |
| `pagination.next` | Next | Próxima |
| `pagination.page(3)` | Page 3 | Página 3 |
| `progressCircle.label` | Progress | Progresso |
| `sidebar.collapse` | Collapse sidebar | Recolher menu lateral |
| `sidebar.expand` | Expand sidebar | Expandir menu lateral |
| `skipLink.label` | Skip to content | Pular para o conteúdo |
| `spinner.label` | Loading | Carregando |
| `splitter.handle` | Resize panel | Redimensionar painel |
| `table.scroll` | Table | Tabela |
| `tagsInput.remove("design")` | Remove design | Remover design |
| `toast.close` | Close | Fechar |
| `toggletip.close` | Close tip | Fechar dica |

<Callout kind="caution">

Um texto vem da primitiva, não do Camaleo: o `Progress` indeterminado é anunciado pelo Base UI como "indeterminate progress", em inglês, seja qual for o provider.

</Callout>

## Datas e horários [#datas-e-horários]

O `MessagesProvider` não mexe em datas. Os componentes de data (`Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `DateField`, `TimeField`) recebem a prop `locale`, que define a ordem dos segmentos, os nomes dos meses e dos dias, o primeiro dia da semana e o relógio. A mesma data em três locales:

<Preview name="date-field/locales" compact />

Sem `locale`, eles usam o `I18nProvider` mais próximo (que o Camaleo reexporta) e depois o idioma do navegador. Defina no servidor, para o servidor e o navegador formatarem igual:

<FileCode file="app/layout.tsx" code={`
  import { I18nProvider, MessagesProvider } from "@camaleo/react";

  <MessagesProvider locale="pt-BR">
    <I18nProvider locale="pt-BR">{children}</I18nProvider>
  </MessagesProvider>
`} />

## Da direita para a esquerda [#da-direita-para-a-esquerda]

Os estilos e o CSS dos componentes usam propriedades lógicas (`margin-inline-start`, `inset-inline-end`, `border-start-start-radius`…), então o mesmo CSS funciona nas duas direções. Para virar uma página ou uma seção para RTL, faça três coisas juntas:

1. `dir="rtl"` no elemento, para o layout do navegador.
2. `lang` no mesmo elemento, para o leitor de tela escolher a voz certa.
3. `<DirectionProvider direction="rtl">` em volta, para os componentes inverterem o teclado (setas em abas, sliders e menus) e os popups.

Troque a direção abaixo e depois escolha outros estilos na barra "visualizar em": abas, slider, switch e botões espelham em todos os estilos.

<Preview name="guideb-i18n/rtl" />

<FileCode file="app/[lang]/layout.tsx" code={`
  import { DirectionProvider } from "@camaleo/react";

  const dir = lang === "ar" ? "rtl" : "ltr";

  <html lang={lang} dir={dir}>
    <body>
      <DirectionProvider direction={dir}>{children}</DirectionProvider>
    </body>
  </html>
`} />

<Callout kind="caution">

Algumas regras de estrutura do app ainda usam lados físicos e não espelham: a borda do `Sidebar`, a barra do item ativo e as contagens dele, os atalhos no `Menubar` e no `CommandPalette`, a linha do `Stepper` vertical e a posição do `SkipLink`. Confira essas partes no olho se o seu app for RTL.

</Callout>

Popups abertos dentro de uma seção RTL continuam RTL: o invólucro do portal copia a direção. Ícones seus que significam "avançar" ou "voltar" (setas, chevrons) precisam ser invertidos em RTL; ícones que mostram uma coisa (um sino, uma lixeira) não.

<Checklist>

- Um `MessagesProvider` na raiz, com o idioma da página
- Mensagens que são funções são trocadas num componente de cliente
- Os componentes de data recebem `locale` ou ficam dentro de um `I18nProvider`
- `dir`, `lang` e `DirectionProvider` mudam juntos
- Setas e chevrons do seu conteúdo invertem em RTL

</Checklist>


# Sobrescritas com escopo (/pt-br/docs/guides/scoped-overrides)

<Learn>

- Três jeitos de limitar uma sobrescrita: um token num elemento, uma regra `@scope`, um provider aninhado
- A ordem das camadas `cml.*`, e por que o seu CSS vence sem `!important`
- As armadilhas: ilhas, estados que você sobrescreve sem querer, `!important`, movimento reduzido

</Learn>

## Experimente [#experimente]

O card tem uma "zona de perigo" (`<div className="danger-zone">`). Cada opção muda a aparência só dessa área; o código que aparece com ela é o que roda.

<CodeSwitch
  name="guide-scope/settings"
  label="Sobrescrita"
  options={[
    { kicker: "Início", title: "Sem sobrescrita", note: "o estilo como vem.", file: "settings.tsx", code: `
      <div className="danger-zone">
        <Text>Zona de perigo</Text>
        <Button variant="outline">Transferir</Button>
        <Button variant="danger">Excluir espaço</Button>
      </div>` },
    { kicker: "Tokens", title: "Tokens na área", note: "os componentes da área leem os novos valores; nada fora dela muda.", file: "app.css", live: true, code: `
      .danger-zone {
        --cml-button-outline-border: var(--cml-danger);
        --cml-button-outline-bg: transparent;
      }` },
    { kicker: "@scope", title: "Uma regra com escopo", note: "CSS completo, limitado à área e interrompido nos estilos aninhados.", file: "app.css", live: true, code: `
      @scope (.danger-zone) to ([data-style]) {
        :scope {
          padding: 1rem;
          border: 1px dashed var(--cml-danger);
          border-radius: var(--cml-radius-surface);
        }
        [data-slot="text"]:first-child {
          color: var(--cml-danger);
        }
      }` },
    { kicker: "Um estilo", title: "Só neste estilo", note: "a mesma regra, mas só enquanto a página usa o estilo escolhido na barra.", file: "app.css", live: true, code: `
      @scope ([data-style="$skin"]) to ([data-style]) {
        .danger-zone [data-slot="button"] {
          letter-spacing: 0.04em;
          text-transform: uppercase;
        }
      }` },
  ]}
/>

## Escolha a ferramenta mais estreita [#escolha-a-ferramenta-mais-estreita]

| Ferramenta | Use para | Alcança |
| --- | --- | --- |
| Um token num elemento | Valores: cor, raio, tamanho, espaçamento | Esse elemento e tudo dentro dele |
| `@scope (…) to (…)` | Tudo o que um token não faz | Da raiz do escopo até o limite que você definir |
| Um `StyleProvider` aninhado | Outro estilo, outro modo ou outra marca | A subárvore dele, popups incluídos |

Comece pelos tokens. Um token mantém os estados do estilo funcionando (hover, foco, desabilitado), porque o estilo continua escrevendo as regras; você só muda os valores que elas leem.

<FileCode file="app.css" code={`
  /* Controles mais altos só no checkout */
  .checkout {
    --cml-control-height: 2.75rem;
    --cml-field-height: 2.75rem;
  }
`} />

<Callout kind="caution">

O elemento precisa estar **dentro** do provider. Todo elemento `[data-style]` declara todos os tokens de novo, então uma classe num wrapper em volta do `StyleProvider` é sobrescrita antes de chegar aos componentes.

</Callout>

Quando a mudança não é um valor (uma borda que não existe, outro layout), escreva uma regra dentro de `@scope`. Acrescente `to ([data-style])` para ela parar nos estilos aninhados, como fazem os arquivos de estilo:

<FileCode file="app.css" code={`
  @scope (.pricing) to ([data-style]) {
    [data-slot="card"] {
      border-style: dashed;
    }
  }
`} />

Para uma aparência totalmente diferente numa área, aninhe um provider. Ele é uma ilha: parte de tokens limpos, e os popups dele mantêm o estilo dele.

<FileCode file="docs-page.tsx" code={`
  <StyleProvider styleName="minimal">
    <Article />
    <StyleProvider styleName="retro" mode="dark">
      <Terminal />
    </StyleProvider>
  </StyleProvider>
`} />

## A ordem das camadas [#a-ordem-das-camadas]

O `base.css` declara quatro camadas antes de qualquer outra coisa. As camadas posteriores vencem as anteriores, e o CSS que não está em nenhuma camada vence todas elas:

<FileCode file="@camaleo/styles/base.css" code={`
  @layer cml.tokens, cml.components, cml.style, cml.preferences;
`} />

| Camada | Guarda |
| --- | --- |
| `cml.tokens` | O padrão de cada token (os valores do `minimal`) no `:root` e em `[data-style]` |
| `cml.components` | As regras dos componentes, quase todas dentro de `:where()`, para não somarem especificidade |
| `cml.style` | Os arquivos de estilo: valores de token em `[data-style="name"]` e as regras `@scope` do estilo |
| `cml.preferences` | Movimento reduzido e cores forçadas |
| o seu CSS sem camada | Vence tudo acima, seja qual for a especificidade |

Se o seu CSS fica numa camada (um design system, um framework de CSS), ordene as camadas uma vez, no topo da folha de estilo principal, antes de qualquer import. Uma camada listada depois de `cml` vence todas as subcamadas dela:

<FileCode file="app.css" code={`
  @layer cml, app;

  @import "@camaleo/styles/base.css";
  @import "@camaleo/styles/glass.css";

  @layer app {
    [data-style] { --cml-radius-surface: 20px; }
  }
`} />

<Callout>

Usa Tailwind? Os utilitários dele também ficam em camadas, e qual lado vence depende da mesma ordem. O guia [Tailwind CSS](/pt-br/docs/guides/tailwind) tem a linha que você precisa acrescentar.

</Callout>

## Armadilhas de especificidade [#armadilhas-de-especificidade]

- **Regras sem camada vencem os estados do estilo.** `[data-slot="button"] { background: navy }` fora de qualquer camada também vence as regras `:hover`, `[data-disabled]` e `:focus-visible` de todos os estilos, e o botão para de reagir. Mude `--cml-accent` e `--cml-accent-hover`, ou escreva os estados você mesmo.
- **`!important` vira as camadas de cabeça para baixo.** Uma declaração importante numa camada anterior vence uma numa camada posterior, e qualquer importante em camada vence um sem camada. Você nunca precisa dele para vencer a biblioteca; deixe-o de fora.
- **O seu CSS também vence `cml.preferences`.** Se você acrescentar uma transição ou uma animação, coloque-a dentro de `@media (prefers-reduced-motion: no-preference)` você mesmo.
- **Um escopo sem limite vaza para as ilhas.** `@scope (.pricing)` também estiliza um provider aninhado dentro de `.pricing`; acrescente `to ([data-style])`.
- **Um token definido alto demais se perde.** No `:root` ou fora do provider, ele é sobrescrito pelas declarações do próprio provider. Use `[data-style]` ou um elemento dentro dele.

<Checklist>

- Tokens primeiro; uma regra só quando nenhum token resolve
- Sobrescritas de token num elemento dentro do provider
- Regras `@scope` terminam com `to ([data-style])`
- Nada de `!important`; CSS em camada listado depois de `cml` numa única declaração `@layer`
- Hover, foco e desabilitado continuam visíveis depois da mudança, no modo claro e no escuro

</Checklist>


# Estilos e troca (/pt-br/docs/guides/skins)

<Learn>

- Quais arquivos CSS e fontes cada um dos 13 estilos precisa
- O que `styleName`, `mode` e `brand` fazem, e quais deles são herdados
- Como aninhar estilos e trocá-los em tempo de execução sem perder estado

</Learn>

## Experimente [#experimente]

Escreva na nota, curta algumas vezes e escolha outro estilo. Os componentes renderizam de novo com outro CSS; nada é montado outra vez, então o texto e a contagem continuam.

<Preview name="guide-skins/switcher" />

<Steps>

## Importe o CSS [#importe-o-css]

O `base.css` traz os tokens, as regras dos componentes e a ordem das camadas. Importe uma vez e depois um arquivo para cada estilo que você usa. O `minimal` é o padrão e não precisa de arquivo próprio.

<FileCode file="app/layout.tsx" code={`
  import "@camaleo/styles/base.css";
  import "@camaleo/styles/neubrutalism.css";
  import "@camaleo/styles/editorial.css";
`} />

<Callout>

Se as pessoas podem escolher o estilo, importe de antemão todos os estilos que você oferece. Um estilo sem o arquivo cai nos padrões do `minimal`, sem nenhum erro.

</Callout>

## Carregue as fontes [#carregue-as-fontes]

As fontes não vêm junto. Cada estilo nomeia as famílias dele nos tokens `--cml-font-*`, com fallbacks do sistema, então funciona mesmo sem elas, só que menos parecido consigo mesmo. Carregue só as dos estilos que você publica:

| Estilo | Fontes |
| --- | --- |
| minimal | Inter |
| swiss | Archivo |
| editorial | Newsreader (texto), Fraunces (títulos), Inter (controles e rótulos) |
| progressive | Figtree |
| material | Roboto Flex |
| cupertino | Inter |
| glass | Plus Jakarta Sans |
| neumorphism | Manrope |
| clay | Nunito, Fredoka (títulos) |
| neubrutalism | Space Grotesk |
| retro | IBM Plex Sans |
| retro-pixel | Pixelify Sans, Press Start 2P (títulos grandes, só latim básico) |
| y2k | Exo 2, Audiowide (títulos grandes) |

O CSS pede as famílias pelo nome, então uma tag `<link>` de folha de estilos ou um `@font-face` hospedado por você funciona do jeito que está. Com `next/font`, aponte o token para a variável da fonte:

<FileCode file="app/fonts.css" code={`
  /* app/layout.tsx: const grotesk = Space_Grotesk({ subsets: ["latin"], variable: "--font-grotesk" }) */
  [data-style="neubrutalism"] {
    --cml-font-body: var(--font-grotesk), system-ui, sans-serif;
  }
`} />

## Envolva o app [#envolva-o-app]

O `StyleProvider` renderiza uma `<div>` com `data-style`, `data-mode` e os tokens da marca inline. Tudo dentro dele, inclusive diálogos e menus renderizados num portal, recebe o estilo.

<FileCode file="app/providers.tsx" code={`
  import { StyleProvider } from "@camaleo/react";

  export function Providers({ children }: { children: React.ReactNode }) {
    return (
      <StyleProvider styleName="neubrutalism" mode="system" brand="#3fa34d">
        {children}
      </StyleProvider>
    );
  }
`} />

| Prop | Valores | Herda de um provider pai? |
| --- | --- | --- |
| `styleName` | Um dos 13 nomes; `minimal` por padrão | Não: um provider aninhado sem ela é `minimal` |
| `mode` | `light`, `dark` ou `system` | Sim, quando omitida (a raiz segue o sistema) |
| `brand` | Qualquer cor CSS | Sim, quando omitida |

</Steps>

## Os 13 estilos [#os-13-estilos]

Todo estilo renderiza o mesmo DOM: o teste de matriz compara o markup dos 13 e falha se um for diferente. Só o CSS muda, e é por isso que a troca sai barata.

| Estilo | Em uma linha |
| --- | --- |
| minimal | Neutro e discreto, os padrões de onde todo outro estilo parte |
| swiss | Uma grotesca, linhas de 1px em tinta, cantos retos, sem sombras |
| editorial | Papel, tinta e filetes finos, com serifas de revista |
| progressive | Cara de app instalável: fundo cinza quente, áreas de toque de 44px |
| material | Superfícies tonais, botões em pílula, campos preenchidos e contornados |
| cupertino | Fundo cinza agrupado, células brancas, cantos contínuos |
| glass | Camadas translúcidas foscas sobre um fundo suave e desfocado |
| neumorphism | Uma só superfície moldada pela luz: ações em relevo, campos afundados |
| clay | Formas fofas em tons pastel que parecem modeladas em argila |
| neubrutalism | Contornos de 2px em tinta e sombras duras, sem desfoque |
| retro | Visual clássico de desktop com chanfros em quatro cores |
| retro-pixel | 8 bits: bordas grossas em tinta, cantos em degrau, fontes pixeladas |
| y2k | Botões brilhantes de gelatina, cromado escovado e risca de giz |

O `material` se inspira no Material Design e o `cupertino` nas Human Interface Guidelines. O Camaleo não tem ligação com o Google nem com a Apple e não usa nenhuma fonte, ícone ou marca registrada deles.

## Aninhamento [#aninhamento]

Um `StyleProvider` aninhado é uma ilha: todo token é declarado de novo no elemento dele, então ele parte de padrões limpos em vez de se misturar com o pai. O `mode` e o `brand` do pai ainda chegam até ele, a não ser que você os defina.

<Preview name="guide-skins/nested" />

## Troca em tempo de execução [#troca-em-tempo-de-execução]

Guarde o estilo no estado e passe para baixo. Mudar o `styleName` muda um atributo no mesmo elemento, então o React mantém cada componente e o estado dele. Não coloque o estilo numa `key`: isso remonta a árvore e zera os formulários.

<FileCode file="skin-switcher.tsx" code={`
  "use client";
  import { useState } from "react";
  import { STYLE_NAMES, type StyleName, StyleProvider } from "@camaleo/react";

  export function App({ children }: { children: React.ReactNode }) {
    const [skin, setSkin] = useState<StyleName>("minimal");
    return (
      <StyleProvider styleName={skin}>
        <select aria-label="Skin" value={skin} onChange={(e) => setSkin(e.target.value as StyleName)}>
          {STYLE_NAMES.map((name) => <option key={name}>{name}</option>)}
        </select>
        {children}
      </StyleProvider>
    );
  }
`} />

## A página inteira, a partir do servidor [#a-página-inteira-a-partir-do-servidor]

Para aplicar o estilo no próprio `<html>` (fundo da página, barras de rolagem), espalhe `styleScopeProps` nele. É seguro no servidor, então um layout raiz pode chamá-lo sem um componente de cliente.

<FileCode file="app/layout.tsx" code={`
  import { styleScopeProps } from "@camaleo/react/style-scope";

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="pt-BR" {...styleScopeProps({ styleName: "editorial", mode: "system" })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

<Callout kind="caution">

Popups renderizam num portal fora da sua árvore. Eles mantêm o estilo pelo contexto do React, então renderize-os dentro de um `StyleProvider` (ou sob um `<html>` com `styleScopeProps`), nunca numa raiz React separada.

</Callout>

<Checklist>

- O `base.css` é importado uma vez, antes dos arquivos dos estilos
- Há um arquivo CSS para cada estilo que as pessoas podem escolher
- As fontes desses estilos estão carregadas
- O estilo fica no estado, nunca numa `key`

</Checklist>


# Server Components e SSR (/pt-br/docs/guides/ssr)

<Learn>

- Quais componentes são Server Components e quais abrem uma fronteira `"use client"`
- Como definir estilo, modo e marca no `<html>` a partir do layout raiz
- Como guardar a escolha de claro ou escuro sem a página piscar
- Como os textos embutidos chegam aos Server Components pelo `Message`

</Learn>

## Componentes de servidor e de cliente [#componentes-de-servidor-e-de-cliente]

Cada componente fica no próprio arquivo em `packages/react/src`, e o build mantém esses arquivos separados, então um `"use client"` nunca vaza para um arquivo que não precisa dele. Você pode importar tudo de `@camaleo/react` num Server Component: o React transforma cada componente de cliente numa fronteira sozinho.

Estes arquivos **não** têm `"use client"`. Os componentes deles renderizam só no servidor e não mandam JavaScript:

| Arquivo | Componentes |
| --- | --- |
| `alert.tsx` | `Alert`, `AlertTitle`, `AlertDescription` |
| `app-shell.tsx` | `AppShell`, `AppShellHeader`, `AppShellBody`, `AppShellContent`, `AppShellFooter`, `SkipLink` |
| `data-display.tsx` | `Stat` e partes, `DataList` e partes, `Timeline` e partes, `EmptyState` e partes, `ProgressCircle` |
| `display.tsx` | `Badge`, `Kbd`, `Card` e partes, `Table` e partes, `Skeleton` |
| `layout.tsx` | `Box`, `Stack`, `Grid`, `Container`, `AspectRatio` |
| `spinner.tsx` | `Spinner` |
| `typography.tsx` | `Heading`, `Text` |
| `visually-hidden.tsx` | `VisuallyHidden` |
| `style-scope.ts` | `styleScopeProps()` (uma função comum) |

Todo o resto é componente de cliente: toda parte interativa (feita sobre Base UI ou React Aria), mais `StyleProvider`, `MessagesProvider` e `DirectionProvider`, que guardam contexto do React. Componentes de cliente também viram HTML no servidor; eles só hidratam no navegador.

<Callout kind="tip">

O `Table` continua Server Component mesmo rolando: só o pequeno contêiner de rolagem (`table-scroll.tsx`) é de cliente, e ele só vira uma região focável quando a tabela transborda.

</Callout>

<Steps>

## Defina o estilo no `<html>` [#defina-o-estilo-no-html]

No layout raiz, espalhe `styleScopeProps()` no `<html>`. É uma função comum, segura num Server Component, que devolve `data-style`, `data-mode` e a escala da marca como custom properties inline. O estilo está no primeiro byte do HTML, então nada espera o JavaScript.

<FileCode file="app/layout.tsx" code={`
  import "@camaleo/styles/base.css";
  import "@camaleo/styles/glass.css";
  import { styleScopeProps } from "@camaleo/react/style-scope";

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="pt-BR" {...styleScopeProps({ styleName: "glass", brand: "#3fa34d" })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

Importe o `base.css` uma vez e o CSS de cada estilo que você renderiza. Diálogos, menus e toasts vão por portal para o `<body>`, então herdam o estilo do `<html>` sem trabalho extra.

## Guarde o modo da pessoa sem piscar [#guarde-o-modo-da-pessoa-sem-piscar]

As cores do Camaleo usam `light-dark()`, e o `data-mode` só define o `color-scheme`. Sem `mode`, a página segue o sistema com CSS puro: não há script rodando antes da pintura, então não há o que piscar.

Quando a pessoa escolhe claro ou escuro, guarde a escolha num cookie e leia no layout. O servidor já manda o `data-mode` certo na primeira resposta.

<FileCode file="app/layout.tsx" code={`
  import { cookies } from "next/headers";
  import { styleScopeProps } from "@camaleo/react/style-scope";

  const MODES = ["light", "dark", "system"] as const;

  export default async function RootLayout({ children }: { children: React.ReactNode }) {
    const saved = (await cookies()).get("cml-mode")?.value;
    // Só aceite valores conhecidos: o cookie vem do navegador.
    const mode = MODES.find((m) => m === saved) ?? "system";
    return (
      <html lang="pt-BR" {...styleScopeProps({ styleName: "glass", mode })}>
        <body>{children}</body>
      </html>
    );
  }
`} />

Grave o cookie numa Server Function. Usada como `action` de um formulário, ela devolve a página renderizada de novo na mesma ida ao servidor:

<FileCode file="app/actions.ts" code={`
  "use server";
  import { cookies } from "next/headers";

  export async function setMode(form: FormData) {
    const mode = form.get("mode");
    if (mode !== "light" && mode !== "dark" && mode !== "system") return;
    (await cookies()).set("cml-mode", mode, { maxAge: 60 * 60 * 24 * 365 });
  }
`} />

<FileCode file="app/mode-switch.tsx" code={`
  import { Button } from "@camaleo/react";
  import { setMode } from "./actions";

  export function ModeSwitch() {
    return (
      <form action={setMode}>
        <Button type="submit" name="mode" value="dark" variant="outline">
          Escuro
        </Button>
      </form>
    );
  }
`} />

<Callout kind="caution">

Nesta versão do Next.js, `cookies()` é assíncrono, e ler cookies deixa a rota dinâmica. Se a página precisa ser estática, deixe o `mode` de fora e o sistema decide.

</Callout>

## Crie ilhas com `StyleProvider` [#crie-ilhas-com-styleprovider]

O `StyleProvider` é componente de cliente, mas renderiza o seu `<div data-style>` no servidor como qualquer outro. Uma seção em outro estilo já está no HTML desde o início:

<FileCode file="app/page.tsx" code={`
  import { Button, StyleProvider } from "@camaleo/react";

  export default function Page() {
    return (
      <StyleProvider styleName="neubrutalism" mode="light">
        <Button>Começar</Button>
      </StyleProvider>
    );
  }
`} />

Popups abertos dentro da ilha mantêm o estilo dela: o `DialogContent` e as outras partes em portal leem o escopo do provider pelo contexto e o aplicam de novo.

## Defina o idioma no servidor [#defina-o-idioma-no-servidor]

O `MessagesProvider` aceita um pacote embutido pelo nome, que é um texto simples e atravessa a fronteira servidor–cliente sem problema:

<FileCode file="app/layout.tsx" code={`
  import { MessagesProvider } from "@camaleo/react";

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html lang="pt-BR">
        <body>
          <MessagesProvider locale="pt-BR">{children}</MessagesProvider>
        </body>
      </html>
    );
  }
`} />

Trocas feitas só de textos também funcionam aqui. Algumas mensagens são funções (`pagination.page`, `carousel.goToSlide`…), e funções não passam de um Server Component para um de cliente, então troque essas num componente de cliente. O [guia de Idiomas e RTL](/pt-br/docs/guides/i18n) traz todas as chaves.

</Steps>

## O auxiliar `Message` [#o-auxiliar-message]

Server Components não leem contexto do React, então `Spinner`, `SkipLink` e `ProgressCircle` não podem chamar `useMessages()`. O rótulo padrão deles é `<Message pick="…" />`: um componente de cliente minúsculo que imprime uma mensagem do `MessagesProvider` mais próximo. O resto de cada componente fica no servidor.

Você pode usá-lo nos seus Server Components para as mesmas três chaves:

<FileCode file="app/loading.tsx" code={`
  import { Message } from "@camaleo/react";

  // Um "Carregando…" visível, no idioma do MessagesProvider mais próximo.
  export default function Loading() {
    return (
      <p role="status">
        <Message pick="spinner.label" />…
      </p>
    );
  }
`} />

O `pick` aceita `"skipLink.label"`, `"spinner.label"` e `"progressCircle.label"`. Para qualquer outro texto, use `useMessages()` num componente de cliente.

<Checklist>

- No código-fonte da página, o `<html>` (ou o `<div>` do provider) já tem `data-style`
- Todo estilo renderizado tem o CSS importado no layout raiz
- O modo lido do cookie é conferido contra os valores conhecidos
- Nenhum layout ganhou `"use client"` só por causa do Camaleo
- O `MessagesProvider` num Server Component recebe `locale` ou `messages` só com textos

</Checklist>


# Tailwind CSS (/pt-br/docs/guides/tailwind)

<Learn>

- Onde as camadas do Camaleo entram entre as do Tailwind, e por que a ordem importa
- Como usar os tokens `--cml-*` como valores do tema do Tailwind
- Como chegar a uma parte de um componente pelo `data-slot`
- O que estilizar com utilitários e o que deixar para o estilo

</Learn>

O Camaleo não precisa do Tailwind: os estilos são CSS puro. Se o seu app já usa o Tailwind v4, os dois funcionam juntos com poucas linhas na folha de estilo principal. Não há plugin nem preset para instalar.

<Steps>

## Ordene as camadas [#ordene-as-camadas]

Todo o CSS do Camaleo fica em quatro camadas: `cml.tokens`, `cml.components`, `cml.style` e `cml.preferences`. O Tailwind v4 usa `theme`, `base`, `components` e `utilities`. A camada declarada primeiro perde, então declare a ordem inteira uma vez, **antes** dos imports:

<FileCode file="app/globals.css" code={`
  @layer theme, base, cml, components, utilities;

  @import "tailwindcss";
  @import "@camaleo/styles/base.css";
  @import "@camaleo/styles/glass.css";
`} />

Com essa ordem:

- O reset do Tailwind (Preflight, em `base`) fica **abaixo** do Camaleo, então nunca achata os botões ou campos de um estilo.
- Os seus utilitários ficam **acima** do Camaleo, então `className="mt-6 w-full"` num componente vence o espaçamento e a largura dele.
- O CSS sem camada que você escreve continua vencendo tudo.

<Callout kind="caution">

Sem a primeira linha, quem decide é a ordem dos imports: as camadas do Camaleo vêm depois das do Tailwind e vencem até os seus utilitários, e um `className="w-full"` num `Button` parece não fazer nada.

</Callout>

## Transforme tokens em valores do tema [#transforme-tokens-em-valores-do-tema]

Mapeie os tokens que você quer como utilitários num bloco `@theme inline`. Os nomes abaixo usam o prefixo `cml-` para nunca colidir com a paleta do Tailwind:

<FileCode file="app/globals.css" code={`
  @theme inline {
    --color-cml-surface: var(--cml-surface);
    --color-cml-raised: var(--cml-surface-raised);
    --color-cml-fg: var(--cml-fg);
    --color-cml-fg-secondary: var(--cml-fg-secondary);
    --color-cml-border: var(--cml-border);
    --color-cml-accent: var(--cml-accent);
    --color-cml-accent-fg: var(--cml-accent-fg);
    --color-cml-accent-text: var(--cml-accent-text);
    --color-cml-danger: var(--cml-danger);
    --radius-cml-control: var(--cml-radius-control);
    --radius-cml-surface: var(--cml-radius-surface);
    --font-cml-body: var(--cml-font-body);
    --font-cml-display: var(--cml-font-display);
  }
`} />

Agora existem `bg-cml-surface`, `text-cml-fg-secondary`, `border-cml-border`, `rounded-cml-surface` e `font-cml-display`, e cada um segue o estilo, o modo e a marca do `StyleProvider` mais próximo:

<FileCode file="app/page.tsx" code={`
  <aside className="rounded-cml-surface border border-cml-border bg-cml-raised p-6">
    <h2 className="font-cml-display text-cml-fg">Seu plano</h2>
    <p className="text-cml-fg-secondary">Renova em 12 de novembro.</p>
  </aside>
`} />

<Callout kind="tip">

O `inline` faz diferença. Sem ele, o Tailwind declara `--color-cml-surface` no `:root`, onde ele é resolvido uma vez, com o estilo da raiz. Com `inline`, o utilitário escreve o próprio `var(--cml-surface)`, e uma ilha em outro estilo ganha o valor dela.

</Callout>

## Estilize as partes pelo `data-slot` [#estilize-as-partes-pelo-data-slot]

Toda parte de todo componente tem um `data-slot` estável, e o estado vem em atributos de dados (`data-active`, `data-checked`, `data-disabled`…). As variantes de dados do Tailwind chegam neles direto:

<FileCode file="app/settings.tsx" code={`
  {/* Um estado do próprio elemento */}
  <Tab value="billing" className="data-active:font-semibold">Cobrança</Tab>

  {/* Uma parte dentro do componente */}
  <Card className="[&_[data-slot=card-title]]:text-lg">…</Card>

  {/* Um token, só para este elemento */}
  <Button className="[--cml-radius-control:0px]">Exportar</Button>
`} />

Cada página de componente lista slots, atributos de estado e tokens na seção **Styling hooks**.

</Steps>

## Não brigue com o estilo [#não-brigue-com-o-estilo]

Utilitários são para o **seu layout**: margens, larguras, posição no grid, espaçamentos e a página em volta dos componentes. Isso não muda de um estilo para outro.

A aparência de um componente (cores, raio, bordas, sombras, fontes) é do estilo. Se você pinta um `Button` com `bg-blue-600 rounded-full shadow-lg`, ele para de mudar com o estilo, ignora a marca e o modo escuro, e o contraste dele deixa de ser conferido pelos testes da biblioteca.

| Quer | Em vez de | Use |
| --- | --- | --- |
| Um controle mais redondo | `rounded-full` | `[--cml-radius-control:999px]` |
| A cor da marca | `bg-blue-600 text-white` | `bg-cml-accent text-cml-accent-fg` |
| Texto mais apagado | `text-gray-500` | `text-cml-fg-secondary` |
| Mudar só um estilo | `in-data-[style=retro]:…` | uma regra `@scope` no CSS |

O guia [Sobrescritas com escopo](/pt-br/docs/guides/scoped-overrides) mostra como escrever essas regras.

<Callout kind="caution">

Uma variante como `in-data-[style=retro]:uppercase` vale para qualquer **ancestral** retro, inclusive um que fica fora de uma ilha aninhada em outro estilo. As regras de estilo do próprio Camaleo usam `@scope ([data-style="retro"]) to ([data-style])`, que para na ilha seguinte.

</Callout>

## Modo escuro [#modo-escuro]

Os tokens já trocam com o modo (usam `light-dark()`), então `bg-cml-surface` não precisa da variante `dark:`. O `dark:` do Tailwind segue o sistema por padrão. Se você define o `mode` e precisa do `dark:` para as suas cores, aponte a variante para o `data-mode`:

<FileCode file="app/globals.css" code={`
  @custom-variant dark (&:where([data-mode=dark], [data-mode=dark] *));
`} />

Essa variante só enxerga um `mode="dark"` explícito. Com `mode="system"` ou sem modo, mantenha o padrão do Tailwind, ou use tokens.

<Checklist>

- `@layer theme, base, cml, components, utilities;` vem antes de qualquer `@import`
- Os tokens são mapeados com `@theme inline`, não com `@theme` simples
- Utilitários em componentes só cuidam de layout e espaçamento
- Mudanças de um estilo só ficam em regras `@scope`, não em variantes `in-data-[style=…]`
- As cores que você acrescenta vêm de tokens, então seguem o modo e a marca

</Checklist>


# Tokens (/pt-br/docs/guides/tokens)

<Learn>

- Onde os tokens são declarados, e por que sobrescrever no `:root` não basta
- Quais grupos existem, da escala da marca aos tokens de cada componente
- Como chegar a uma parte de um componente com `data-slot`

</Learn>

## Três níveis [#três-níveis]

Comece pelo topo e só desça quando precisar. Escolha um nível: a demo roda o código que aparece com ela, no estilo, no modo e na marca da barra "visualizar em".

<CodeSwitch
  name="guide-tokens/invite"
  label="Nível de personalização"
  options={[
    { kicker: "Início", title: "Padrão", note: "o estilo exatamente como vem.", file: "app.tsx", code: `
      <StyleProvider styleName="$skin">
        <InviteCard />
      </StyleProvider>` },
    { kicker: "Nível 1", title: "Um token", note: "uma linha de CSS muda todos os controles em todos os estilos.", file: "app.css", live: true, code: `
      [data-style] {
        --cml-radius-control: 999px;
      }` },
    { kicker: "Nível 2", title: "Uma regra com escopo", note: "muda a aparência de uma parte, só neste estilo. Troque de estilo e ela some.", file: "app.css", live: true, code: `
      @scope ([data-style="$skin"]) to ([data-style]) {
        [data-slot="button"] {
          text-transform: uppercase;
          letter-spacing: 0.06em;
        }
      }` },
    { kicker: "Nível 3", title: "Seu próprio estilo", note: "uma linguagem visual inteira num arquivo, com os mesmos componentes.", file: "sunset.css", live: true, skin: "sunset", code: `
      @layer cml.style {
        [data-style="sunset"] {
          --cml-font-body: "Fraunces", Georgia, serif;
          --cml-surface: light-dark(#fff7ef, #1c1410);
          --cml-surface-raised: light-dark(#fffdf9, #261b15);
          --cml-fg: light-dark(#2b1a14, #f6e9df);
          --cml-border: light-dark(#2b1a14, #f6e9df);
          --cml-border-width: 2px;
          --cml-radius-control: 20px;
          --cml-radius-surface: 24px;
          --cml-shadow-surface: 6px 6px 0 var(--cml-border);
        }
      }` },
  ]}
/>

## Onde os tokens moram [#onde-os-tokens-moram]

O `base.css` declara todos os tokens no `:root` **e em todo elemento com `data-style`** (a `<div>` que um `StyleProvider` renderiza). É isso que faz de um provider aninhado uma ilha: ele parte dos padrões em vez de herdar a aparência do pai. Os padrões são o estilo `minimal`.

Um arquivo de estilo só redefine tokens em `[data-style="<name>"]`, dentro da camada `cml.style`. Todo o CSS da biblioteca fica em camadas, então **o seu CSS sem camada vence** sem `!important` nem especificidade extra.

<FileCode file="app.css" code={`
  /* Todos os estilos, todos os providers da página */
  [data-style] {
    --cml-radius-control: 999px;
  }

  /* Uma área: um elemento dentro do provider */
  .checkout {
    --cml-control-height: 2.75rem;
  }
`} />

<Callout kind="caution">

Um token definido no `:root` ou num wrapper **fora** de um `StyleProvider` não chega aos componentes dele: o elemento `data-style` do provider declara todos os tokens de novo. Use `[data-style]`, ou defina o token num elemento dentro do provider.

</Callout>

As cores usam `light-dark()`, então uma declaração cobre os dois modos. O navegador escolhe o lado pelo `color-scheme`, que o `data-mode` define (veja [Modo escuro](/pt-br/docs/guides/dark-mode)).

## Os grupos [#os-grupos]

| Grupo | O que guarda | Por exemplo |
| --- | --- | --- |
| Escala da marca | Os 11 passos gerados pelo `createBrand`, cada um com uma cor de texto e uma de hover. Definidos no `:root`, não por estilo, para que uma marca definida mais acima chegue às ilhas aninhadas. | `--cml-brand-600`, `--cml-brand-600-fg` |
| Tipografia | Famílias e tamanhos de fonte para corpo, controles, campos e rótulos; pesos, caixa e espaçamento entre letras. | `--cml-font-body`, `--cml-font-size-control` |
| Cor | Superfícies, texto, bordas, o acento (tirado da escala da marca) e as cores de status. | `--cml-surface`, `--cml-accent`, `--cml-danger` |
| Forma e profundidade | Largura da borda, raios, sombras, o anel de foco. | `--cml-radius-control`, `--cml-shadow-surface` |
| Campos de formulário | Altura, padding e fundo dos campos; tamanhos de check, switch e slider. | `--cml-field-height`, `--cml-switch-width` |
| Densidade | Alturas e paddings dos controles, padding das superfícies, o passo do layout. | `--cml-control-height`, `--cml-space` |
| Movimento | Durações, easing e a distância que as coisas percorrem. | `--cml-duration-fast`, `--cml-ease-standard` |
| Por componente | Sem valor por padrão; um estilo define só o que precisa. | `--cml-button-outline-bg`, `--cml-tab-active-bg` |

<Callout>

Mude o token semântico (`--cml-accent`, `--cml-surface`), não o passo da marca: cada estilo escolhe os próprios passos, então `--cml-accent` é o passo 600 no `minimal` e o passo 500 no `neubrutalism`.

</Callout>

## Tokens por componente [#tokens-por-componente]

Os tokens de componente são declarados como `initial`, então uma ilha aninhada nunca os herda, e toda regra que lê um deles tem um fallback. Definir um muda só aquela parte:

<FileCode file="app.css" code={`
  /* button.css lê var(--cml-button-outline-bg, var(--cml-surface-raised)) */
  [data-style] {
    --cml-button-outline-bg: transparent;
  }
`} />

Cada página de componente lista os tokens que ele lê em **Styling hooks**, agrupados em cor, forma, tipografia e os próprios. Comece por lá em vez de adivinhar.

## Ganchos de estilização [#ganchos-de-estilização]

Quando nenhum token cobre o que você quer, mire na parte. Todo componente renderiza um `data-slot` com o nome da parte, e a biblioteca o escreve **depois** das suas props, então ele não é substituído sem querer. Variantes e estados também são atributos:

<FileCode file="app.css" code={`
  [data-slot="button"][data-variant="outline"] {
    border-style: dashed;
  }

  [data-slot="switch"][data-checked] {
    --cml-accent: var(--cml-success);
  }
`} />

Para limitar uma regra a um estilo ou a uma área, envolva-a em `@scope`: veja [Sobrescritas com escopo](/pt-br/docs/guides/scoped-overrides).

## Todos os tokens [#todos-os-tokens]

Lidos do `tokens.css` no build do site. A última coluna mostra o valor no estilo escolhido na barra "visualizar em"; um traço quer dizer que o estilo mantém o padrão.

<TokenTable />

<Checklist>

- Sobrescreva com `[data-style]` ou num elemento dentro do provider, não no `:root`
- Mude tokens semânticos (`--cml-accent`), não passos da marca
- Deixe as suas sobrescritas sem camada, para vencerem a biblioteca sem `!important`
- Confira o contraste do texto (4,5:1) no modo claro e no escuro depois de mudar qualquer cor

</Checklist>


# Documentação (/pt-br/docs)

<HomeSearch label="Buscar componentes, tokens, guias…" />

## Comece aqui [#comece-aqui]

<HomeSteps>
	<HomeStep href="/pt-br/docs/installation" title="Instale">Dois pacotes e uma folha de estilo, no Next.js ou no Vite.</HomeStep>
	<HomeStep href="/pt-br/docs/guides/skins" title="Escolha um estilo">Carregue um ou vários, troque em tempo de execução, defina a cor da marca e o modo escuro.</HomeStep>
	<HomeStep href="/pt-br/docs/guides/tokens" title="Deixe com a sua cara">Tokens, regras com escopo ou um décimo quarto estilo escrito do zero.</HomeStep>
</HomeSteps>

## Componentes [#componentes]

<HomeCategories summary="{n} páginas de componente em {g} grupos, cada uma com exemplos ao vivo, props e notas de teclado. As miniaturas vestem o estilo, o modo e a cor da barra acima." />

## Estilos [#estilos]

Abra um estilo para ver as fontes, os tokens e quando usá-lo. Para vestir todos os exemplos com ele, escolha-o na barra acima.

<HomeSkins current="em uso" own="Crie o seu" />

<HomeColumns>
<HomeColumn>

## Guias [#guias]

- [Modo escuro sem piscar](/pt-br/docs/guides/dark-mode)
- [Cor da marca e contraste](/pt-br/docs/guides/brand-color)
- [Formulários com react-hook-form e zod](/pt-br/docs/guides/forms)
- [Server Components e SSR](/pt-br/docs/guides/ssr)
- [Direita para a esquerda e datas por idioma](/pt-br/docs/guides/i18n)

</HomeColumn>
<HomeColumn>

## Novidades [#novidades]

- **30 out.** Acabamento por estilo: abas verticais no Material, linhas de tabela no glass, alertas no Neubrutalism.
- **30 out.** Itens de rádio e submenus no Menu, erros no Stepper, legenda e rodapé de tabela.
- **30 out.** Textos padrão em inglês com um `MessagesProvider` e um pacote pt-BR.
- **28–30 out.** Uma página para cada componente, com exemplos ao vivo nos 13 estilos.

<HomeMore href="/pt-br/docs/changelog">Changelog completo</HomeMore>

</HomeColumn>
</HomeColumns>

<HomeNote>

**Usa um assistente de IA?** As páginas em inglês têm versão em Markdown (acrescente `.md` à URL), o [/llms.txt](/llms.txt) indexa o site e o [/llms-full.txt](/llms-full.txt) traz tudo num arquivo só.

</HomeNote>


# Instalação (/pt-br/docs/installation)

<Learn>

- Quais pacotes e arquivos CSS adicionar
- Como escolher estilo, modo e cor da marca para o app inteiro
- Como passar para o português os textos que os componentes já trazem

</Learn>

<Steps>

## Instale os pacotes [#instale-os-pacotes]

O `@camaleo/react` traz os componentes; o `@camaleo/styles`, o CSS e o `createBrand`.

<FileCode file="terminal" lang="bash" code={`
  pnpm add @camaleo/react @camaleo/styles
`} />

## Importe o CSS [#importe-o-css]

Importe o `base.css` uma vez e depois um arquivo para cada estilo que você usar. O `minimal` é o padrão e não precisa de arquivo próprio.

<FileCode file="app/layout.tsx" code={`
  import "@camaleo/styles/base.css";
  import "@camaleo/styles/neumorphism.css";
`} />

As fontes não vêm no pacote. As de cada estilo estão em [Estilos e troca](/pt-br/docs/guides/skins#carregue-as-fontes); sem elas, o estilo cai nas fontes do sistema.

## Envolva o app [#envolva-o-app]

O `StyleProvider` aplica o estilo, o modo e a cor da marca a tudo dentro dele, inclusive popups.

<FileCode file="app/providers.tsx" code={`
  import { Button, StyleProvider } from "@camaleo/react";

  <StyleProvider styleName="neumorphism" mode="system" brand="#7c3aed">
    <Button>Salvar</Button>
  </StyleProvider>
`} />

| Prop | Valores |
| --- | --- |
| `styleName` | `minimal` (padrão), `swiss`, `editorial`, `progressive`, `material`, `cupertino`, `glass`, `neumorphism`, `clay`, `neubrutalism`, `retro`, `retro-pixel`, `y2k` |
| `mode` | `light`, `dark` ou `system`. Sem ele, herda do pai; na raiz, segue o sistema, sem nenhum script |
| `brand` | Qualquer cor CSS. A biblioteca gera a escala e mantém o texto sobre ela em 4,5:1 ou mais |

Para aplicar o estilo na página inteira a partir de um Server Component, espalhe `styleScopeProps` no `<html>`:

<FileCode file="app/layout.tsx" code={`
  import { styleScopeProps } from "@camaleo/react/style-scope";

  <html lang="pt-BR" {...styleScopeProps({ styleName: "editorial" })}>
`} />

<Callout>

O `material` é inspirado no Material Design e o `cupertino` nas Human Interface Guidelines. O Camaleo não é afiliado ao Google nem à Apple e não usa fontes, ícones ou marcas deles.

</Callout>

## Defina os textos dos componentes [#defina-os-textos-dos-componentes]

Componentes que mostram ou anunciam texto por conta própria (botões de fechar, "Página 3", estados vazios) falam inglês por padrão. Para português, envolva o app uma vez com o `MessagesProvider`:

<FileCode file="app/layout.tsx" code={`
  import { MessagesProvider } from "@camaleo/react";

  <MessagesProvider locale="pt-BR">{children}</MessagesProvider>
`} />

- `locale`: `"en"` ou `"pt-BR"`, os pacotes que vêm com a biblioteca. É a forma de usar num Server Component.
- `messages`: só as chaves que você quer mudar, mescladas sobre o locale, por exemplo `messages={{ toast: { close: "Dispensar" } }}`. Algumas chaves são funções (`pagination.page`), que só um componente cliente consegue passar.
- A prop do próprio componente (por exemplo `closeLabel`) continua vencendo os dois. Mais em [Idiomas e RTL](/pt-br/docs/guides/i18n).

</Steps>

## Personalize [#personalize]

Do menos ao mais invasivo:

1. **Tokens.** Defina-os em `[data-style]`, fora de qualquer camada, e eles vencem a biblioteca: `[data-style] { --cml-radius-control: 4px; }`. Só `:root` não chega dentro de um provider, porque cada provider declara os tokens de novo. Veja [Tokens](/pt-br/docs/guides/tokens).
2. **Partes.** Mire o `data-slot` e os atributos de estado do componente: `[data-slot="button"][data-variant="outline"] { … }`. Para limitar uma regra a uma área ou a um estilo, veja [Sobrescritas com escopo](/pt-br/docs/guides/scoped-overrides).
3. **Marcação.** Use `className`, `style` ou a prop `render` para trocar o elemento que o componente renderiza.

<Checklist>

- `@camaleo/react` e `@camaleo/styles` instalados
- `base.css` importado uma vez, depois um arquivo para cada estilo que você usa
- O app dentro de um `StyleProvider` (ou o `<html>` com `styleScopeProps`)
- `MessagesProvider` definido se o seu app não é em inglês

</Checklist>


# Clay (/pt-br/docs/skins/clay)

<SkinHero id="clay" />

## Como usar [#como-usar]

<SkinUse id="clay" />

## Quando usar [#quando-usar]

<SkinWhen id="clay" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="clay" />

## Componentes em Clay [#componentes-em-clay]

<SkinGallery id="clay" />

## Tokens [#tokens]

<SkinTokens id="clay" />

## Mesma família [#mesma-família]

<SkinFamily id="clay" />


# Comparar lado a lado (/pt-br/docs/skins/compare)

<SkinCompare />


# Cupertino (/pt-br/docs/skins/cupertino)

<SkinHero id="cupertino" />

## Como usar [#como-usar]

<SkinUse id="cupertino" />

## Quando usar [#quando-usar]

<SkinWhen id="cupertino" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="cupertino" />

## Componentes em Cupertino [#componentes-em-cupertino]

<SkinGallery id="cupertino" />

## Tokens [#tokens]

<SkinTokens id="cupertino" />

## Mesma família [#mesma-família]

<SkinFamily id="cupertino" />


# Editorial (/pt-br/docs/skins/editorial)

<SkinHero id="editorial" />

## Como usar [#como-usar]

<SkinUse id="editorial" />

## Quando usar [#quando-usar]

<SkinWhen id="editorial" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="editorial" />

## Componentes em Editorial [#componentes-em-editorial]

<SkinGallery id="editorial" />

## Tokens [#tokens]

<SkinTokens id="editorial" />

## Mesma família [#mesma-família]

<SkinFamily id="editorial" />


# Glass (/pt-br/docs/skins/glass)

<SkinHero id="glass" />

## Como usar [#como-usar]

<SkinUse id="glass" />

## Quando usar [#quando-usar]

<SkinWhen id="glass" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="glass" />

## Componentes em Glass [#componentes-em-glass]

<SkinGallery id="glass" />

## Tokens [#tokens]

<SkinTokens id="glass" />

## Mesma família [#mesma-família]

<SkinFamily id="glass" />


# Todos os 13 estilos (/pt-br/docs/skins)

## Tipográfico [#tipográfico]

<SkinIndex family="typographic" />

## Plataforma [#plataforma]

<SkinIndex family="platform" />

## Profundidade suave [#profundidade-suave]

<SkinIndex family="soft" />

## Ousado [#ousado]

<SkinIndex family="bold" />


# Material (/pt-br/docs/skins/material)

<SkinHero id="material" />

## Como usar [#como-usar]

<SkinUse id="material" />

## Quando usar [#quando-usar]

<SkinWhen id="material" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="material" />

## Componentes em Material [#componentes-em-material]

<SkinGallery id="material" />

## Tokens [#tokens]

<SkinTokens id="material" />

## Mesma família [#mesma-família]

<SkinFamily id="material" />


# Minimal (/pt-br/docs/skins/minimal)

<SkinHero id="minimal" />

## Como usar [#como-usar]

<SkinUse id="minimal" />

## Quando usar [#quando-usar]

<SkinWhen id="minimal" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="minimal" />

## Componentes em Minimal [#componentes-em-minimal]

<SkinGallery id="minimal" />

## Tokens [#tokens]

<SkinTokens id="minimal" />

## Mesma família [#mesma-família]

<SkinFamily id="minimal" />


# Neubrutalism (/pt-br/docs/skins/neubrutalism)

<SkinHero id="neubrutalism" />

## Como usar [#como-usar]

<SkinUse id="neubrutalism" />

## Quando usar [#quando-usar]

<SkinWhen id="neubrutalism" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="neubrutalism" />

## Componentes em Neubrutalism [#componentes-em-neubrutalism]

<SkinGallery id="neubrutalism" />

## Tokens [#tokens]

<SkinTokens id="neubrutalism" />

## Mesma família [#mesma-família]

<SkinFamily id="neubrutalism" />


# Neumorphism (/pt-br/docs/skins/neumorphism)

<SkinHero id="neumorphism" />

## Como usar [#como-usar]

<SkinUse id="neumorphism" />

## Quando usar [#quando-usar]

<SkinWhen id="neumorphism" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="neumorphism" />

## Componentes em Neumorphism [#componentes-em-neumorphism]

<SkinGallery id="neumorphism" />

## Tokens [#tokens]

<SkinTokens id="neumorphism" />

## Mesma família [#mesma-família]

<SkinFamily id="neumorphism" />


# Progressive (/pt-br/docs/skins/progressive)

<SkinHero id="progressive" />

## Como usar [#como-usar]

<SkinUse id="progressive" />

## Quando usar [#quando-usar]

<SkinWhen id="progressive" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="progressive" />

## Componentes em Progressive [#componentes-em-progressive]

<SkinGallery id="progressive" />

## Tokens [#tokens]

<SkinTokens id="progressive" />

## Mesma família [#mesma-família]

<SkinFamily id="progressive" />


# Retro pixel (/pt-br/docs/skins/retro-pixel)

<SkinHero id="retro-pixel" />

## Como usar [#como-usar]

<SkinUse id="retro-pixel" />

## Quando usar [#quando-usar]

<SkinWhen id="retro-pixel" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="retro-pixel" />

## Componentes em Retro pixel [#componentes-em-retro-pixel]

<SkinGallery id="retro-pixel" />

## Tokens [#tokens]

<SkinTokens id="retro-pixel" />

## Mesma família [#mesma-família]

<SkinFamily id="retro-pixel" />


# Retro (/pt-br/docs/skins/retro)

<SkinHero id="retro" />

## Como usar [#como-usar]

<SkinUse id="retro" />

## Quando usar [#quando-usar]

<SkinWhen id="retro" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="retro" />

## Componentes em Retro [#componentes-em-retro]

<SkinGallery id="retro" />

## Tokens [#tokens]

<SkinTokens id="retro" />

## Mesma família [#mesma-família]

<SkinFamily id="retro" />


# Swiss (/pt-br/docs/skins/swiss)

<SkinHero id="swiss" />

## Como usar [#como-usar]

<SkinUse id="swiss" />

## Quando usar [#quando-usar]

<SkinWhen id="swiss" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="swiss" />

## Componentes em Swiss [#componentes-em-swiss]

<SkinGallery id="swiss" />

## Tokens [#tokens]

<SkinTokens id="swiss" />

## Mesma família [#mesma-família]

<SkinFamily id="swiss" />


# Y2K (/pt-br/docs/skins/y2k)

<SkinHero id="y2k" />

## Como usar [#como-usar]

<SkinUse id="y2k" />

## Quando usar [#quando-usar]

<SkinWhen id="y2k" />

## Claro e escuro [#claro-e-escuro]

<SkinModes id="y2k" />

## Componentes em Y2K [#componentes-em-y2k]

<SkinGallery id="y2k" />

## Tokens [#tokens]

<SkinTokens id="y2k" />

## Mesma família [#mesma-família]

<SkinFamily id="y2k" />