@cdx-ui/components 0.3.5 → 0.3.7

package/docs/components/system-alert/content.md

@@ -0,0 +1,533 @@
+# System Alert (https://design.candescent.com/docs/components/system-alert)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8228-5936), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-systemalert--default)
+
+A compound component for one app-wide message, with sub-components for the icon, the description, and trailing actions. It renders in the document flow and pushes the page down; it is not an overlay, toast, or portal. Open and close it with `isOpen`, and it slides in and out while pushing the content below it.
+
+```tsx
+import { SystemAlert } from '@cdx-ui/components';
+```
+
+> [!WARNING]
+>
+> **Mount it above the header**
+>
+> Render `SystemAlert` as the first child of the screen root, outside any `SafeAreaView` and outside
+> the page `ScrollView`. On a screen with a SystemAlert, the app header must not apply its own top
+> inset. See [Placement](#placement).
+
+## Basic
+
+`color` defaults to `info`. `SystemAlert.Icon` renders the default glyph for the current `color`; pass `as` to replace it. Without `isOpen`, the banner shows for as long as it is mounted, with no motion. That fits a message decided when the screen loads that stays for the whole visit.
+
+```tsx
+import { SystemAlert } from '@cdx-ui/components';
+
+export default function SystemAlertBasicDemo() {
+  return (
+    <SystemAlert>
+      <SystemAlert.Icon />
+      <SystemAlert.Description>
+        Branches are closed on November 11 for Veterans Day.
+      </SystemAlert.Description>
+    </SystemAlert>
+  );
+}
+```
+
+## Colors
+
+`color` sets the strong surface, the icon, the text, and every control. `danger` and `warning` interrupt screen readers; `success`, `info`, and `brand` announce politely. Use `brand` for announcements that carry no urgency.
+
+```tsx
+import { SystemAlert, VStack } from '@cdx-ui/components';
+
+export default function SystemAlertColorsDemo() {
+  return (
+    <VStack space="md" className="w-full">
+      <SystemAlert color="danger">
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Online banking is unavailable. We are working to restore service.
+        </SystemAlert.Description>
+      </SystemAlert>
+      <SystemAlert color="warning">
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Verify your email address to keep receiving statements.
+        </SystemAlert.Description>
+      </SystemAlert>
+      <SystemAlert color="success">
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Service has been restored. Thank you for your patience.
+        </SystemAlert.Description>
+      </SystemAlert>
+      <SystemAlert color="info">
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Branches are closed on November 11 for Veterans Day.
+        </SystemAlert.Description>
+      </SystemAlert>
+      <SystemAlert color="brand">
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          New budgeting tools are now available in Insights.
+        </SystemAlert.Description>
+      </SystemAlert>
+    </VStack>
+  );
+}
+```
+
+## Controlled
+
+Set `isOpen` to open or close the banner while someone is on the screen, including when they dismiss it. Opening slides the banner down from the top edge, through the status-bar area, and then pushes the header and page down by its height. Closing reverses it. A banner with `isOpen={true}` on the first render appears in place without motion. `isOpen` is controlled only, so set it to `false` from `onClose`. Here, the bell button opens a `brand` banner, and dismissing it moves focus back to the bell.
+
+```tsx
+import { useRef, useState, type ComponentRef } from 'react';
+import {
+  Box,
+  Card,
+  Heading,
+  IconButton,
+  ListItem,
+  ScrollView,
+  SystemAlert,
+  Text,
+} from '@cdx-ui/components';
+import { Notifications } from '@cdx-ui/icons';
+
+const ACCOUNTS = [
+  { id: 'checking', name: 'Everyday Checking · 6643', balance: '$2,450.00' },
+  { id: 'savings', name: 'High-Yield Savings · 1180', balance: '$12,875.42' },
+  { id: 'card', name: 'Rewards Visa · 3021', balance: '$684.19' },
+  { id: 'cd', name: '12-Month CD · 5507', balance: '$5,000.00' },
+  { id: 'auto', name: 'Auto Loan · 8812', balance: '$14,310.77' },
+  { id: 'mortgage', name: 'Mortgage · 2290', balance: '$212,904.03' },
+];
+
+export default function SystemAlertPresenceDemo() {
+  const [isNoticeOpen, setIsNoticeOpen] = useState(false);
+  const openRef = useRef<ComponentRef<typeof IconButton>>(null);
+
+  const close = () => {
+    openRef.current?.focus();
+    setIsNoticeOpen(false);
+  };
+
+  return (
+    <Box className="h-120 w-full max-w-sm">
+      <Card fullBleed className="flex-1">
+        <SystemAlert color="brand" isOpen={isNoticeOpen} onClose={close}>
+          <SystemAlert.Icon />
+          <SystemAlert.Description>
+            New budgeting tools are now in Insights.
+          </SystemAlert.Description>
+        </SystemAlert>
+        <Card.Header>
+          <Heading size="sm">Accounts</Heading>
+          <IconButton
+            ref={openRef}
+            as={Notifications}
+            variant="ghost"
+            accessibilityLabel="What's new"
+            onPress={() => setIsNoticeOpen(true)}
+          />
+        </Card.Header>
+        <ScrollView className="flex-1">
+          {ACCOUNTS.map((account, index) => (
+            <ListItem key={account.id} showSeparator={index < ACCOUNTS.length - 1}>
+              <ListItem.Content>
+                <ListItem.Title>{account.name}</ListItem.Title>
+                <ListItem.Description>Available balance</ListItem.Description>
+              </ListItem.Content>
+              <ListItem.TrailingSlot>
+                <Text>{account.balance}</Text>
+              </ListItem.TrailingSlot>
+            </ListItem>
+          ))}
+        </ScrollView>
+      </Card>
+    </Box>
+  );
+}
+```
+
+> [!WARNING]
+>
+> **Keep it mounted**
+>
+> Close a banner with `isOpen={false}`; do not unmount it. Unmounting removes it in one frame, so
+> the header and page jump up. While closed, the banner reserves a transparent strip the height of
+> the top inset on iOS and Android, so the header below never applies its own top inset on that
+> screen, open or closed. Unmounting removes the strip too, and the header slides under the status
+> bar.
+
+The closed strip is transparent, so match the colour behind the banner to the header. Either set the screen root's background to the header's colour and give the page `ScrollView` its own background, or wrap the banner in a `View` with the header's background. On web the inset is zero, so the closed banner takes no space.
+
+Open `info` and `brand` banners, such as a "What's new" notice, from a control. Open `danger` and `warning` from app state, such as an outage, a failed payment, or a required verification, rather than from a control: an assertive alert interrupts screen reader users, which is wrong for something they just asked to see.
+
+## With actions
+
+Put `SystemAlert.Action` and `SystemAlert.IconAction` inside `SystemAlert.Actions`. Set `onClose` to add a dismiss button as the last control. SystemAlert does not close itself: in `onClose`, move focus to a sensible target, then set `isOpen={false}`. Here, dismissing moves focus to the **Show alert** button, which opens the banner again.
+
+```tsx
+import { useRef, useState, type ComponentRef } from 'react';
+import { Button, SystemAlert, VStack } from '@cdx-ui/components';
+import { Refresh } from '@cdx-ui/icons';
+
+export default function SystemAlertWithActionsDemo() {
+  const [isOpen, setIsOpen] = useState(true);
+  const showRef = useRef<ComponentRef<typeof Button>>(null);
+
+  const close = () => {
+    showRef.current?.focus();
+    setIsOpen(false);
+  };
+
+  return (
+    <VStack space="lg" className="w-full items-start">
+      <SystemAlert color="info" isOpen={isOpen} onClose={close}>
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Mobile check deposit is down for maintenance until 6 AM ET.
+        </SystemAlert.Description>
+        <SystemAlert.Actions>
+          <SystemAlert.Action onPress={() => {}}>Details</SystemAlert.Action>
+          <SystemAlert.IconAction
+            as={Refresh}
+            accessibilityLabel="Check service status"
+            onPress={() => {}}
+          />
+        </SystemAlert.Actions>
+      </SystemAlert>
+      <Button ref={showRef} variant="outline" size="small" onPress={() => setIsOpen(true)}>
+        <Button.Label>Show alert</Button.Label>
+      </Button>
+    </VStack>
+  );
+}
+```
+
+## Text wrapping
+
+The description wraps and the banner grows downward, while the icon and trailing controls stay aligned with the first line. There is no default line limit. Use nested `Text` with `weight="bold"` for a lead-in.
+
+```tsx
+import { Box, SystemAlert, Text } from '@cdx-ui/components';
+
+export default function SystemAlertTextWrappingDemo() {
+  return (
+    <Box className="w-full max-w-xs">
+      <SystemAlert color="warning" onClose={() => {}}>
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          <Text weight="bold">Action required:</Text> confirm your mailing address by December 1 to
+          keep receiving paper statements and tax documents.
+        </SystemAlert.Description>
+        <SystemAlert.Actions>
+          <SystemAlert.Action onPress={() => {}}>Confirm</SystemAlert.Action>
+        </SystemAlert.Actions>
+      </SystemAlert>
+    </Box>
+  );
+}
+```
+
+To clamp the message, set `numberOfLines` on `SystemAlert.Description`. Keep the link to the full message in `SystemAlert.Actions` so the ellipsis never clips it. Screen readers still read the full text.
+
+```tsx
+import { Box, SystemAlert, Text } from '@cdx-ui/components';
+
+export default function SystemAlertTruncatedDemo() {
+  return (
+    <Box className="w-full max-w-sm">
+      <SystemAlert color="info">
+        <SystemAlert.Icon />
+        <SystemAlert.Description numberOfLines={1}>
+          <Text weight="bold">Important:</Text> starting December 1, wire transfers submitted after
+          4 PM ET are processed on the next business day.
+        </SystemAlert.Description>
+        <SystemAlert.Actions>
+          <SystemAlert.Action onPress={() => {}}>View details</SystemAlert.Action>
+        </SystemAlert.Actions>
+      </SystemAlert>
+    </Box>
+  );
+}
+```
+
+## Placement
+
+The banner is the first child of the screen root, then the header, then the page `ScrollView`. On iOS and Android the surface paints behind the status bar and the content row starts below the top safe-area inset; on web the inset is zero. Because it sits outside the `ScrollView`, it stays pinned while the page scrolls. Dismissing it slides it up, the header and page move up with it, and focus moves to the notifications button, whose warning dot shows there is an alert to reopen.
+
+```tsx
+import { useRef, useState, type ComponentRef } from 'react';
+import {
+  Badge,
+  Box,
+  Card,
+  Heading,
+  IconButton,
+  ListItem,
+  ScrollView,
+  SystemAlert,
+} from '@cdx-ui/components';
+import { Download, Notifications } from '@cdx-ui/icons';
+
+const STATEMENTS = [
+  { id: '2026-09', period: 'September 2026', issued: 'Issued Oct 1' },
+  { id: '2026-08', period: 'August 2026', issued: 'Issued Sep 1' },
+  { id: '2026-07', period: 'July 2026', issued: 'Issued Aug 1' },
+  { id: '2026-06', period: 'June 2026', issued: 'Issued Jul 1' },
+  { id: '2026-05', period: 'May 2026', issued: 'Issued Jun 1' },
+  { id: '2026-04', period: 'April 2026', issued: 'Issued May 1' },
+  { id: '2026-03', period: 'March 2026', issued: 'Issued Apr 1' },
+];
+
+export default function SystemAlertPlacementDemo() {
+  const [isAlertOpen, setIsAlertOpen] = useState(true);
+  const notificationsRef = useRef<ComponentRef<typeof IconButton>>(null);
+
+  const close = () => {
+    notificationsRef.current?.focus();
+    setIsAlertOpen(false);
+  };
+
+  return (
+    <Box className="h-120 w-full max-w-sm">
+      <Card fullBleed className="flex-1">
+        <SystemAlert color="warning" isOpen={isAlertOpen} onClose={close}>
+          <SystemAlert.Icon />
+          <SystemAlert.Description>
+            Verify your email address to keep receiving statements.
+          </SystemAlert.Description>
+          <SystemAlert.Actions>
+            <SystemAlert.Action onPress={() => {}}>Verify</SystemAlert.Action>
+          </SystemAlert.Actions>
+        </SystemAlert>
+        <Card.Header>
+          <Heading size="sm">Statements</Heading>
+          <Badge variant="dot" color="warning" overlap="circular">
+            <IconButton
+              ref={notificationsRef}
+              as={Notifications}
+              variant="ghost"
+              accessibilityLabel="Notifications, 1 alert"
+              onPress={() => setIsAlertOpen(true)}
+            />
+          </Badge>
+        </Card.Header>
+        <ScrollView className="flex-1">
+          {STATEMENTS.map((statement, index) => (
+            <ListItem key={statement.id} showSeparator={index < STATEMENTS.length - 1}>
+              <ListItem.Content>
+                <ListItem.Title>{statement.period}</ListItem.Title>
+                <ListItem.Description>{statement.issued}</ListItem.Description>
+              </ListItem.Content>
+              <ListItem.TrailingSlot>
+                <IconButton
+                  as={Download}
+                  variant="ghost"
+                  accessibilityLabel={`Download ${statement.period} statement`}
+                  onPress={() => {}}
+                />
+              </ListItem.TrailingSlot>
+            </ListItem>
+          ))}
+        </ScrollView>
+      </Card>
+    </Box>
+  );
+}
+```
+
+## Multiple
+
+Every banner pads by the top inset by default. When you stack a second banner below the first, set `hasSafeAreaInset={false}` on it so the inset is applied once. Use the same setting for a banner that does not sit at the top edge of the screen.
+
+```tsx
+import { Box, SystemAlert } from '@cdx-ui/components';
+
+export default function SystemAlertMultipleDemo() {
+  return (
+    <Box className="w-full">
+      <SystemAlert color="danger">
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Online banking is unavailable. We are working to restore service.
+        </SystemAlert.Description>
+      </SystemAlert>
+      <SystemAlert color="info" hasSafeAreaInset={false}>
+        <SystemAlert.Icon />
+        <SystemAlert.Description>
+          Branches are closed on November 11 for Veterans Day.
+        </SystemAlert.Description>
+      </SystemAlert>
+    </Box>
+  );
+}
+```
+
+## API
+
+### SystemAlert
+
+Root banner. Its `children` render in source order inside the content row, followed by the dismiss button when `onClose` is set. Children are not matched by type, so wrapping a sub-component in `memo()` or your own component keeps its place.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Rendered in order inside the content row, typically `SystemAlert.Icon`, `SystemAlert.Description`, and `SystemAlert.Actions`. |
+| `color?` | `'danger' \| 'warning' \| 'success' \| 'info' \| 'brand'` | `'info'` | Colour treatment. Drives the surface, the default icon, and live-region urgency: `danger` and `warning` announce assertively, the rest politely. |
+| `asChild?` | `boolean` | — | Replace the root element with the consumer's child element via `Slot`. When `true`, children render as-is: no body row and no close button. The `color` context is still provided so sub-components receive the correct styles. |
+| `hasSafeAreaInset?` | `boolean` | `true` | Pad the top of the root by the top safe-area inset so the surface paints behind the status bar and the content row starts below it. Set `false` for a banner that does not sit at the top edge of the screen. The inset is zero on web and without a safe-area provider. |
+| `onClose?` | `(() => void)` | — | Renders a dismiss button as the last control in the row. |
+| `closeAccessibilityLabel?` | `string` | `'Dismiss alert'` | Accessible name for the dismiss button. |
+| `isOpen?` | `boolean` | — | Controlled presence. Omit it for a banner that shows while mounted, with no motion. When set, SystemAlert stays mounted and owns presence: `false` → `true` slides the banner down from the top edge and pushes the content below it, and `true` → `false` reverses that, then removes the surface. `true` on first render shows the banner in place without motion. While closed with `hasSafeAreaInset`, a transparent strip the height of the top inset stays reserved, so the header below never applies the inset. Pick one mode per mount: switching between omitted and set is not supported. |
+| `animation?` | `'disable-all'` | — | Pass `'disable-all'` to open and close in one frame, without motion. Has no effect without `isOpen`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute                 | danger / warning | success / info / brand |
+| ------------------------- | ---------------- | ---------------------- |
+| `role`                    | `alert`          | `status`               |
+| `accessibilityLiveRegion` | `assertive`      | `polite`               |
+
+The prop is `color`, not `severity`. This is a deliberate exception to the rule that props driving live-region urgency and icon selection are named `severity`. `brand` carries no urgency, so no severity value describes it, and `Toast` already uses `color` to choose both its icon and `role="alert"`. [`Alert`](https://design.candescent.com/docs/components/alert/content.md) keeps `severity`.
+
+## Sub-components
+
+### SystemAlert.Icon
+
+Leading glyph, hidden from assistive tech. Renders `EmergencyHome` for `danger`, `Warning` for `warning`, `CheckCircle` for `success`, `Info` for `info`, and `Error` for `brand`. Override with `as`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `ReactNode` | — | — |
+| `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `as?` | `ForgeIcon` | — | Override the default icon for the current `color` (`EmergencyHome`, `Warning`, `CheckCircle`, `Info`, or `Error` for `brand`). Not required when `asChild` is set. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+### SystemAlert.Description
+
+Message text in the banner's on-strong colour. It fills the space between the icon and the controls.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Message text. Wraps by default; pass `numberOfLines` to clamp it. With `isOpen` on the root, its plain text is what iOS announces when the banner opens, so it must be passed as children rather than resolved inside a child component. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props), including `numberOfLines`.
+
+### SystemAlert.Actions
+
+Row of trailing controls, placed after `SystemAlert.Description`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Typically `SystemAlert.Action` and `SystemAlert.IconAction`. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### SystemAlert.Action
+
+Text control rendered as a ghost, small [`Button`](https://design.candescent.com/docs/components/button/content.md), restyled so its label, hover, press, and focus ring stay legible on the strong surface. Children are wrapped in `Button.Label`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the button's own styles. |
+| `children?` | `ReactNode` | — | Label text, rendered inside `Button.Label`. |
+
+Inherits all `Button` props except `variant`, `color`, `size`, `fullWidth`, and `asChild`.
+
+### SystemAlert.IconAction
+
+Icon-only control rendered as a ghost, small [`IconButton`](https://design.candescent.com/docs/components/icon-button/content.md), restyled for the strong surface like `SystemAlert.Action`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode \| ((state: PressableStateCallbackType) => React.ReactNode)` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `as` | `ForgeIcon` | — | Forge icon component to render. |
+| `accessibilityLabel` | `string` | — | Accessible name. Required: the control has no visible text. |
+
+Inherits all `IconButton` props except `variant`, `color`, and `size`.
+
+## Hook
+
+### useSystemAlertStatusBarStyle
+
+Returns the status-bar glyph style, `'light'` or `'dark'`, that matches a banner's text on its strong surface in the active theme. Pass it to whatever owns the status bar, such as `expo-status-bar`'s `style`, React Native `StatusBar`'s `barStyle` (as `'light-content'` or `'dark-content'`), or your navigator's status-bar option:
+
+```tsx
+const statusBarStyle = useSystemAlertStatusBarStyle('danger');
+```
+
+| Argument | Type               | Description          |
+| -------- | ------------------ | -------------------- |
+| `color`  | `SystemAlertColor` | The banner's `color` |
+
+## Anatomy
+
+| `data-slot`                | Element                                        |
+| -------------------------- | ---------------------------------------------- |
+| `system-alert`             | Root surface                                   |
+| `system-alert-icon`        | Leading icon                                   |
+| `system-alert-description` | Message text                                   |
+| `system-alert-actions`     | Trailing controls row                          |
+| `system-alert-action`      | Text control                                   |
+| `system-alert-icon-action` | Icon-only control                              |
+| `system-alert-close`       | Dismiss button, rendered when `onClose` is set |
+
+## Constraints
+
+- Mount SystemAlert as the first child of the screen root, above the header. Inside a `SafeAreaView`, or below a header that applies its own top inset, the top inset is applied twice. Inside the page `ScrollView`, the banner scrolls away.
+- On a screen with a SystemAlert, the app header must not apply its own top inset. With `isOpen`, that holds while the banner is closed too, because the closed banner keeps the inset strip. If your navigator draws the header, turn its top inset off on that screen.
+- The app sets the native status-bar style; SystemAlert does not, and neither platform adapts the glyphs to the banner on its own. The glyphs sit on the banner's surface, so match them to the banner's text colour with [`useSystemAlertStatusBarStyle`](#usesystemalertstatusbarstyle). Light and dark mode give different answers: in dark mode every strong surface is pale and needs dark glyphs. Apply the style only while the banner is open and its screen is focused, so it does not leak onto other tabs or a modal flow.
+- Visibility is consumer-owned: SystemAlert never closes or dismisses itself. With `isOpen`, it animates open and closed in the document flow, never as an overlay. Without `isOpen`, it shows while mounted, and mounting or unmounting it moves the content below in one frame.
+- Choose one mode per mount: switching a mounted banner between omitting `isOpen` and setting it is not supported.
+- With `isOpen`, do not put margin classes on SystemAlert's `className`. The banner moves inside a clipping wrapper that cuts margins off; put spacing on a parent instead.
+- With `isOpen` on stacked banners, the inset stays with the top banner. If the top banner closes while the second stays open, the top banner's strip keeps the status-bar area and the second banner does not paint behind the status bar.
+- Motion turns off with Reduce Motion, `animation="disable-all"`, or a parent that disables animation, and the banner opens and closes in one frame.
+- On web, an app-shell layout (a fixed-height column with its own scroll container) behaves as on native: an opening banner pushes the header and shrinks the scroll area.
+- On a web page where the document scrolls, mount SystemAlert as the first child of the app root, above the layout.
+- On a document-scroll page, keep the header in flow or `sticky`, not `fixed`. Flow cannot push a `fixed` header or sidebar, so the banner opens underneath it.
+- On a document-scroll page, the push is visible only near the top of the page. Opened while the page is scrolled down, the browser keeps the visible content still and the banner opens out of view; screen readers still announce it.
+- Content spans the full width on wide screens. There is no max-width container.
+
+## When to use
+
+| Use `Alert` when…                                           | Use `SystemAlert` when…                                                                  |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| The message is about one section, form, or task on the page | The message applies to the whole app, such as a closure, an outage, or a required action |
+| It sits inline in the content, next to what it describes    | It sits at the top edge of the screen, above the header                                  |
+| It needs a separate title                                   | A single line of copy, with an optional bold lead-in, is enough                          |
+
+For brief confirmation of something the user just did, use [`Toast`](https://design.candescent.com/docs/components/toast/content.md).
+
+## Accessibility
+
+| Attribute                    | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Live region**              | `danger` and `warning` render `role="alert"` with an assertive live region and interrupt screen readers. `success`, `info`, and `brand` render `role="status"` with a polite live region.                                                                                                                                                                                                                                                                                        |
+| **Announcement on mount**    | A banner present when the screen first renders is not announced; live regions announce changes. Because it is the first element in reading order, screen reader users reach it first.                                                                                                                                                                                                                                                                                            |
+| **Announcement on open**     | With `isOpen`, opening announces the banner as it starts to slide, and focus does not move. iOS: SystemAlert announces the `SystemAlert.Description` text, interrupting speech for `danger` and `warning` and queuing it for the other colours. Android: the live region sits on a wrapper that stays mounted while closed, so TalkBack reads the opened banner as a change inside it. Web: inserting the `role="alert"` or `role="status"` surface announces it.                |
+| **Announcement text**        | iOS reads the plain text passed as `SystemAlert.Description` children, including nested `Text`. Text a child component resolves itself, such as a translation component that takes a key, cannot be read: the banner opens without an announcement, and a development-only warning is logged on iOS.                                                                                                                                                                             |
+| **Closed strip**             | The transparent inset strip of a closed controlled banner is not an accessibility element, so screen readers move straight to the header.                                                                                                                                                                                                                                                                                                                                        |
+| **Reading order**            | First in the accessibility tree, before the header. Each control is a separate focus stop, and the dismiss button comes last. There is no focus trap and no Escape handling.                                                                                                                                                                                                                                                                                                     |
+| **Dismiss button**           | Its label defaults to `Dismiss alert`; set `closeAccessibilityLabel` to change it.                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Dismissing**               | Consumer-owned. SystemAlert calls `onClose` and does not close itself. In `onClose`, move focus to a sensible target first, such as the control that opened the banner or the header's first control, then set `isOpen={false}`. When the exit starts, the banner is hidden from assistive tech and stops receiving touches and clicks. Chrome ignores `aria-hidden` on an element that still holds focus, so focus left on the dismiss button keeps the closing banner exposed. |
+| **Reduced motion**           | With Reduce Motion on, a controlled banner opens and closes in one frame. On iOS and Android this needs `ForgeDesignProvider`; on web, `prefers-reduced-motion` applies.                                                                                                                                                                                                                                                                                                         |
+| **Icon**                     | Decorative. The meaning of `color` must also be in the description.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **`SystemAlert.IconAction`** | `accessibilityLabel` is required, because the control has no visible text.                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **Truncation**               | `numberOfLines` only clips visually; the full description stays in the accessibility tree.                                                                                                                                                                                                                                                                                                                                                                                       |

package/docs/foundations/expressions/icons/content.md

@@ -3,7 +3,8 @@
 Cross-platform icon library for Forge UI, built on [Material Symbols](https://fonts.google.com/icons) (outlined style, weight 400, optical size 24). Renders via `react-native-svg` and targets iOS, Android, and Web.
 
 3,986 icons are available, each with outlined and filled variants, plus support for custom
-SVGs.
+SVGs. Country flags are a separate set and do not appear in the browser below. Render one with
+[`CountryFlag`](https://design.candescent.com/docs/components/country-flag/content.md).
 
 ```bash
 pnpm add @cdx-ui/icons

package/docs/foundations/styles/tokens/all-tokens/content.md

@@ -209,4 +209,5 @@ Data-visualization colors, used as `bg-*` utilities. Light and Dark name the pri
 | `chart.categorical.5` | `bg-chart-categorical-5` | Categorical, 5 | `color.purple.600` | `color.purple.600` |
 | `chart.categorical.6` | `bg-chart-categorical-6` | Categorical, 6 | `color.neutral.600` | `color.neutral.600` |
 | `chart.simple.primary` | `bg-chart-simple-primary` | Simple, primary | `color.brand.500` | `color.brand.500` |
-| `chart.simple.secondary` | `bg-chart-simple-secondary` | Simple, secondary | `color.brand.950` | `color.brand.950` |
+| `chart.simple.secondary` | `bg-chart-simple-secondary` | Simple, secondary | `color.brand.900` | `color.brand.900` |
+| `chart.simple.tertiary` | `bg-chart-simple-tertiary` | Simple, tertiary | `color.brand.700` | `color.brand.700` |

package/docs/getting-started/developers/content.md

@@ -93,7 +93,7 @@ Create `global.css` in your project root:
 - **`@custom-variant dark`** — Switches Tailwind v4's dark mode from `@media (prefers-color-scheme)` to class-based activation. Required for `ScopedTheme` to work on web. Harmless if you don't use `ScopedTheme` — global dark mode continues to work via `Uniwind.setTheme()`.
 - **`@cdx-ui/styles/theme.css`** — Design tokens (colors, spacing, radii, shadows, fonts) as a Tailwind v4 `@theme static` block, plus light/dark mode and platform font overrides via `@variant`.
 - **`@cdx-ui/styles/utilities.css`** — Composite typography utilities (`heading-xl`…`heading-xs`, `body-xl`…`body-xs`, `label-sm`, `label-xs`) used by `Heading`, `Text`, and `Link`. Each has a `-size` companion (`body-sm-size`) that sets only the font size, line height, and letter spacing, so nested text can change size and keep its inherited font family and weight.
-- **`@cdx-ui/components/styles.css`** — `@source` directive telling Tailwind where to scan for component utility classes.
+- **`@cdx-ui/components/styles.css`** — `@source` directive telling Tailwind where to scan for component utility classes. If you use `DataGrid`, also import `@cdx-ui/data-grid/styles.css`, which does the same for `@cdx-ui/data-grid`.
 
 > [!NOTE]
 >

package/docs/llms.txt

@@ -75,6 +75,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [Progress Bar](components/progress-bar/content.md): A continuous progress bar that visualizes determinate or indeterminate progress with a compound track and indicator. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4927-541), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progressbar--default)
   - [Progress Circle](components/progress-circle/content.md): A circular progress indicator that visualizes determinate or indeterminate progress with a compound ring and indicator. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=2616-182), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progresscircle--default)
   - [Progress Segmented](components/progress-segmented/content.md): A segmented progress bar that visualizes step-by-step completion as a row of discrete segments. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=449-449), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progresssegmented--default)
+  - [Stepper](components/stepper/content.md): A vertical or horizontal list of labeled steps that shows which step is current, which are complete, and how far each one has progressed. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/navigation-stepper--default)
   - [Skeleton](components/skeleton/content.md): A pulsing loading placeholder shaped via className — no intrinsic size, layout preserved while content loads. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=11476-16576), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-skeleton--default)
 
   - **Content display**
@@ -84,6 +85,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [Divider](components/divider/content.md): A horizontal or vertical separator for grouping related content, with an optional inline label. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=6771-8895), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-divider--default)
   - [Insurance Disclosure](components/insurance-disclosure/content.md): Domain-specific regulatory disclosure — official FDIC lockup with optional copy for account footers, deposit screens, and onboarding. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8550-3291), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/domain-insurancedisclosure--default)
   - [Icon](components/icon/content.md): A cross-platform SVG icon wrapper with semantic color, sizing, filled variants, and accessibility support. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=397-33), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-icon--default)
+  - [Country Flag](components/country-flag/content.md): A country flag rendered from an officially assigned ISO 3166-1 alpha-2 code. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-countryflag--default)
   - [Image](components/image/content.md): Displays local or remote images across native and web platforms. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=9091-16186), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-image--default)
   - [List Item](components/list-item/content.md): A composable row for display and navigation — accounts, transactions, alerts, settings, and nav rows. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=3710-4649), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-listitem--default)
   - [Reorderable List](components/reorderable-list/content.md): A short, mount-all list that lets members drag rows into a new order via an explicit handle. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-reorderablelist--default)
@@ -93,6 +95,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
 
   - **Feedback**
   - [Alert](components/alert/content.md): An inline severity banner that renders contextual feedback — danger, warning, success, or info — with an optional title, body, and trailing actions. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=6665-19536), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-alert--default)
+  - [System Alert](components/system-alert/content.md): A full-width, strong-surface banner at the top of the screen for app-wide messages such as closures, outages, and required actions. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8228-5936), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-systemalert--default)
   - [Alert Dialog](components/alert-dialog/content.md): A modal confirmation for destructive or important actions that requires an explicit response. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4428-496), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-alertdialog--default)
   - [Dialog](components/dialog/content.md): A modal overlay that interrupts the user with critical information or decisions requiring immediate attention. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4331-429), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-dialog--default) Design guidance: [design.md](components/dialog/design.md)
   - [Full Screen Dialog](components/full-screen-dialog/content.md): A modal page that covers the viewport with a back, title, and close header for single-step or multi-step tasks. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-fullscreendialog--default)
@@ -118,6 +121,11 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [Data Grid](components/data-grid/content.md): A web data grid with rows, columns, sort, filters, selection, and pagination. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/data-visualization-datagrid--default)
   - [Table](components/table/content.md): A presentational compound table for displaying tabular data with consistent Forge styling. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/data-visualization-table--default)
   - [Table Pagination](components/table-pagination/content.md): A compound pager for moving between pages of a list or table. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/navigation-tablepagination--default)
+
+  - **Charts**
+  - [Bar Chart](components/bar-chart/content.md): A vertical or horizontal bar chart for comparing categories, with grouped, stacked, overlay, and waterfall series. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/charts-barchart--default)
+  - [Line Chart](components/line-chart/content.md): A line or area chart for values over time, with per-series styling, dashed forecasts, and event markers. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/charts-linechart--default)
+  - [Pie Chart](components/pie-chart/content.md): A pie or donut chart for share-of-whole data, with a category legend, tooltip, and optional selection. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/charts-piechart--default)
 - Patterns
   - [Patterns](patterns/content.md): Reusable combinations of components that address common user experiences. Browse by category to find a ready-to-use pattern.
   - [Authentication](patterns/authentication/content.md): Login, signup, OTP verification, and biometric authentication screens.
@@ -126,6 +134,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [Onboarding](patterns/onboarding/content.md): Welcome screens, setup wizards, and guided first-run experiences.
   - [Settings](patterns/settings/content.md): User preferences, notification controls, and account settings.
   - [Dashboard](patterns/dashboard/content.md): Home screens, greetings, summaries, and at-a-glance views.
+  - [Insights](patterns/insights/content.md): Personalized insight cards that pair a headline with a chart, table, or actions.
   - [Forms](patterns/forms/content.md): Data entry patterns for personal info, addresses, and profile editing.
   - [Empty States](patterns/empty-states/content.md): Placeholder screens shown when content is not yet available.
 - Resources
@@ -133,6 +142,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
 
   - **Tools**
   - [Figma libraries](resources/figma-libraries/content.md): Access our official design system Figma libraries
+  - [Agent skills](resources/skills/content.md): Teach AI coding agents to build with Forge UI components as they ship, without restyling them.
 
   - **Changelogs**
   - Release notes
@@ -140,6 +150,8 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
 
 ## Release notes
 
+- [0.3.6](resources/release-notes/0.3.6/content.md): Adds SystemAlert, bar, line, and pie charts on a shared MUI X-shaped API, Stepper, and a fix for tabs scroll controls.
+- [0.3.5](resources/release-notes/0.3.5/content.md): Selected subtle Chip labels stay visible on Android when the variant changes from outline to subtle.
 - [0.3.4](resources/release-notes/0.3.4/content.md): Select adds multiple selection, in-list search, and a native bottom sheet; Input gains a subtle variant for fields inside popups and sheets.
 - [0.3.3](resources/release-notes/0.3.3/content.md): Insight and InsightStack add dismissible summary cards with status colors, optional AI styling, and stacked depth for insight feeds.
 - [0.3.2](resources/release-notes/0.3.2/content.md): CurrencyInput adds an outline variant for bordered amount fields; BottomSheet opens reliably in optimized web production builds.