@zyncat/ui 0.11.0 → 0.13.0

package/skills/zyncat-ui/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: zyncat-ui
+description: Use when writing or reviewing React code in a project that uses @zyncat/ui - picking which component fits a job, rendering or composing components, styling/theming them, or debugging their behavior. Load BEFORE importing or rendering any @zyncat/ui component.
+---
+
+# Building with @zyncat/ui
+
+React 19 design system: accessible, animated components on a closed CSS token vocabulary.
+No Tailwind, no CSS-in-JS, no animation library - a built-in WAAPI motion engine drives everything.
+
+## The contract
+
+1. **Never write a component's props from memory or from this skill.** Before writing any JSX that
+   renders a Zyncat UI component, call the `get_component` MCP tool with EVERY component the change
+   touches, in one call: `get_component(["select", "text-field", "dialog"])`. It returns the
+   maintainers' usage notes, the live docs URL and the complete prop types for the version actually
+   installed. An unknown name returns the full catalog, so a wrong guess self-corrects.
+2. Unsure which component owns a behavior? `search_api("drag dismiss")` - ranked, and a miss
+   returns the catalog.
+3. Styling or theming? Read [references/theming.md](references/theming.md) first, then `get_tokens`
+   for the real values.
+4. Full component inventory: [references/components.md](references/components.md) - generated, and
+   stamped with the version it came from. If `node_modules/@zyncat/ui/package.json` shows a
+   different version, trust `get_component` over the file and re-run `npx zyncat-ui init`.
+5. If the MCP tools are missing, register the server and reinstall this skill: `npx zyncat-ui init`
+   (one command: installs the package if absent, imports the stylesheet, writes `.mcp.json`,
+   `.claude/skills/` and the theme scaffold).
+
+## Setup (once per app)
+
+Everything here is what `npx zyncat-ui init` wires up - when a piece is missing, prefer re-running
+init over hand-wiring it.
+
+- `import '@zyncat/ui/styles.css'` once at the root - fonts + tokens; each component lazy-loads its
+  own CSS.
+- Theming: `defineTheme` + `<ZyncatTheme theme={{ base, dark }} />` from `@zyncat/ui/theme`, once at
+  the root. Typed, server-rendered, no build config. See references/theming.md before writing one.
+- One subpath per component: `import { Button } from '@zyncat/ui/button'`. There is no barrel.
+- Peers: react and react-dom 19. Ships built ESM with `'use client'` intact - no bundler or
+  transpile config, works as-is in the Next.js App Router.
+- Icons: the library bundles its own internal glyphs but exports NO Icon component. Every
+  icon-shaped prop or slot takes YOUR ReactNode (e.g. an `@phosphor-icons/react` element).
+
+## Picking the component
+
+The catalog is 9 groups (~50 components): primitives, forms, data display, date/time & tabs,
+overlays & feedback, expressive, compound, replicas, dev tools. The full index is in
+[references/components.md](references/components.md). The choices agents get wrong:
+
+| Job                                              | Use                                                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| Standard modal: title, body, actions             | **Dialog** - the default choice for modals                                                         |
+| Modality with zero chrome (lightbox, full-bleed) | **Modal** - you supply the surface AND role="dialog"                                               |
+| Edge-docked panel, drag-to-dismiss               | **Sheet**                                                                                          |
+| Anchored non-modal panel                         | **Popover**                                                                                        |
+| Menu of actions on a trigger                     | **Dropdown** - commands only, never holds a value                                                  |
+| Pick one value from options                      | **Select** (or **RadioGroup** when all options should be visible)                                  |
+| Pick many values                                 | **MultiSelect** (form value) / **ToggleTag** (filter chips)                                        |
+| Transient hint on hover/focus                    | **Tooltip**                                                                                        |
+| Persistent in-flow status                        | **Alert**                                                                                          |
+| Transient notification                           | **toast()** - needs `<Toaster />` mounted once                                                     |
+| Ambient status chip                              | **Badge** / **StatusBadge** (canonical post status)                                                |
+| User-owned removable label                       | **Tag**                                                                                            |
+| Rolling number                                   | **CountBadge roll** (inline) / **Odometer** (display size)                                         |
+| Persistent support entry point                   | **SupportRail** (edge tab)                                                                         |
+| Social post mock                                 | **InstagramFeed / FacebookFeed / TikTok / YouTube** - pixel-pinned replicas, unthemeable by design |
+
+## Conventions the system assumes
+
+- Sentence case everywhere; no emoji or exclamation marks in UI copy.
+- Exactly one primary `<Button>` per view.
+- Numbers, times, IDs and status read mono + tabular.
+- Status hues (info/success/warning/danger) only for genuine status; hierarchy comes from the
+  neutral ramp.
+
+## Pitfalls that bite
+
+- `toast()` silently no-ops until `<Toaster />` is mounted once at the app root.
+- `EmojiPickerPanel` throws unless `loadEmojiData(...)` ran before first open; `getEmojiUrl` is
+  required.
+- Overlays (Dialog, Modal, Sheet, Popover, Tooltip, Dropdown) take no `className` - pass
+  `htmlProps={{ className }}` to reach the panel.
+- `Modal` renders zero semantics - you render `role="dialog"` plus a label yourself.
+- `Collapse`'s `animation` takes motion TOKENS only (`fast|base|slow|...`), never millisecond
+  values.
+- Replicas pin platform metrics as constants - tokens cannot move them, on purpose.
+- Every component's docs page is live at the `Docs:` URL `get_component` returns
+  (`https://ui.zyncat.app/<slug>`) - open or screenshot it to see the component rendered.
+
+## References
+
+- [references/components.md](references/components.md) - the generated component index
+- [references/theming.md](references/theming.md) - the four override levels + token vocabulary
+- [references/recipes.md](references/recipes.md) - assembled patterns: forms, tables, confirm
+  flows, notifications, drawers

