@tailor-platform/app-shell 1.14.0 → 1.16.0

package/skills/app-shell-patterns/references/components/activity-card.md

@@ -0,0 +1,142 @@
+---
+title: ActivityCard
+description: Timeline of recent document activities with avatars and overflow dialog
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/activity-card.docs.outline.md — do not edit by hand. -->
+
+# ActivityCard
+
+The `ActivityCard` component displays a timeline of recent activities (e.g. changes on a PO, SO, or GR document). Each entry shows an avatar, user name, description, and timestamp. A limited number of activities are shown in the card; additional activities are available via a clickable overflow that opens a dialog with a scrollable full list.
+
+## Import
+
+```tsx
+import {
+  ActivityCard,
+  type ActivityCardItem,
+  type ActivityCardBaseItem,
+  type ActivityCardProps,
+} from "@tailor-platform/app-shell";
+```
+
+Use `ActivityCardItem` for each item in the standalone API. Use `ActivityCardBaseItem` as the minimum constraint when extending items for the compound API.
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return <ActivityCard items={items} title="Updates" />;
+}
+```
+
+## Overflow and dialog
+
+By default the card shows the 6 most recent activities. If there are more, a button appears at the bottom (e.g. **"2 more activities"**). Clicking it opens a modal dialog titled "All activities" with the full list in a scrollable area. The overflow label can be switched to a count style (**"+2"**) via the `overflowLabel` prop.
+
+```tsx
+<ActivityCard items={manyItems} title="Updates" maxVisible={6} overflowLabel="more" />
+// or overflowLabel="count" for "+N"
+```
+
+## Grouping by day
+
+Set `groupBy="day"` to group activities under labels like "TODAY", "YESTERDAY", or a formatted date.
+
+```tsx
+<ActivityCard items={items} title="Updates" groupBy="day" />
+```
+
+## Props
+
+| Prop            | Type                 | Default  | Description                                       |
+| --------------- | -------------------- | -------- | ------------------------------------------------- |
+| `items`         | `ActivityCardItem[]` | required | List of items (newest first).                     |
+| `title`         | `string`             | -        | Card title, e.g. "Updates".                       |
+| `maxVisible`    | `number`             | `6`      | Max activities shown in the card before overflow. |
+| `overflowLabel` | `"more" \| "count"`  | `"more"` | "N more activities" vs "+N".                      |
+| `groupBy`       | `"none" \| "day"`    | `"none"` | Optional grouping by day.                         |
+| `className`     | `string`             | -        | Applied to the card root.                         |
+
+Each activity must include: `id`, `description`, `timestamp` (Date or string). Optional: `actor` (`{ name, avatarUrl? }`) — omit for system events with no specific actor (initials fallback when `avatarUrl` is absent).
+
+---
+
+## Compound API
+
+Use the compound API when you need fully custom item rendering — custom icons, links, badges, or mixed item kinds. Items still must satisfy `ActivityCardBaseItem` (`id` + `timestamp`). You extend `ActivityCardBaseItem` with any additional fields you need.
+
+### Import
+
+```tsx
+import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
+```
+
+### Parts
+
+| Part                 | Description                                                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ActivityCard.Root`  | Outer card container. Accepts the same `items`, `title`, `maxVisible`, `overflowLabel`, `groupBy` props as the standalone API, plus `children`. |
+| `ActivityCard.Items` | Iterates over items and renders each via a render-prop children function. Generic over your item type.                                          |
+| `ActivityCard.Item`  | A single row in the timeline. Accepts an optional `indicator` (any `ReactNode`) for the left column.                                            |
+
+### ActivityCard.Root Props
+
+| Prop            | Type                | Default  | Description                                                           |
+| --------------- | ------------------- | -------- | --------------------------------------------------------------------- |
+| `items`         | `T[]`               | required | List of items (newest first). `T` must extend `ActivityCardBaseItem`. |
+| `title`         | `string`            | -        | Card title, e.g. "Updates".                                           |
+| `maxVisible`    | `number`            | `6`      | Max items shown in the card before overflow.                          |
+| `overflowLabel` | `"more" \| "count"` | `"more"` | "N more activities" vs "+N".                                          |
+| `groupBy`       | `"none" \| "day"`   | `"none"` | Optional grouping by day.                                             |
+| `className`     | `string`            | -        | Applied to the card root.                                             |
+| `children`      | `React.ReactNode`   | required | Must contain `ActivityCard.Items`.                                    |
+
+### ActivityCard.Item Props
+
+| Prop        | Type              | Default | Description                                                                                |
+| ----------- | ----------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `indicator` | `React.ReactNode` | -       | Element rendered in the left column (e.g. Avatar, icon). Omit for a default timeline node. |
+| `children`  | `React.ReactNode` | -       | Content for the item row (text, badges, links, etc.).                                      |
+| `className` | `string`          | -       | Additional CSS classes.                                                                    |
+
+### Example
+
+```tsx
+import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
+
+interface MyItem extends ActivityCardBaseItem {
+  kind: "approval" | "update";
+  label?: string;
+  message?: string;
+}
+
+const items: MyItem[] = [
+  { id: "1", timestamp: new Date(), kind: "approval", label: "PO approved" },
+  { id: "2", timestamp: new Date(), kind: "update", message: "Status changed to CONFIRMED" },
+];
+
+<ActivityCard.Root items={items} title="Updates" groupBy="day">
+  <ActivityCard.Items<MyItem>>
+    {(item) =>
+      item.kind === "approval" ? (
+        <ActivityCard.Item indicator={<ApprovedIcon />}>
+          <p>{item.label}</p>
+        </ActivityCard.Item>
+      ) : (
+        <ActivityCard.Item>
+          <p>{item.message}</p>
+        </ActivityCard.Item>
+      )
+    }
+  </ActivityCard.Items>
+</ActivityCard.Root>;
+```
+
+---
+
+## See also
+
+- [Avatar](./avatar.md) — underlying avatar primitive used for profile images and initials

