@k8ordo/ui 2.0.0 → 2.2.0

package/docs/references/generative-ui.md

@@ -10,10 +10,104 @@ Both are optional peer dependencies — install only the one you use.
 ```bash
 # json-render
 pnpm add @json-render/core @json-render/react zod
-# OpenUI
-pnpm add @openuidev/react-lang zod
-# Add this too if you use OpenUI's server-safe prompt entry:
-pnpm add @openuidev/lang-core
+# OpenUI — both entries import lang-core directly, so install both packages
+pnpm add @openuidev/react-lang @openuidev/lang-core zod
+```
+
+`@openuidev/lang-core` is not optional for OpenUI: `@k8ordo/ui/openui` builds its
+component library with it and `@k8ordo/ui/openui/prompt` is the React-free entry
+on top of it. `@openuidev/react-lang` depends on it as well, but pnpm will not
+let your app resolve a dependency of a dependency — declare it yourself.
+
+json-render is 0.x, where a minor bump is a breaking release, so `@k8ordo/ui`
+declares a range that stops at the next minor; OpenUI is 1.x, and the range
+stops at the next major. The peer table in the package's README
+(`node_modules/@k8ordo/ui/README.md` when installed via npm) lists the current
+range for each package. Pick a version inside it.
+
+Within that range, resolve exactly **one copy** of each framework. The adapters
+read the framework's own React context — `useStateField` for OpenUI,
+`useBoundProp` for json-render — so if your app and `@k8ordo/ui` end up on two
+different copies, the context objects are different objects: every schema check,
+the types, and the build all pass, and the form views throw
+`useOpenUI must be used within a <Renderer /> component.` at render time. With
+pnpm this happens as soon as your version differs from the one `@k8ordo/ui`
+resolves, even when both satisfy the range.
+
+## What the catalog covers
+
+Both adapters register the same components, and the prompts they generate list
+them. Most are the exported component of the same name. A few are shaped for a
+model instead:
+
+- **Icons** are one `Icon` entry whose `name` picks the glyph from a curated
+  set of icons that need nothing but a size. `ChevronIcon` has an entry of its
+  own, and `AlertIcon` is the `StatusIcon` entry.
+- **Toasts** are a `Toast` entry, standing in for `ToastProvider` and
+  `useToast`: a self-contained widget whose `triggerLabel` button shows the
+  toast.
+- **Overlays** (`Modal`, `Dialog`, `Drawer`, `Popover`, `Tooltip`,
+  `DropdownMenu`) are self-contained widgets too. Each declares its own trigger
+  with `triggerLabel` and handles opening and closing itself.
+- **Compound components** (`Tabs`, `Accordion`, `Table`, `Breadcrumb`, …) are
+  one entry each, with their parts flattened into data such as
+  `tabs: [{ label, content }]`. `Carousel` is one container entry whose
+  children are its slides, one child per slide.
+- **Kbd** takes `keys: string[]` and draws the whole shortcut, one key cap per
+  entry, where the component itself is one key.
+
+Every other component the package exports is either in the catalog or in the
+list below, and the package's tests keep it that way.
+
+## What the catalog leaves out
+
+These exports are left out on purpose, so a model cannot place them:
+
+- `ContextMenu` — it opens on a right-click, which nothing on screen invites,
+  so actions put in it would be hidden in a generated UI. It belongs on your
+  application's own content (a file, a row).
+- `InView`, `Resize` — they report to a callback and draw nothing of their own,
+  and a spec has no code to receive the report.
+- `UIProvider` — your application mounts it once, around the generated UI as
+  well.
+- `PortalRootProvider`, `usePortalRoot` — wiring for your own `createPortal`
+  calls. The generated overlays open their own surfaces.
+- `Conversation`, `Message`, `PromptInput`, `Reasoning`, `Suggestion`,
+  `ToolInvocation`, `Attachment`, and `Source` from `@k8ordo/ui/ai`, and
+  `Response` from
+  `@k8ordo/ui/ai/response` — the chat the generated UI is shown in. Your
+  application builds it from its message stream; a spec does not place it.
+- `CodeBlock` from `@k8ordo/ui/code-block` — it highlights on the server, as an
+  async Server Component. The generated UI renders on the client, where it
+  cannot run, and placing it there would ship the highlighter to the browser.
+  `Code` (inline code) is in the catalog.
+- `CommandPalette` — every item runs a function of your application, which a
+  spec cannot write, and it is chrome your application opens from a shortcut
+  rather than something placed in a reply. For actions inside the generated UI,
+  use `Button` or `DropdownMenu`.
+- `ResizablePanels` — it divides a parent of fixed size into a workspace, the
+  frame an application draws around its content. The generated UI flows inside
+  a message and has no height to divide; to set things side by side, use
+  `Grid`.
+- `Prose` — it typesets the bare HTML that Markdown renders to. A spec places
+  components, which keep their own look, so it would have nothing to typeset;
+  lay a flow out with `Stack`.
+- `TableOfContents` — it points at the ids of the document's headings and
+  follows the scroll. The headings a spec places carry no id, so there would be
+  nothing to point at.
+
+## Prompt language
+
+Everything the adapters hand the model — component descriptions, `uiRules`,
+schema descriptions, and the repair prompt — is English, whatever your
+application's locale. The model reads it; your users never see it. To pin the
+language of the text the model writes into the UI, add a rule of your own:
+
+```tsx
+// json-render
+catalog.prompt({ customRules: [...uiRules, 'Write all UI text in Japanese.'] });
+// OpenUI
+prompt({ additionalRules: ['Write all UI text in Japanese.'] });
 ```
 
 ## json-render