package/skills/zyncat-ui/references/components.md

@@ -0,0 +1,85 @@
+# @zyncat/ui component index
+
+Generated from @zyncat/ui v0.13.0 by `pnpm sync:skill` - do not edit by hand.
+If node_modules/@zyncat/ui/package.json shows a DIFFERENT version, this index is stale:
+trust the get_component MCP tool and re-run `npx zyncat-ui init` to refresh the skill.
+
+This is an index, not the API - prop lists here are incomplete by design.
+Call get_component (it accepts a list) before writing any JSX.
+
+== Primitives ==
+Button - @zyncat/ui/button - One control for every click; exactly one primary per view.
+Collapse - @zyncat/ui/collapse - Layout-transition primitive; eases height open/closed, never teleports.
+Badge - @zyncat/ui/badge - Glass or outline chip for ambient status - toned, dotted, live or pill.
+StatusBadge - @zyncat/ui/status-badge - Canonical post status - tone + one-word label.
+CountBadge - @zyncat/ui/count-badge - Mono tabular count; `roll` animates digits like an odometer.
+Glide / GlidePill - @zyncat/ui/glide - A persistent background pill that glides smoothly between hovered/active elements.
+
+== Forms ==
+Every form field takes label, helper/error/warning/success, size sm|md|lg, disabled.
+TextField - @zyncat/ui/text-field - Base text input; states disclose via Collapse.
+NumberField - @zyncat/ui/number-field - Tabular figures, caret steppers, unit suffix, clamp to [min,max].
+OtpField - @zyncat/ui/otp-field - Segmented one-time code; auto-advance, paste-to-fill.
+Textarea - @zyncat/ui/textarea - Auto-grow, char meter (max), ⌘/Ctrl+↵ submit (onSubmit).
+Checkbox - @zyncat/ui/checkbox - Stages a choice the form commits later - pick Toggle when the effect is immediate.
+Toggle - @zyncat/ui/toggle - Actuates a setting on the spot - pick Checkbox when the form commits the choice later.
+RadioGroup - @zyncat/ui/radio-group - Pick exactly one from options that stay visible - rows or cards; pick Select for long lists.
+Select - @zyncat/ui/select - Single-select listbox in a popover, searchable; holds value: string | null.
+MultiSelect - @zyncat/ui/multi-select - Many-of listbox; stays open while toggling, trigger summarises as first +N.
+
+== Data display ==
+Avatar - @zyncat/ui/avatar - Identity mark: image, initials, or silhouette.
+AvatarGroup - @zyncat/ui/avatar-group - Overlapping avatars with +N overflow.
+Tag / TagGroup - @zyncat/ui/tag - User-owned label (a control, not a status).
+ToggleTag - @zyncat/ui/toggle-tag - Many-of-many filter chip.
+Table - @zyncat/ui/table - Declare columns + rows; owns sort, selection, stickiness, overflow.
+Pagination - @zyncat/ui/pagination - Cursor strip: mono range readout + prev/next pair.
+
+== Date, time & tabs ==
+The date and time fields share: value is a string, onChange(value | null), timezone, min/max, disabled.
+DateField - @zyncat/ui/date-field - Month calendar in a popover; value 'YYYY-MM-DD'.
+DateTimeField - @zyncat/ui/datetime-field - Calendar + segmented HH:MM; value 'YYYY-MM-DDTHH:mm'.
+DateRangeField - @zyncat/ui/date-range-field - Two-tap auto-ordering window; value DateRange { start, end } | null; commits when both ends exist.
+TimeField - @zyncat/ui/time-field - Standalone segmented time; value 'HH:mm'; bounds saturate.
+Tabs / TabPanel - @zyncat/ui/tabs - Line tabs; the ink reaches then releases; panels enter from the side you moved toward.
+
+== Overlays & feedback ==
+Dropdown - @zyncat/ui/dropdown - Menu button - a list of ACTIONS the trigger commits, with submenus.
+Popover - @zyncat/ui/popover - Headless anchored panel, non-modal.
+Sheet - @zyncat/ui/sheet - Edge-docked modal panel, drag-to-dismiss.
+Dialog - @zyncat/ui/dialog - DEFAULT CHOICE for modals - the styled surface: header (icon/title/description/close), scrolling body, footer actions, on top of scrim + focus trap + scroll lock.
+Modal - @zyncat/ui/modal - The SAME modality as Dialog (scrim, focus trap, scroll lock, inert, Esc, motion) with ZERO paint - no header, no body padding, no width cap, no border/radius/shadow.
+Tooltip - @zyncat/ui/tooltip - Transient hint on hover/focus; wraps any child (no ref wiring needed).
+Alert - @zyncat/ui/alert - Persistent, in-flow status.
+Toast - @zyncat/ui/toast - Imperative transient notifications: mount <Toaster /> once at the app root, then call toast() from anywhere.
+toast-store - @zyncat/ui/toast-store - The headless store behind Toast: subscribe to the toast queue and drive it without rendering <Toaster />.
+EmojiPickerPanel - @zyncat/ui/emoji-picker - Searchable emoji panel - grid, scrollspy category rail, recents in localStorage - living in a Popover, becoming a bottom Sheet on narrow viewports.
+
+== Expressive ==
+Creative motion components. Each publishes scoped --<component>-* custom properties as its theming surface.
+Odometer - @zyncat/ui/odometer - Rolling number display for display-size figures - each digit column springs on its own.
+TypingLines - @zyncat/ui/typing-lines - A single line that types itself, holds, deletes, then moves to the next one and repeats.
+Lens - @zyncat/ui/lens - An optical loupe that magnifies whatever you wrap.
+Confetti - @zyncat/ui/confetti - A canvas particle burst you fire yourself: paper flakes, curls, ribbons and foil sequins tumbling on real drag, lift and flip, across three depth layers.
+FlowField - @zyncat/ui/flow-field - A canvas field of needles that breathe on a noise loop, then swing away from the pointer with per-cell lag - a decorative backdrop for a hero or a card.
+MorphingText - @zyncat/ui/morphing-text - A headline that cycles a word list, morphing each word into the next.
+WeightField - @zyncat/ui/weight-field - A display headline where hovering one letter ramps its variable-font wght to the peak and its two neighbours either side part-way, so weight spills outward from the cursor.
+
+== Compound ==
+Whole assembled patterns on the expressive contract - scoped --support-rail-* properties, no tone/corner/density enums. Actions are a SupportAction[]: id, label, icon, meta, description, onSelect.
+SupportRail - @zyncat/ui/support-rail - An edge tab that grows a support panel out of its own measured box.
+
+== Replicas ==
+Each reproduces an external platform surface; fidelity is the contract. Platform metrics are pinned constants - only --font-sans, --focus-ring and the duration tokens are read, so your theme cannot move them. None ever fetches media or autoplays: media and avatar take a URL string or your own node, with CSS-only placeholders.
+FacebookFeed - @zyncat/ui/facebook-feed - Replica of Facebook's three post surfaces, pinned to the platform's real metrics: the feed card, the reels stage and the story stage.
+InstagramFeed - @zyncat/ui/instagram-feed - A replica of one Instagram feed post, pixel-pinned to the platform and immune to your theme.
+TikTok - @zyncat/ui/tiktok - A replica of TikTok's post surface: pick surface="desktop" for the 1584x912 web player with the photo carousel, or surface="mobile" for the 452x822 mobile-web viewport.
+YouTube - @zyncat/ui/youtube - Replica of three YouTube surfaces, picked with surface: a feed grid card (video), a Shorts player with its action rail (short), or a community post (post).
+
+== Dev tools ==
+motion-tokens - @zyncat/ui/motion-tokens - TypeScript readers for the motion token vocabulary - duration/ease/distance/scale token names resolved to the live CSS values.
+MotionDevtools - @zyncat/ui/motion-devtools - Dev-only floating panel that slows or freezes EVERY animation at once (CSS and WAAPI) for motion debugging.
+Theme - @zyncat/ui/theme - Typed theming - defineTheme groups every token with autocomplete and hover docs; ZyncatTheme renders the themes as unlayered CSS above the library layers, with no build step.
+
+== Types-only modules (documented by their .d.ts alone) ==
+@zyncat/ui/next - get_component("next")