package/skills/app-shell-patterns/references/components/ai-chat.md

@@ -0,0 +1,315 @@
+---
+title: AIChat
+description: Building blocks for an LLM assistant UI — a streaming conversation view over a composer, plus reasoning, tool-call, and citation parts
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/ai-chat.docs.outline.md — do not edit by hand. -->
+
+# AIChat
+
+`AIChat` owns the frame for an assistant UI and places its three regions in a fixed order, the way [`Layout`](./layout.md) places `Layout.Header` and `Layout.Column`: **`AIChat.Header`** (optional) over **`AIChat.Conversation`** (required) over **`AIChat.Composer`** (optional). Each region carries its own props; the root carries only the chat's `status`. You compose the transcript inside `AIChat.Conversation` from the attached parts — `AIChat.Message`, `AIChat.Response`, `AIChat.Reasoning`, `AIChat.Tool`, `AIChat.Sources`, and more — against your own [`useAIChat()`](../api/use-ai-chat.md) state.
+
+It renders no border or background of its own. Wrap it in [`Card`](./card.md), [`Sheet`](./sheet.md), or a `Layout.Column` for the surrounding surface.
+
+## Import
+
+```tsx
+import { AIChat, useAIChat, createAIGatewayClient } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+```tsx
+function Assistant() {
+  const client = useMemo(() => createAIGatewayClient({ gatewayUri, authClient }), [authClient]);
+  const { messages, status, sendMessage, stop } = useAIChat({ client, model: "gpt-5" });
+
+  return (
+    // `overflow-hidden` keeps the header rule inside the card's rounded corners.
+    <Card.Root className="flex h-full flex-col overflow-hidden">
+      <AIChat status={status}>
+        <AIChat.Header title="Assistant" />
+        <AIChat.Conversation>
+          {messages.length === 0 ? (
+            <AIChat.EmptyState title="Ask the assistant" />
+          ) : (
+            messages.map((message) => (
+              <AIChat.Message key={message.id} from={message.role}>
+                <AIChat.Response>{message.content}</AIChat.Response>
+              </AIChat.Message>
+            ))
+          )}
+        </AIChat.Conversation>
+        <AIChat.Composer onSubmit={sendMessage} onStop={stop} />
+      </AIChat>
+    </Card.Root>
+  );
+}
+```
+
+`message.role` ("user" | "assistant") from `useAIChat` lines up directly with `AIChat.Message`'s `from` prop — no mapping step. `AIChat` streams for real when the AI Gateway sends real SSE chunks; there is no client-side typewriter effect.
+
+The regions can appear in any source order — the root always renders Header, then Conversation, then Composer. Omit `AIChat.Composer` for a read-only transcript.
+
+They must be **direct** children. The root matches them by component identity, so a region wrapped in one of your own components — `const AppComposer = () => <AIChat.Composer … />` — is not recognised, and is dropped with a console warning like any other unexpected child. To preset props, export the props instead of the element: `<AIChat.Composer {...appComposerProps} />`.
+
+## Props
+
+### `AIChat`
+
+| Prop        | Type                                               | Default   | Description                                                                                          |
+| ----------- | -------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `children`  | `ReactNode`                                        | required  | `AIChat.Header`, `AIChat.Conversation`, and `AIChat.Composer`, in any order.                         |
+| `status`    | `"ready" \| "submitted" \| "streaming" \| "error"` | `"ready"` | The chat's state. Plugs directly into `useAIChat()`'s `status`; `AIChat.Composer` reads it.          |
+| `className` | `string`                                           | -         | Merged onto the root. It already fills a block parent (`h-full`) or a flex-column parent (`flex-1`). |
+
+Other props spread onto the root `<div>`.
+
+### `AIChat.Header`
+
+| Prop        | Type        | Default | Description                                                                                      |
+| ----------- | ----------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `title`     | `ReactNode` | -       | Title text.                                                                                      |
+| `icon`      | `ReactNode` | sparkle | Leading graphic. Pass `null` for none, or a control (e.g. a collapse button) for a docked panel. |
+| `actions`   | `ReactNode` | -       | Right-aligned slot — compose it from `AIChat.Action`.                                            |
+| `className` | `string`    | -       |                                                                                                  |
+
+### `AIChat.Conversation`
+
+| Prop         | Type        | Default  | Description                                                                           |
+| ------------ | ----------- | -------- | ------------------------------------------------------------------------------------- |
+| `children`   | `ReactNode` | required | The transcript. Composed from the attached parts, or `AIChat.EmptyState` while empty. |
+| `autoScroll` | `boolean`   | `true`   | Follow content growth while the reader is pinned to the bottom.                       |
+| `className`  | `string`    | -        |                                                                                       |
+
+Other props spread onto the region's outer `<div>`.
+
+### `AIChat.Composer`
+
+| Prop            | Type                        | Default  | Description                                                                      |
+| --------------- | --------------------------- | -------- | -------------------------------------------------------------------------------- |
+| `onSubmit`      | `(message: string) => void` | required | Called with the trimmed prompt.                                                  |
+| `onStop`        | `() => void`                | -        | Called from the Stop button while the chat is busy. Omit for a plain busy state. |
+| `value`         | `string`                    | -        | Controlled draft. Cleared via `onValueChange("")` after a successful submit.     |
+| `defaultValue`  | `string`                    | `""`     | Uncontrolled draft's initial value.                                              |
+| `onValueChange` | `(value: string) => void`   | -        | Called on every draft change, including the post-submit clear.                   |
+| `placeholder`   | `string`                    | -        |                                                                                  |
+| `disabled`      | `boolean`                   | `false`  | Disables the composer — not the transcript above it.                             |
+| `submitOnEnter` | `boolean`                   | `true`   | Enter submits (IME-safe); Shift+Enter always inserts a newline.                  |
+| `actions`       | `ReactNode`                 | -        | Open slot on the action row — a visibility toggle, a model picker, a select.     |
+| `className`     | `string`                    | -        |                                                                                  |
+
+## Prop pass-through
+
+Most props stay inside their region. These `AIChat.Composer` props land on **another AppShell component**, so they carry that component's contract — and any future change to it — rather than one `AIChat` defines:
+
+| Prop          | Reaches                                                                | Note                                    |
+| ------------- | ---------------------------------------------------------------------- | --------------------------------------- |
+| `value`       | [`Textarea`](./textarea.md) `value`                                    | The composer body is a real `Textarea`. |
+| `placeholder` | [`Textarea`](./textarea.md) `placeholder`                              |                                         |
+| `disabled`    | [`Textarea`](./textarea.md) **and** the attach [`Button`](./button.md) | One prop, two components.               |
+| `onStop`      | [`Button`](./button.md) `onClick`                                      | Becomes the Stop button's handler.      |
+
+`onValueChange` is wrapped rather than forwarded — it is called from the `Textarea`'s `onChange`, and again with `""` after a submit. `defaultValue` seeds the composer's own state and is never forwarded. Nothing on `AIChat`, `AIChat.Header`, or `AIChat.Conversation` reaches another AppShell component.
+
+Three attached parts wrap an AppShell component. They expose only the props the part's job needs rather than inheriting the wrapped component's surface, so its visual treatment is fixed and not yours to change:
+
+| Part                                | Wraps                                                      | Accepts                                                       | Fixed                              |
+| ----------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------- |
+| `AIChat.Suggestion`                 | [`Button`](./button.md)                                    | `suggestion`, `onSelect`, `className`, `disabled`, `children` | `variant="secondary"`, `size="sm"` |
+| `AIChat.Action`                     | [`Button`](./button.md) inside a [`Tooltip`](./tooltip.md) | `label`, `onClick`, `className`, `disabled`, `children`       | `variant="ghost"`, `size="icon"`   |
+| `AIChat.ChainOfThoughtSearchResult` | [`Badge`](./badge.md)                                      | `className`, `children`, `variant`                            | —                                  |
+
+`variant` stays open on `ChainOfThoughtSearchResult` because conveying status is what a `Badge` is for. `AIChat.Action`'s `label` becomes both the accessible name and the tooltip text.
+
+One thing to know about `className` on these: it is merged with `cn()`, which is not configured for AppShell's internal prefix, so it cannot reliably override a base utility from the wrapped component. Add properties the component doesn't set, and reach for the wrapped component's own props or variants to change ones it does — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components).
+
+## Filling the page
+
+`AIChat` fills whatever height its parent gives it — `h-full` for a block parent, `flex-1 min-h-0` for a flex column — and never grows the page: the transcript scrolls internally while the header and composer stay pinned. Give the surface around it a definite height.
+
+Inside a `<Layout fill>` column (the column is `flex flex-col`, so the card takes the leftover space):
+
+```tsx
+<Layout fill>
+  <Layout.Header title="Assistant" />
+  <Layout.Column>
+    <Card.Root className="flex min-h-0 flex-1 flex-col overflow-hidden">
+      <AIChat status={status}>
+        <AIChat.Header title="Assistant" />
+        <AIChat.Conversation>{/* … */}</AIChat.Conversation>
+        <AIChat.Composer onSubmit={sendMessage} />
+      </AIChat>
+    </Card.Root>
+  </Layout.Column>
+</Layout>
+```
+
+`min-h-0` is what lets the card shrink below its content's natural height so the transcript scrolls instead of pushing the composer off-screen. In a docked panel or `Sheet` whose height is already fixed, `h-full` on the card is enough.
+
+## Header
+
+A 48px strip above the transcript: leading graphic, title, and an open action slot on the right, closed by a rule that runs the full width of the surface. Omit it for a bare transcript-and-composer surface, and give the card `overflow-hidden` so the rule stays inside its rounded corners.
+
+```tsx
+<AIChat.Header
+  title="Assistant"
+  actions={
+    <>
+      <AIChat.Action label="Conversation history" onClick={openHistory}>
+        <History className="size-3.5" aria-hidden />
+      </AIChat.Action>
+      <AIChat.Action label="Clear conversation" onClick={clear}>
+        <Eraser className="size-3.5" aria-hidden />
+      </AIChat.Action>
+    </>
+  }
+/>
+```
+
+For a docked right panel, put the collapse control in `icon` so it takes the leading position:
+
+```tsx
+<AIChat.Header
+  title="Assistant"
+  icon={
+    <AIChat.Action label="Collapse panel" onClick={onClose}>
+      <ChevronsRight className="size-3.5" aria-hidden />
+    </AIChat.Action>
+  }
+/>
+```
+
+## Attached parts
+
+### Message
+
+```tsx
+<AIChat.Message from="assistant">
+  <AIChat.Response>{message.content}</AIChat.Response>
+</AIChat.Message>
+```
+
+User turns render as a right-aligned primary bubble; assistant turns take the full width with no bubble, so reasoning, tool calls, and citations stack inside the same column above the response text.
+
+### Response
+
+Renders the markdown subset a streamed LLM response actually emits — bold, inline code, links, headings, bullet/numbered lists — without a markdown dependency. Only `http(s):`, `mailto:`, and same-site relative links render as clickable; any other target renders as plain text, since the text passing through here is untrusted model output. For full CommonMark, swap `<AIChat.Response>` for `react-markdown` or the AI SDK's `streamdown` — call sites keep the same shape.
+
+```tsx
+<AIChat.Response>{message.content}</AIChat.Response>
+```
+
+### EmptyState / Suggestions
+
+`AIChat.EmptyState` stacks `icon`, then the `title`/`description` block, then `children` — so starter suggestions sit alongside the text rather than replacing it:
+
+```tsx
+<AIChat.EmptyState
+  icon={<Sparkles className="size-6 text-primary" aria-hidden />}
+  title="Ask the assistant"
+  description="Grounded in your help articles."
+>
+  <AIChat.Suggestions>
+    <AIChat.Suggestion suggestion="How do I create a purchase order?" onSelect={sendMessage} />
+  </AIChat.Suggestions>
+</AIChat.EmptyState>
+```
+
+`AIChat.Suggestion` submits its `suggestion` text as if the reader had typed and sent it via `onSelect`.
+
+### Actions
+
+Icon-button row under a finished assistant turn — copy, retry, feedback. Render it only once the turn has finished so streaming turns stay uncluttered.
+
+```tsx
+<AIChat.Actions>
+  <AIChat.Action label="Copy" onClick={() => navigator.clipboard.writeText(message.content)}>
+    <Copy className="size-3.5" aria-hidden />
+  </AIChat.Action>
+</AIChat.Actions>
+```
+
+### Reasoning
+
+Collapsible "thinking" block for reasoning models. Auto-opens while `isStreaming` is true and auto-closes when it turns false, unless the reader has manually toggled it.
+
+```tsx
+<AIChat.Reasoning isStreaming={reasoning.streaming} duration={reasoning.duration}>
+  <AIChat.ReasoningTrigger />
+  <AIChat.ReasoningContent>{reasoning.text}</AIChat.ReasoningContent>
+</AIChat.Reasoning>
+```
+
+### ChainOfThought
+
+Structured step timeline for agentic turns — the discrete plan being executed, each step with a status and optional result chips. Use `Reasoning` for free-form thinking text and this for multi-step tool plans.
+
+```tsx
+<AIChat.ChainOfThought defaultOpen>
+  <AIChat.ChainOfThoughtHeader />
+  <AIChat.ChainOfThoughtContent>
+    <AIChat.ChainOfThoughtStep label="Searching the knowledge base" status="complete">
+      <AIChat.ChainOfThoughtSearchResults>
+        <AIChat.ChainOfThoughtSearchResult>12 hits</AIChat.ChainOfThoughtSearchResult>
+      </AIChat.ChainOfThoughtSearchResults>
+    </AIChat.ChainOfThoughtStep>
+    <AIChat.ChainOfThoughtStep label="Drafting the answer" status="active" />
+  </AIChat.ChainOfThoughtContent>
+</AIChat.ChainOfThought>
+```
+
+`status` is `"complete" | "active" | "pending"`.
+
+### Tool
+
+Collapsible tool-call card. Maps 1:1 to the AI SDK's tool-part lifecycle, so a streaming loop can update a call in place as parts arrive.
+
+```tsx
+<AIChat.Tool>
+  <AIChat.ToolHeader toolName="search_kb" state={call.state} />
+  <AIChat.ToolContent>
+    <AIChat.ToolInput input={call.input} />
+    <AIChat.ToolOutput output={call.output} errorText={call.errorText} />
+  </AIChat.ToolContent>
+</AIChat.Tool>
+```
+
+`state` is `"input-streaming" | "input-available" | "output-available" | "output-error"`.
+
+### Sources
+
+Compact "Used N sources" citation trigger under a grounded answer.
+
+```tsx
+<AIChat.Sources>
+  <AIChat.SourcesTrigger count={sources.length} />
+  <AIChat.SourcesContent>
+    {sources.map((source) => (
+      <AIChat.Source key={source.id} title={source.title} onClick={() => openDocument(source.id)} />
+    ))}
+  </AIChat.SourcesContent>
+</AIChat.Sources>
+```
+
+### History
+
+Grouped list of past conversations for reopening an earlier chat. Layout-agnostic — render it in a popover behind a header action, or as a sidebar section of a full chat page. Group titles and date bucketing are yours; `AIChat.History` has no opinion on date ranges.
+
+```tsx
+<AIChat.History
+  groups={[{ title: "Today", items: [{ id: "1", title: "Creating a purchase order" }] }]}
+  activeId={activeId}
+  onSelect={loadConversation}
+  onDelete={deleteConversation}
+/>
+```
+
+## Related components
+
+- [Layout](./layout.md) — the same children-placed-by-the-root shape
+- [Textarea](./textarea.md) — the composer's body control
+- [Card](./card.md)
+- [Button](./button.md)
+- [useAIChat](../api/use-ai-chat.md)
+- [createAIGatewayClient](../api/create-ai-gateway-client.md)

package/skills/app-shell-patterns/references/components/alert.md

@@ -0,0 +1,202 @@
+---
+title: Alert
+description: Contextual status messages with automatic variant icons
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/alert.docs.outline.md — do not edit by hand. -->
+
+# Alert
+
+The `Alert` component is a compound component for displaying contextual status messages. It automatically renders a matching icon for each variant and supports optional action buttons and dismiss behavior.
+
+## Import
+
+```tsx
+import { Alert } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Alert.Root variant="success">
+      <Alert.Title>Saved</Alert.Title>
+      <Alert.Description>Your changes have been saved.</Alert.Description>
+    </Alert.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component       | Description                                       |
+| ------------------- | ------------------------------------------------- |
+| `Alert.Root`        | Container with variant styling and automatic icon |
+| `Alert.Title`       | Bold title line of the alert                      |
+| `Alert.Description` | Additional descriptive text below the title       |
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### AlertProps
+
+| Prop           | Type                                                               | Default     | Description                                          |
+| -------------- | ------------------------------------------------------------------ | ----------- | ---------------------------------------------------- |
+| `action?`      | `React.ReactNode`                                                  | -           | Action element rendered below the description        |
+| `dismissible?` | `boolean`                                                          | -           | Shows a dismiss button; hides the alert when clicked |
+| `onDismiss?`   | `() => void`                                                       | -           | Callback invoked when the dismiss button is clicked  |
+| `variant?`     | `"error" \| "neutral" \| "success" \| "warning" \| "info" \| null` | `"neutral"` | Visual style and automatic icon                      |
+
+## Exports
+
+- `Alert` — const
+- `AlertProps` — type
+- `alertVariants` — const
+
+All standard HTML `<div>` props are also accepted.
+
+## Variants
+
+Each variant automatically renders a contextual icon:
+
+```tsx
+<Alert.Root variant="neutral">
+  <Alert.Title>Note</Alert.Title>
+  <Alert.Description>General information.</Alert.Description>
+</Alert.Root>
+
+<Alert.Root variant="success">
+  <Alert.Title>Success</Alert.Title>
+  <Alert.Description>Operation completed successfully.</Alert.Description>
+</Alert.Root>
+
+<Alert.Root variant="warning">
+  <Alert.Title>Warning</Alert.Title>
+  <Alert.Description>Proceed with caution.</Alert.Description>
+</Alert.Root>
+
+<Alert.Root variant="error">
+  <Alert.Title>Error</Alert.Title>
+  <Alert.Description>Something went wrong.</Alert.Description>
+</Alert.Root>
+
+<Alert.Root variant="info">
+  <Alert.Title>Info</Alert.Title>
+  <Alert.Description>Here is some useful information.</Alert.Description>
+</Alert.Root>
+```
+
+| Variant   | Automatic Icon      | Color palette   |
+| --------- | ------------------- | --------------- |
+| `neutral` | Message circle icon | Muted surface   |
+| `success` | Check circle icon   | Green           |
+| `warning` | Alert triangle icon | Yellow          |
+| `error`   | X circle icon       | Red/destructive |
+| `info`    | Info icon           | Blue            |
+
+## With Action Button
+
+Use the `action` prop to render an action element below the description:
+
+```tsx
+<Alert.Root
+  variant="warning"
+  action={
+    <Button size="sm" variant="outline">
+      Review
+    </Button>
+  }
+>
+  <Alert.Title>Review Required</Alert.Title>
+  <Alert.Description>This record has pending changes that need review.</Alert.Description>
+</Alert.Root>
+```
+
+## Dismissible Alert
+
+Set `dismissible` to show a close button. Use `onDismiss` to react when the alert is dismissed:
+
+```tsx
+<Alert.Root variant="info" dismissible onDismiss={() => markAlertRead(alertId)}>
+  <Alert.Title>New Feature Available</Alert.Title>
+  <Alert.Description>Check out the new dashboard layout in Settings.</Alert.Description>
+</Alert.Root>
+```
+
+> **Note:** When `dismissible` is `true`, clicking the close button hides the alert via internal state. The `onDismiss` callback fires after the alert is hidden.
+
+## Examples
+
+### Form Validation Error
+
+```tsx
+function OrderForm() {
+  const [error, setError] = useState<string | null>(null);
+
+  return (
+    <form>
+      {error && (
+        <Alert.Root variant="error" dismissible onDismiss={() => setError(null)}>
+          <Alert.Title>Submission Failed</Alert.Title>
+          <Alert.Description>{error}</Alert.Description>
+        </Alert.Root>
+      )}
+      {/* form fields */}
+    </form>
+  );
+}
+```
+
+### Success Confirmation
+
+```tsx
+<Alert.Root variant="success">
+  <Alert.Title>Invoice Created</Alert.Title>
+  <Alert.Description>Invoice #INV-0042 has been sent to the customer.</Alert.Description>
+</Alert.Root>
+```
+
+### Warning with Action
+
+```tsx
+<Alert.Root
+  variant="warning"
+  action={
+    <Button size="sm" variant="outline" onClick={() => navigate("/settings/billing")}>
+      Update Billing
+    </Button>
+  }
+>
+  <Alert.Title>Payment Method Expiring</Alert.Title>
+  <Alert.Description>Your credit card on file expires at the end of this month.</Alert.Description>
+</Alert.Root>
+```
+
+## Accessibility
+
+- The root element has `role="alert"` so screen readers announce the message.
+- The dismiss button has `aria-label="Dismiss"`.
+- Variant icons are marked `aria-hidden` and are decorative only — the text content carries the meaning.
+
+## Styling
+
+Alerts are styled with the library's internal `astw:`-prefixed utilities. Write **plain** Tailwind utilities in your own markup, and reach for `variant` rather than restyling what `Alert` sets itself — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components). Customize appearance using:
+
+1. **Using `className`** on `Alert.Root` for additional styles
+2. **Using `alertVariants`** utility to apply variant classes to custom elements
+
+```tsx
+import { alertVariants } from "@tailor-platform/app-shell";
+import { cn } from "@/lib/utils";
+
+<div className={cn(alertVariants({ variant: "info" }), "my-4")}>Custom alert container</div>;
+```
+
+## Related Components
+
+- [Badge](./badge.md) - Inline status labels
+- [Button](./button.md) - Use as action element inside alerts