@@ -40,13 +134,20 @@ collect form values.
 
 ```tsx
 'use client';
+import type { UISpec } from '@k8ordo/ui/json-render';
 import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';
 
-export function GenUi({ spec }: { spec: unknown }) {
+export function GenUi({ spec }: { spec: UISpec }) {
   return <JsonRenderUI spec={spec} />;
 }
 ```
 
+Props:
+
+- `spec`: `Spec | null` (required; a `UISpec` is assignable to json-render's `Spec` without a cast, and `null` renders nothing)
+- `loading`: boolean (passed to `Renderer`: set it while the spec is still streaming in, so children that have not arrived yet are skipped without a warning)
+- `onStateChange`: `(changes: Array<{ path: string; value: unknown }>) => void` (called once per state update with every changed path and its new value)
+
 For an advanced setup (your own `navigate`, `handlers`, or
 `validationFunctions`), pass the low-level `registry` straight to
 `@json-render/react`'s `JSONUIProvider` / `Renderer`.
@@ -54,9 +155,12 @@ For an advanced setup (your own `navigate`, `handlers`, or
 ### 3. Validate LLM output, then render or repair it
 
 `validateGeneratedSpec` applies mechanical fixes, validates the structure, then
-validates props per component. On failure it returns a repair prompt you can
-send straight back to the LLM. Use it instead of `catalog.validate()`, which
-rejects valid specs in the current upstream version.
+validates props per component. On failure it returns the `issues` it found (each
+a `message`, plus the `elementKey` of the offending element when there is one)
+and a repair prompt built from them that you can send straight back to the LLM.
+Use it instead of `catalog.validate()`, which rejects valid specs in the current
+upstream version. The result and issue types are exported as
+`ValidateGeneratedSpecResult` and `GeneratedSpecIssue`.
 
 ```tsx
 import { validateGeneratedSpec } from '@k8ordo/ui/json-render';
@@ -87,8 +191,9 @@ const spec = {
 } satisfies UISpec;
 ```
 
-`ComponentName` and `ComponentProps<K>` are exported as well, so you can pull
-out the props type of a specific component.
+`UISpecElement` (one element of a `UISpec`), `ComponentName`, and
+`ComponentProps<K>` are exported as well, so you can pull out the props type of a
+specific component.
 
 ## OpenUI
 
@@ -114,10 +219,14 @@ import { prompt } from '@k8ordo/ui/openui/prompt';
 const systemPrompt = prompt(); // No React dependency — callable from RSC or an API route
 ```
 
-In OpenUI a `Stack` or `Grid` cannot sit directly inside another `Stack` or
-`Grid` (self-referential schemas are unsupported). When you need nested layout,
-put the `Stack` / `Grid` inside a `Card`. json-render is slot-based and nests
-freely.
+`prompt` takes an optional `PromptOptions` from `@openuidev/lang-core`
+(`preamble`, `additionalRules`, `examples`, …) and passes it straight through to
+the library's prompt generation.
+
+Containers nest freely in OpenUI, as they do in json-render: `Stack`, `Grid`,
+`Card`, `Form`, `Modal`, `Dialog`, `Drawer`, and `Popover` each list every
+container among their children, so a `Card` can sit inside a `Stack` and a
+`Stack` inside another `Stack`.
 
 ## Exports at a glance
 
@@ -126,8 +235,8 @@ freely.
 | `@k8ordo/ui/json-render`          | server-safe    | `catalog`, `validateGeneratedSpec`, `uiRules`, types (`UISpec`, …) |
 | `@k8ordo/ui/json-render/registry` | `'use client'` | `JsonRenderUI` (pre-wired), `registry` (low level)                 |
 | `@k8ordo/ui/openui`               | `'use client'` | `library` (rendering)                                              |
-| `@k8ordo/ui/openui/prompt`        | server-safe    | `prompt()` (prompt generation)                                     |
+| `@k8ordo/ui/openui/prompt`        | server-safe    | `prompt(options?)` (prompt generation)                             |
 
 > All of them assume you have loaded `@k8ordo/ui/styles.css` (or
-> `@k8ordo/ui/tailwind.css` in a Tailwind CSS 4 project) and wrapped the tree in
-> `UIProvider`.
+> `@k8ordo/ui/tailwind.css` after Tailwind, in a Tailwind CSS 4 project) and
+> wrapped the tree in `UIProvider`.

package/docs/references/interaction-design.md

@@ -6,26 +6,33 @@ Interaction in `@k8ordo/ui` follows one principle: quiet change.
 
 Design with these eight states in mind.
 
-| State    | Style                                                 |
-| -------- | ----------------------------------------------------- |
-| Default  | The base style                                        |
-| Hover    | `hover:bg-bg-mute` — a gentle color shift             |
-| Focus    | `focus-visible:ring-2 focus-visible:ring-border-info` |
-| Active   | `active:bg-bg-emphasize`                              |
-| Disabled | `opacity-50 cursor-not-allowed`                       |
-| Loading  | A spinner or a skeleton                               |
-| Selected | `bg-primary-bg-subtle`                                |
-| Error    | `border-border-error` + `text-fg-error`               |
+| State    | Style                                                     |
+| -------- | --------------------------------------------------------- |
+| Default  | The base style                                            |
+| Hover    | `--color-bg-mute` — a gentle color shift                  |
+| Focus    | `box-shadow: var(--shadow-ring-info)` on `:focus-visible` |
+| Active   | `--color-bg-emphasize`                                    |
+| Disabled | `opacity: 0.5; cursor: not-allowed`                       |
+| Loading  | A spinner or a skeleton                                   |
+| Selected | `--color-primary-bg-subtle`                               |
+| Error    | `--color-border-error` + `--color-fg-error`               |
 
 ## Transitions
 
 Restrained, natural motion.
 
-| Purpose                        | Recommended setting                        |
-| ------------------------------ | ------------------------------------------ |
-| Hover color change             | `transition-colors duration-150 ease-out`  |
-| Opacity change                 | `transition-opacity duration-200 ease-out` |
-| When size changes are involved | `transition-all duration-150 ease-out`     |
+| Purpose                        | Recommended setting                                      |
+| ------------------------------ | -------------------------------------------------------- |
+| Hover color change             | the colors over `--duration-fast` with `--easing-out`    |
+| Opacity change                 | `opacity` over `--duration-moderate` with `--easing-out` |
+| When size changes are involved | the changing properties over `--duration-fast`           |
+| A page or a panel replaced     | `<ViewTransition>` — the browser's cross-fade            |
+
+`--duration-fast` is 150ms, `--duration-moderate` 200ms and `--duration-slow`
+300ms. `--easing-out` and `--easing-in-out` are Tailwind's curves
+(`cubic-bezier(0, 0, 0.2, 1)` and `cubic-bezier(0.4, 0, 0.2, 1)`), not the CSS
+keywords of the same name. With `tailwind.css`: `transition-colors
+duration-150 ease-out`.
 
 ### Timing principles
 
@@ -36,32 +43,54 @@ Restrained, natural motion.
 
 ### Choosing an animation
 
-```tsx
-// Good: transition-colors (only the color changes)
-className = 'transition-colors hover:bg-bg-mute';
-
-// OK: transition-all (only when several properties change)
-className = 'transition-all hover:bg-bg-mute hover:scale-[1.02]';
-
-// Bad: bounce or spring easing
-className = 'animate-bounce';
+```css
+/* Good: transition only the colors that change */
+.item {
+  transition-property: color, background-color;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: var(--easing-out);
+}
+
+@media (hover: hover) {
+  .item:hover {
+    background-color: var(--color-bg-mute);
+  }
+}
+
+/* OK: list every property when several change */
+.card {
+  transition-property: background-color, scale;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: var(--easing-out);
+}
+
+/* Bad: bounce or spring easing */
 ```
 
 ## Focus management
 
-- Use `focus-visible`, not `focus` — no ring appears on a mouse click
-- Keep the focus ring consistent with `ring-border-info`
-- Clear the default outline with `outline-hidden` before applying the ring
-
-```tsx
-className =
-  'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-border-info';
+- Use `:focus-visible`, not `:focus` — no ring appears on a mouse click
+- Keep the focus ring consistent with `--shadow-ring-info`
+- Clear the default outline before applying the ring, and give it back under forced colors, where the ring (a shadow) disappears
+- Keep focus on a button that is waiting on its own action: show the wait with `aria-busy` and `aria-disabled` and ignore presses, rather than setting `disabled`. Chromium moves focus to `body` when the focused element becomes disabled, so the keyboard user who pressed it loses their place. `Button` and `IconButton` do this for `onAction`
+- For the same reason, a text field whose form's action is pending turns `readOnly`, not `disabled`, and ignores the keys that would change its value, so the user who pressed Enter in it keeps their place. `TextField`, `Textarea`, `PasswordInput`, `NumberField`, `DateField`, `DatePicker`, `ColorPicker`, `Combobox`, and `Autocomplete` do this. `readOnly` does not apply to a checkbox, radio, range, or select, yet Enter in one still submits the form through its submit button, so `Checkbox`, `Radio`, `Switch`, `Slider`, `RangeSlider`, and `Select` take `aria-disabled` instead and ignore what would change their value. A checkbox or radio cancels the click in the capture phase and stops it there: cancelled any later, React's change tracking has already recorded the toggle the browser then undoes, calls `onChange` for it, and misses the next real one. A range ignores the arrow, Home, End, and Page keys and the pointer; a select ignores those keys, Space, F4, typed characters, and the pointer
+
+```css
+.control:focus-visible {
+  outline-style: none;
+  box-shadow: var(--shadow-ring-info);
+
+  @media (forced-colors: active) {
+    outline: 2px solid transparent;
+    outline-offset: 2px;
+  }
+}
 ```
 
 ## Form design
 
 - Put the label above the input (a left-aligned label reads badly in Japanese)
-- Put the error message directly under the input, as `text-fg-error text-sm`
+- Put the error message directly under the input, in `--color-fg-error` at `--font-size-sm`
 - Mark required fields with `*` after the label
 - Validate on submit; keep real-time validation to a minimum
 - Use the `FormControl` component so labels and errors stay consistent
@@ -83,13 +112,14 @@ import { FormControl, TextField } from '@k8ordo/ui';
 
 - Set `aria-label` / `aria-describedby` where they belong
 - Guarantee keyboard navigation (Tab, Enter, Escape, arrow keys)
-- Respect `prefers-reduced-motion` — the motion library handles it for you
+- Respect `prefers-reduced-motion`. Under it the stylesheet turns off the open animation of Popover and what is built on it (DropdownMenu, ListBox, Tooltip), the Toast, Modal, and Drawer animations, the Tabs indicator slide, and every view transition; `Card`'s hover scale runs only under `prefers-reduced-motion: no-preference`. Skeleton's pulse, Spinner's spin, and the Accordion chevron, Switch thumb, and Progress bar transitions keep running. Put your own motion under `@media (prefers-reduced-motion: no-preference)`
 - Never signal state with color alone; pair it with an icon or text
+- The components follow `prefers-contrast: more` and stay legible under `forced-colors: active` (see [High contrast and forced colors](./color.md#high-contrast-and-forced-colors)); do the same in your own UI
 
 ## What not to do
 
 - Bounce or spring easing
 - Animation longer than 300ms
-- A strong primary color (`bg-primary-bg`) on hover
-- `cursor-pointer` on anything that is not a button (links do not need it either)
+- A strong primary color (`--color-primary-bg`) on hover
+- `cursor: pointer` on anything that is not a button (links do not need it either)
 - A submit button with no double-click guard

package/docs/references/spatial-design.md

@@ -5,32 +5,34 @@ leave room.
 
 ## Spacing principles
 
-A 4pt spacing system, using Tailwind's standard scale.
+A 4pt spacing system: one token, `--spacing` (0.25rem), multiplied by the step
+you want — `calc(var(--spacing) * 6)` is 1.5rem. With `tailwind.css`, the
+step is the utility's number (`p-6`, `gap-8`).
 
 ### Padding inside a component
 
-| Use               | Class  | Value |
-| ----------------- | ------ | ----- |
-| Compact           | `p-4`  | 16px  |
-| Standard          | `p-6`  | 24px  |
-| Generous          | `p-8`  | 32px  |
-| Inside a big card | `p-10` | 40px  |
+| Use               | Step | Value |
+| ----------------- | ---- | ----- |
+| Compact           | 4    | 16px  |
+| Standard          | 6    | 24px  |
+| Generous          | 8    | 32px  |
+| Inside a big card | 10   | 40px  |
 
 ### Spacing between blocks of text
 
-| Relationship           | Class   | Use                                     |
-| ---------------------- | ------- | --------------------------------------- |
-| Closely related        | `mt-2`  | Descriptions, help text                 |
-| Standard               | `mt-4`  | Between paragraphs, between form fields |
-| Between sections       | `mt-8`  | A section break                         |
-| Between major sections | `mt-12` | A page-level break                      |
+| Relationship           | Step | Use                                     |
+| ---------------------- | ---- | --------------------------------------- |
+| Closely related        | 2    | Descriptions, help text                 |
+| Standard               | 4    | Between paragraphs, between form fields |
+| Between sections       | 8    | A section break                         |
+| Between major sections | 12   | A page-level break                      |
 
 ### Spacing between sections
 
-| Relationship     | Class              | Use                            |
-| ---------------- | ------------------ | ------------------------------ |
-| Between cards    | `gap-6`            | Cards side by side (in a grid) |
-| Between sections | `gap-8` – `gap-10` | Sections stacked vertically    |
+| Relationship     | Step   | Use                            |
+| ---------------- | ------ | ------------------------------ |
+| Between cards    | 6      | Cards side by side (in a grid) |
+| Between sections | 8 – 10 | Sections stacked vertically    |
 
 ## Border radius
 
@@ -40,74 +42,92 @@ Vary the radius with the element's role.
 
 ### Things you touch (soft)
 
-| Use                           | Class          | Value |
-| ----------------------------- | -------------- | ----- |
-| Button                        | `rounded-full` | Pill  |
-| Input, Textarea, Select       | `rounded-xl`   | 1rem  |
-| Card, CheckboxCard, RadioCard | `rounded-xl`   | 1rem  |
+| Use                           | Token           | Value |
+| ----------------------------- | --------------- | ----- |
+| Button                        | `--radius-full` | Pill  |
+| Input, Textarea, Select       | `--radius-xl`   | 1rem  |
+| Card, CheckboxCard, RadioCard | `--radius-xl`   | 1rem  |
 
 ### Things you read (precise)
 
-| Use      | Class          | Value                          |
-| -------- | -------------- | ------------------------------ |
-| Alert    | `rounded-lg`   | 0.75rem                        |
-| Badge    | `rounded-full` | Pill (fine, since it is small) |
-| Tabs     | As-is          |                                |
-| Checkbox | `rounded-md`   | 0.5rem                         |
+| Use      | Token           | Value                          |
+| -------- | --------------- | ------------------------------ |
+| Alert    | `--radius-lg`   | 0.75rem                        |
+| Callout  | `--radius-lg`   | 0.75rem                        |
+| Badge    | `--radius-full` | Pill (fine, since it is small) |
+| Tabs     | As-is           |                                |
+| Checkbox | `--radius-md`   | 0.5rem                         |
 
 ### Everything else
 
-| Use                              | Class          |
-| -------------------------------- | -------------- |
-| Dialog, Modal                    | `rounded-lg`   |
-| Avatar, IconButton, progress bar | `rounded-full` |
+| Use                              | Token           |
+| -------------------------------- | --------------- |
+| Dialog, Modal                    | `--radius-lg`   |
+| Avatar, IconButton, progress bar | `--radius-full` |
+
+With `tailwind.css` these are `rounded-full`, `rounded-xl`, … .
 
 ## Shadow
 
 Express depth with a soft, gentle shadow.
 
-| Use                      | Style                                                      |
-| ------------------------ | ---------------------------------------------------------- |
-| Card (default)           | `shadow-sm` (with `appearance="shadow"`)                   |
-| Card (bordered)          | `border border-border-mute` (with `appearance="bordered"`) |
-| Modal / Dialog / Tooltip | `shadow-md`                                                |
-| Dropdown / ListBox       | `shadow-md`                                                |
-| Button                   | None                                                       |
+| Use                      | Style                                                    |
+| ------------------------ | -------------------------------------------------------- |
+| Card (default)           | `--shadow-sm` (with `variant="shadow"`)                  |
+| Card (outlined)          | a 1px `--color-border-mute` border (`variant="outline"`) |
+| Modal / Dialog / Tooltip | `--shadow-md`                                            |
+| Dropdown / ListBox       | `--shadow-md`                                            |
+| Button                   | None                                                     |
 
-Never use `shadow-xl` or heavier.
+Never use `--shadow-xl` or heavier. The focus ring is a shadow too,
+`--shadow-ring-info`; with a surface's own shadow, list the ring first:
+`box-shadow: var(--shadow-ring-info), var(--shadow-xs)`.
 
 ## Page structure
 
 ### The bg-subtle plus white card pattern
 
-Make the page background `bg-bg-subtle` (a light grey) and float the content on
-white cards.
+Make the page background `--color-bg-subtle` (a light grey) and float the
+content on white cards.
+
+```css
+.page {
+  min-height: 100vh;
+  background-color: var(--color-bg-subtle);
+}
+
+.body {
+  padding: calc(var(--spacing) * 6);
+}
+```
 
 ```tsx
 // Good: a white card floating on a grey ground
-<div className="bg-bg-subtle min-h-screen">
-  <Card appearance="shadow">
-    <div className="p-8">Content</div>
+<div className={styles.page}>
+  <Card variant="shadow">
+    <div className={styles.body}>Content</div>
   </Card>
 </div>
 ```
 
 ### Build hierarchy out of spacing
 
-```tsx
-// Good: the size of the gap shows how related things are
-<section className="mt-12">
-  <Heading level="h2">Section</Heading>
-  <p className="mt-2">A description that belongs to it</p>
-  <div className="mt-8">Content that sits a little apart</div>
-</section>
-
-// Bad: the same gap everywhere
-<section className="mt-4">
-  <Heading level="h2">Section</Heading>
-  <p className="mt-4">Description</p>
-  <div className="mt-4">Content</div>
-</section>
+Let the size of the gap show how related things are: 12 steps above a
+section, 2 between a heading and the description that belongs to it, 8 before
+content that sits a little apart. The same gap everywhere flattens the page.
+
+```css
+.section {
+  margin-top: calc(var(--spacing) * 12);
+}
+
+.description {
+  margin-top: calc(var(--spacing) * 2);
+}
+
+.content {
+  margin-top: calc(var(--spacing) * 8);
+}
 ```
 
 ### A card is not the answer to everything
@@ -117,10 +137,10 @@ Content does not have to go in a card. Spacing and a separator are often enough.
 ```tsx
 import { Separator } from '@k8ordo/ui';
 
-// Good: divide with a separator
+// Good: divide with a separator (.divider { padding-block: calc(var(--spacing) * 8); })
 <div>
   <section>Content A</section>
-  <div className="py-8">
+  <div className={styles.divider}>
     <Separator />
   </div>
   <section>Content B</section>
@@ -133,7 +153,7 @@ import { Separator } from '@k8ordo/ui';
 
 ## What not to do
 
-- Extremely tight spacing such as `gap-1` or `p-1`
+- Extremely tight spacing such as one step (`calc(var(--spacing) * 1)`)
 - Cramming content in (space wins over information density)
 - Nested cards (Card in Card)
-- A z-index above 12
+- A z-index of your own: stack with `--z-index-raised` (inside a component), `--z-index-overlay`, `--z-index-modal` and `--z-index-toast`

package/docs/references/types.md

@@ -0,0 +1,101 @@
+# Types
+
+The shared types `@k8ordo/ui` exports for typing component props.
+
+```tsx
+import type {
+  Direction,
+  DrawerSide,
+  ModalSide,
+  Option,
+  Placement,
+  Status,
+} from '@k8ordo/ui';
+```
+
+## Status
+
+```tsx
+type Status = 'success' | 'info' | 'warning' | 'error';
+```
+
+Used for the status of `Alert`, `Callout`, `Toast`, and `AlertIcon`. `Badge` takes its own `tone`, which also allows `'neutral'`.
+
+## Direction
+
+```tsx
+type Direction = 'up' | 'down' | 'right' | 'left';
+```
+
+Used to point ChevronIcon and similar icons.
+
+## Placement
+
+```tsx
+type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
+```
+
+Placement relative to an anchor element, for Popover, Tooltip, DropdownMenu,
+and ListBox (the `placement` prop), and for IconButton's tooltip
+(`tooltipPlacement`).
+
+## ModalSide
+
+```tsx
+type ModalSide = 'center' | 'bottom' | 'left' | 'right';
+```
+
+Which viewport edge a Modal sticks to (the `side` prop). It is a different
+idea from `Placement`, which is relative to an anchor, so the prop name differs
+too.
+
+## DrawerSide
+
+```tsx
+type DrawerSide = Extract<ModalSide, 'left' | 'right'>;
+```
+
+The subset of `ModalSide` a Drawer accepts: a drawer always slides in from an
+edge, so `center` is excluded.
+
+## Option
+
+```tsx
+type Option = Readonly<{ value: string; label: string }>;
+```
+
+Used for the choices in Radio, Select, Autocomplete, and similar components.
+
+## Component prop types
+
+The root also exports types that belong to one component, for typing your own
+code around it:
+
+| Type                                                                  | What it types                                                                                           |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `StackProps` / `GridProps`                                            | Every prop of `Stack` / `Grid`, for a component that wraps one                                          |
+| `GapSize` / `PaddingSize`                                             | The `none`–`xl` scale of `gap` (Stack, Grid) and `padding` (Stack)                                      |
+| `ButtonRenderItemProps` / `IconButtonRenderItemProps`                 | What `renderItem` receives on `Button` / `IconButton`                                                   |
+| `IconButtonTriggerProps`                                              | `Partial<TooltipTriggerProps>`: the tooltip wiring in `IconButtonRenderItemProps`' `triggerProps`       |
+| `PopoverTriggerProps` / `PopoverContentProps` / `TooltipTriggerProps` | What `renderItem` receives on `Popover.Trigger` / `Popover.Content` / `Tooltip.Trigger`                 |
+| `ToolbarItemProps`                                                    | What `renderItem` receives on `Toolbar.Item`: `ref`, `tabIndex`, `onFocus`                              |
+| `CommandPaletteItem`                                                  | A command in `CommandPalette`: `id`, `label`, `onSelect`, plus `group`, `keywords`, `shortcut`          |
+| `AlertAction` / `ToastAction` / `ToastOptions`                        | `Alert`'s `action`, and the `action` and `duration` a toast takes                                       |
+| `ColorPickerSwatch`                                                   | A preset in `ColorPicker`'s `swatches`: `value` (`#rrggbb`) and `label`, the color's name               |
+| `ComboboxSearch`                                                      | `Combobox`'s `search`: `(query, { signal }) => Promise<readonly Option[]>`                              |
+| `CheckboxCardOption` / `RadioCardOption`                              | A choice in `CheckboxCard` / `RadioCard`: `value` and `label`, plus `description`, `visual`, `disabled` |
+| `StepperStep`                                                         | A step in `Stepper`: `label`, plus `description`                                                        |
+| `CellAlign`                                                           | A table cell's `align`: `'left'`, `'center'`, or `'right'`                                              |
+| `BaseIconProps` / `IconRenderProps`                                   | An icon's `size`, and the props an icon puts on its `<svg>`                                             |