package/skills/zyncat-ui/references/recipes.md

@@ -0,0 +1,171 @@
+# Recipes - assembled @zyncat/ui patterns
+
+Templates, not truth: they show which components compose and how state flows between them.
+Before shipping one, run `get_component` on the parts you use - props here are the common subset,
+not the full API of your installed version.
+
+## Settings form
+
+TextField + Select + Toggle + Button, submitted with a loading state and a toast.
+
+```tsx
+import { Button } from '@zyncat/ui/button';
+import { Select } from '@zyncat/ui/select';
+import { TextField } from '@zyncat/ui/text-field';
+import { toast } from '@zyncat/ui/toast';
+import { Toggle } from '@zyncat/ui/toggle';
+
+function WorkspaceSettings() {
+  const [name, setName] = useState('');
+  const [tz, setTz] = useState<string | null>(null);
+  const [autosave, setAutosave] = useState(true);
+  const [saving, setSaving] = useState(false);
+
+  const save = async () => {
+    setSaving(true);
+    try {
+      await api.save({ name, tz, autosave });
+      toast.success('Settings saved');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        save();
+      }}
+    >
+      <TextField id="ws" label="Workspace name" required value={name} onChange={(e) => setName(e.target.value)} />
+      <Select
+        options={TIMEZONES}
+        value={tz}
+        onChange={setTz}
+        searchable
+        placeholder="Choose a time zone"
+        ariaLabel="Time zone"
+      />
+      <Toggle label="Auto-save drafts" checked={autosave} onChange={(e) => setAutosave(e.target.checked)} />
+      <Button type="submit" loading={saving}>
+        Save changes
+      </Button>
+    </form>
+  );
+}
+```
+
+## Data table page
+
+ToggleTag filters above a sortable Table, a Pagination cursor strip below.
+
+```tsx
+import { Pagination } from '@zyncat/ui/pagination';
+import { Table } from '@zyncat/ui/table';
+import { ToggleTag } from '@zyncat/ui/toggle-tag';
+
+<ToggleTag selected={onlyFailed} onChange={setOnlyFailed} count={counts.failed}>Failed</ToggleTag>
+<Table<Invoice>
+  ariaLabel="Invoices"
+  columns={COLUMNS}
+  rows={page.rows}
+  selectable
+  defaultSort={{ key: 'amount', dir: 'desc' }}
+/>
+<Pagination ariaLabel="Rows" range={[page.from, page.to]} total={page.total}
+  hasPrev={page.from > 1} hasNext={page.to < page.total} onPrev={prev} onNext={next} />
+```
+
+## Destructive confirm
+
+Dialog owns the modality; the danger action lives in its footer and reports back with a toast.
+
+```tsx
+import { Button } from '@zyncat/ui/button';
+import { Dialog } from '@zyncat/ui/dialog';
+import { toast } from '@zyncat/ui/toast';
+
+<Dialog
+  open={confirming}
+  onOpenChange={setConfirming}
+  tone="danger"
+  title="Delete this project?"
+  description="Every scheduled post in it is deleted with it."
+  footer={(close) => (
+    <>
+      <Button variant="secondary" onClick={close}>
+        Cancel
+      </Button>
+      <Button
+        variant="danger"
+        onClick={async () => {
+          await api.remove(id);
+          close();
+          toast.success('Project deleted');
+        }}
+      >
+        Delete project
+      </Button>
+    </>
+  )}
+>
+  This cannot be undone.
+</Dialog>;
+```
+
+## App-wide notifications
+
+Mount `<Toaster />` once at the root; every module calls `toast()` - without the mount it no-ops.
+
+```tsx
+import { toast, Toaster } from '@zyncat/ui/toast';
+
+// root layout, once:
+<Toaster position="bottom-right" />;
+
+// anywhere else:
+toast.promise(publish(), {
+  loading: 'Publishing...',
+  success: (r) => `Published to ${r.count} channels`,
+  error: (e) => `Publish failed - ${e.message}`,
+});
+```
+
+## Detail drawer
+
+Sheet for an edge-docked record view; you own the panel's semantics.
+
+```tsx
+import { Sheet } from '@zyncat/ui/sheet';
+
+<Sheet side="right" open={!!selected} onOpenChange={(o) => !o && setSelected(null)}>
+  <div role="dialog" aria-label="Invoice details">
+    {selected && <InvoiceDetails id={selected} />}
+  </div>
+</Sheet>;
+```
+
+## Row actions menu
+
+Dropdown runs commands - it never holds a value; pair it with an icon Button trigger.
+
+```tsx
+import { Button } from '@zyncat/ui/button';
+import { Dropdown } from '@zyncat/ui/dropdown';
+
+<Dropdown
+  ariaLabel="Row actions"
+  trigger={
+    <Button size="icon" variant="ghost" aria-label="Actions">
+      …
+    </Button>
+  }
+  onSelect={(id) => run(id)}
+  items={[
+    { id: 'rename', label: 'Rename' },
+    { id: 'move', label: 'Move to', items: [{ id: 'drafts', label: 'Drafts' }] },
+    { id: 'delete', label: 'Delete', danger: true },
+  ]}
+/>;
+```

package/skills/zyncat-ui/references/theming.md

@@ -0,0 +1,83 @@
+# Theming @zyncat/ui - the four override levels
+
+Load your own stylesheet after `@zyncat/ui/styles.css`, then reach for the LOWEST level that does
+the job. Never fork the source. The `get_tokens` MCP tool prints the whole vocabulary with real
+values.
+
+## Level 0 - your plain CSS already wins
+
+Every shipped rule lives inside `@layer zyncat.tokens` or `@layer zyncat.components`, and unlayered
+CSS beats every layer however specific the layered rule is. `.btn { border-radius: 0 }` in your
+sheet lands: no `!important`, no specificity ladder, no parent selector. Even `:where(.btn)` at
+specificity (0,0,0) wins. Class names are BEM off a short base - `.btn`, `.btn--primary`,
+`.btn__label`; `.fld`, `.fld__input`; `.dialog__body`.
+
+## Level 1 - retheme the whole system
+
+Reach for `@zyncat/ui/theme` first: it is this level with types on it. `defineTheme` takes one
+grouped object - `color`, `type`, `space`, `radius`, `elevation`, `motion`, `glass`, `icon`,
+`layer`, `avatar`, plus `components` for scoped knobs and `custom` for anything else. Keys are the
+token in camelCase (`accent`, `radiusMd`, `durationBase`), values are any CSS including `var()`
+references, and a typo is a compile error. `ZyncatTheme` renders the set once at the app root; it
+is a plain component with no hooks, so it server-renders and needs no build configuration.
+
+```tsx
+import { defineTheme, ZyncatTheme } from '@zyncat/ui/theme';
+
+const base = defineTheme({
+  color: { accent: 'oklch(0.58 0.19 292)', accentHover: 'oklch(0.5 0.19 292)' },
+  radius: { radiusMd: '0.5rem' },
+  components: { odometer: { accent: 'var(--warning)' } },
+});
+const dark = defineTheme({ color: { bgApp: 'oklch(0.19 0.008 198)', textBody: 'oklch(0.92 0.004 198)' } });
+
+<ZyncatTheme theme={{ base, dark }} />;
+```
+
+`base` lands on `:root`; every other key is a `[data-theme='<key>']` block, so switching themes -
+globally or for one subtree - is setting that attribute. Durations you repoint keep their
+reduced-motion collapse automatically.
+
+The same tokens are writable as plain CSS: repoint them on `:root` in your own stylesheet -
+`--accent` and its ramp, `--bg-*`, `--text-*`, `--border-*`, `--radius-*`, `--shadow-*`,
+`--space-*`, `--size-*`, `--type-*`, `--duration-*`, `--ease-*`, `--focus-ring`. Components read
+them live and the WAAPI engine reads the same DOM values, so motion retimes with the CSS. Reduced
+motion is handled here - every `--duration-*` collapses to 1ms under `prefers-reduced-motion`, so
+derive your own delays from a duration token, and repoint durations on `:root` rather than a
+nested scope or the collapse cannot reach them.
+
+## Level 2 - retune one component
+
+Expressive and compound components publish scoped `--<component>-<name>` properties as their public
+contract: `--odometer-size/-accent/-gap`, `--typing-lines-caret-ink/-blink`,
+`--lens-surface/-fringe-warm`, `--morphing-text-size/-smear`, `--weight-field-peak-weight/-hover-padding`,
+`--flow-field-ramp-0..11`, `--confetti-paper-1..5`, `--support-rail-*`. Set them
+on any ancestor or inline via `style`. The canvas simulations sample theirs at their next measure -
+FlowField on resize and on a theme attribute change, Confetti on the next `fire()`.
+
+Both reaches are typed. In a theme they are the `components` group with the prefix dropped:
+`components.odometer.accent` is `--odometer-accent`. On one instance they are the component's own
+`style` prop, which accepts the design tokens plus that component's knobs and nothing from another
+component - `<Odometer style={{ '--odometer-size': '3rem' }} />`.
+
+A few are per-frame state the component writes to itself, not knobs -
+`--odometer-velocity/-blur`, `--lens-lift/-blur/-shadow-alpha`, `--morphing-text-heat/-letter-blur`,
+`--support-rail-drag`, `--youtube-progress`.
+Setting those does nothing, and they are absent from the types, so trying is a compile error.
+
+System primitives and composites publish none by design - retheme those at level 1.
+
+## Level 3 - restyle one instance
+
+Primitives and fields take `className` and `style` directly; on a field they land on the wrapper,
+and `htmlProps` reaches the native `<input>`. Overlays (Dialog, Modal, Sheet, Popover, Tooltip,
+Dropdown) have no `className` prop - pass `htmlProps={{ className }}` and it lands on the panel
+itself. Importing `@zyncat/ui/theme` anywhere in the app types every design token in `style`, so
+`style={{ '--accent': 'red' }}` completes and checks like any other property.
+
+## Replicas answer to none of this, on purpose
+
+FacebookFeed, InstagramFeed, TikTok and YouTube pin platform metrics as constants; only
+`--font-sans`, `--focus-ring` and the duration tokens reach them, and there are no scoped
+properties to set. Fidelity is the contract. If you want a card that follows your theme, build one
+from primitives instead.

package/src/components/composites/alert/Alert.tsx

@@ -1,17 +1,21 @@
 'use client';
 
 import './alert.css';
+
 import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
-import { Presence } from '../../../motion/presence';
+
+import type { DataAttributes } from '../../../dom-props';
 import { Motion } from '../../../motion/element';
 import { resolveMotionTiming } from '../../../motion/motion-timing';
+import { Presence } from '../../../motion/presence';
+import { popOut } from '../../../motion/presets';
 import type { DisableableAnimation } from '../../../motion/timing';
+import { UIMotion } from '../../../tokens/motion-tokens';
+import { useControllable } from '../../internal/hooks/use-controllable';
 import { Icon, type IconName } from '../../internal/icon/Icon';
-import { Button } from '../../primitives/button/Button';
 import { IconSlot } from '../../internal/icon/IconSlot';
-import { useControllable } from '../../internal/hooks/use-controllable';
-import type { DataAttributes } from '../../../dom-props';
 import { cx } from '../../internal/utils/cx';
+import { Button } from '../../primitives/button/Button';
 
 export type AlertTone = 'info' | 'success' | 'warning' | 'danger';
 
@@ -34,7 +38,8 @@ interface AlertOwnProps {
   dismissible?: boolean;
   /** Fires on dismiss. With `open` set, the parent owns hiding the alert. */
   onDismiss?: () => void;
-  /** Controlled visibility; omit for uncontrolled. Exit eases shut (height collapse). */
+  /** Controlled visibility; omit for uncontrolled. Exit scales down and fades; the slot it
+   *  occupied is released when it unmounts, so content below moves up then rather than during. */
   open?: boolean;
   /** App-level strip: square corners, hairline below only. Paint modifier. */
   banner?: boolean;
@@ -44,8 +49,8 @@ interface AlertOwnProps {
   className?: string;
   /** Inline styles merged onto the alert. */
   style?: CSSProperties;
-  /** Enter/exit timing - motion tokens only, or `null` to disable (the height collapse snaps).
-   *  @default height 'slow'/'entrance'; opacity in 'base'/'entrance', out 'fast'/'exit' */
+  /** Enter/exit timing - motion tokens only, or `null` to disable (enter and exit snap).
+   *  @default entrance height 'slow'/'entrance' + opacity 'base'/'entrance'; exit scale + opacity 'fast'/'exit' */
   animation?: DisableableAnimation;
 }
 
@@ -104,10 +109,7 @@ export function Alert({
             { height: [0, 'auto'], timing: h.open },
             { opacity: [0, 1], timing: o.open },
           ]}
-          exit={[
-            { height: ['auto', 0], timing: h.close },
-            { opacity: [1, 0], timing: o.close },
-          ]}
+          exit={[popOut(UIMotion.scale.floating, o.close)]}
         >
           <div className={cls} style={style} data-tone={tone} role={TONE_ROLE[tone] || 'status'} {...htmlProps}>
             {icon === null ? null : (

package/src/components/composites/alert/Alert.usage.md

@@ -0,0 +1,15 @@
+# Alert - @zyncat/ui/alert
+
+Group: overlays
+Docs: https://ui.zyncat.app/alert
+
+Persistent, in-flow status.
+
+tone, title, children (body), action { label, onClick }, dismissible, banner, open/onDismiss
+(controlled).
+
+```tsx
+<Alert tone="warning" title="Your trial ends in 5 days" action={{ label: 'Upgrade', onClick: fn }}>
+  Add a plan...
+</Alert>
+```