@cdx-ui/components 0.3.1 → 0.3.3

package/docs/components/insight/content.md

@@ -0,0 +1,644 @@
+# Insight (https://design.candescent.com/docs/components/insight)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=13158-18419), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-insight--default)
+
+A compound component with two layouts. A `summary` Insight is a single line of copy beside a Sparkle medallion, usually linking to a list of insights. A `detail` Insight on that list adds a category tag, a title, free content, and actions. Insight renders the medallion and the tag chip itself.
+
+```tsx
+import { Insight } from '@cdx-ui/components';
+```
+
+## Basic
+
+`layout` defaults to `summary`. Set `onPress` to make the whole card one press region. `onPress` exists only on the summary layout, where it is a type error on `detail`, and it is a plain callback: navigating to the insights screen is up to your app.
+
+```tsx
+import { Box, Insight } from '@cdx-ui/components';
+
+export default function InsightBasicDemo() {
+  return (
+    <Box className="w-full max-w-md">
+      <Insight onPress={() => {}}>
+        <Insight.Description>
+          Your spending this month is 12% lower than last month.
+        </Insight.Description>
+      </Insight>
+    </Box>
+  );
+}
+```
+
+## Detail
+
+Set `layout="detail"` for a static card. Write the category in `Insight.Tag`, the title and description in `Insight.Header`, free content such as a chart in `Insight.Content`, and actions in `Insight.Footer`. `Insight.Content`, `Insight.Footer`, and `onClose` are optional. A detail Insight without `Insight.Tag` logs a development warning.
+
+The tag overhangs the card's top edge. The detail layout adds a top margin to make room for it, so keep that space above the card and don't set `overflow-hidden` on the Insight or on a container that clips it.
+
+```tsx
+import { Box, Button, Insight, ProgressBar, Text } from '@cdx-ui/components';
+
+export default function InsightDetailDemo() {
+  return (
+    <Box className="w-full max-w-md">
+      <Insight layout="detail" onClose={() => {}}>
+        <Insight.Tag>Spending</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Dining is trending higher</Insight.Title>
+          <Insight.Description>
+            You have spent $320.00 of your $400.00 dining budget, with 10 days left this month.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Content className="gap-1.5">
+          <Text size="sm" color="secondary">
+            80% of budget used
+          </Text>
+          <ProgressBar value={80} max={100} accessibilityLabel="Dining budget used">
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </Insight.Content>
+        <Insight.Footer>
+          <Button variant="outline" size="small">
+            <Button.Label>View transactions</Button.Label>
+          </Button>
+          <Button size="small">
+            <Button.Label>Adjust budget</Button.Label>
+          </Button>
+        </Insight.Footer>
+      </Insight>
+    </Box>
+  );
+}
+```
+
+## Custom content
+
+`Insight.Content` takes any layout, such as budget bars, a short list of bills, or goal figures. It adds no padding or styling, so the card's `gap-4` spaces it from the header and footer. Keep the content to a glance: link to a full screen for anything longer.
+
+```tsx
+import { Box, Button, Divider, Insight, ProgressBar, Text } from '@cdx-ui/components';
+
+const categories = [
+  { name: 'Groceries', spent: '$412.30', percent: 82 },
+  { name: 'Dining', spent: '$268.75', percent: 54 },
+  { name: 'Transport', spent: '$96.40', percent: 19 },
+];
+
+const bills = [
+  { name: 'Electric', due: 'Due Oct 17', amount: '$96.20' },
+  { name: 'Phone', due: 'Due Oct 18', amount: '$65.00' },
+  { name: 'Car insurance', due: 'Due Oct 20', amount: '$251.28' },
+];
+
+export default function InsightCustomContentDemo() {
+  return (
+    <Box className="w-full max-w-md gap-6">
+      <Insight layout="detail">
+        <Insight.Tag>Spending</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Your top categories this month</Insight.Title>
+          <Insight.Description>Groceries make up almost half of your spending.</Insight.Description>
+        </Insight.Header>
+        <Insight.Content className="gap-3">
+          {categories.map((category) => (
+            <Box key={category.name} className="gap-1.5">
+              <Box className="flex-row justify-between">
+                <Text size="sm">{category.name}</Text>
+                <Text size="sm" weight="semibold">
+                  {category.spent}
+                </Text>
+              </Box>
+              <ProgressBar
+                value={category.percent}
+                max={100}
+                accessibilityLabel={`${category.name} budget used`}
+              >
+                <ProgressBar.Indicator />
+              </ProgressBar>
+            </Box>
+          ))}
+        </Insight.Content>
+        <Insight.Footer>
+          <Button variant="outline" size="small">
+            <Button.Label>See all spending</Button.Label>
+          </Button>
+        </Insight.Footer>
+      </Insight>
+      <Insight layout="detail" color="warning" onClose={() => {}}>
+        <Insight.Tag>Bills</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>3 bills are due this week</Insight.Title>
+          <Insight.Description>
+            They total $412.48, and your checking balance is $380.12.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Content>
+          {bills.map((bill, index) => (
+            <Box key={bill.name}>
+              {index > 0 ? <Divider /> : null}
+              <Box className="flex-row items-center justify-between py-2">
+                <Box>
+                  <Text size="sm" weight="medium">
+                    {bill.name}
+                  </Text>
+                  <Text size="xs" color="secondary">
+                    {bill.due}
+                  </Text>
+                </Box>
+                <Text size="sm" weight="semibold">
+                  {bill.amount}
+                </Text>
+              </Box>
+            </Box>
+          ))}
+        </Insight.Content>
+        <Insight.Footer>
+          <Button size="small">
+            <Button.Label>Transfer funds</Button.Label>
+          </Button>
+        </Insight.Footer>
+      </Insight>
+      <Insight layout="detail" aiGenerated>
+        <Insight.Tag>Goals</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Your vacation fund is 64% there</Insight.Title>
+          <Insight.Description>
+            At your current pace, you will reach your goal three weeks early.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Content className="gap-2">
+          <Box className="flex-row justify-between">
+            <Box>
+              <Text size="xs" color="secondary">
+                Saved
+              </Text>
+              <Text size="lg" weight="semibold">
+                $1,920.00
+              </Text>
+            </Box>
+            <Box className="items-end">
+              <Text size="xs" color="secondary">
+                Goal
+              </Text>
+              <Text size="lg" weight="semibold">
+                $3,000.00
+              </Text>
+            </Box>
+          </Box>
+          <ProgressBar value={64} max={100} accessibilityLabel="Vacation fund progress">
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </Insight.Content>
+      </Insight>
+    </Box>
+  );
+}
+```
+
+## Colors
+
+`color` tints the border, the medallion, and the tag. It is visual only, so any meaning it carries, such as a warning, must also be in the copy. FIs theme the border through the `stroke-info-subtle`, `stroke-warning-subtle`, and `stroke-danger-subtle` tokens. These tokens use the light values in dark mode until design supplies dark ones.
+
+```tsx
+import { Box, Insight } from '@cdx-ui/components';
+
+const examples = [
+  {
+    color: 'info',
+    tag: 'Income',
+    title: 'Your paycheck arrived early',
+    summary: 'Your paycheck usually arrives on Fridays.',
+    detail: '$2,450.00 was deposited to checking on Thursday.',
+  },
+  {
+    color: 'warning',
+    tag: 'Cash flow',
+    title: 'Your balance may run low',
+    summary: 'Your checking balance may run low before your next deposit.',
+    detail: 'Upcoming bills could bring checking below $50.00 before Friday.',
+  },
+  {
+    color: 'danger',
+    tag: 'Payment overdue',
+    title: 'Your card payment is overdue',
+    summary: 'Your credit card payment of $85.00 is overdue.',
+    detail: 'Pay $85.00 today to avoid a late fee.',
+  },
+] as const;
+
+export default function InsightColorsDemo() {
+  return (
+    <Box className="w-full max-w-md gap-6">
+      <Box className="gap-3">
+        {examples.map((example) => (
+          <Insight key={example.color} color={example.color} onPress={() => {}}>
+            <Insight.Description>{example.summary}</Insight.Description>
+          </Insight>
+        ))}
+      </Box>
+      <Box className="gap-4">
+        {examples.map((example) => (
+          <Insight key={example.color} layout="detail" color={example.color}>
+            <Insight.Tag>{example.tag}</Insight.Tag>
+            <Insight.Header>
+              <Insight.Title>{example.title}</Insight.Title>
+              <Insight.Description>{example.detail}</Insight.Description>
+            </Insight.Header>
+          </Insight>
+        ))}
+      </Box>
+    </Box>
+  );
+}
+```
+
+## AI-generated
+
+`aiGenerated` swaps the `color` border for a left-to-right gradient with a soft glow. The gradient does not mirror in right-to-left layouts. FIs theme its two stops through the `stroke-ai-start` and `stroke-ai-end` tokens.
+
+```tsx
+import { Box, Button, Insight } from '@cdx-ui/components';
+
+export default function InsightAiGeneratedDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      <Insight aiGenerated onPress={() => {}}>
+        <Insight.Description>
+          You could save $45.00 a month by moving two subscriptions to annual billing.
+        </Insight.Description>
+      </Insight>
+      <Insight aiGenerated color="warning" onPress={() => {}}>
+        <Insight.Description>
+          Your utility bills are 30% higher than this time last year.
+        </Insight.Description>
+      </Insight>
+      <Insight layout="detail" aiGenerated onClose={() => {}}>
+        <Insight.Tag>Savings</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Grow your emergency fund</Insight.Title>
+          <Insight.Description>
+            Setting aside $150.00 each payday would reach your savings goal by June.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Footer>
+          <Button size="small">
+            <Button.Label>Set up transfer</Button.Label>
+          </Button>
+        </Insight.Footer>
+      </Insight>
+    </Box>
+  );
+}
+```
+
+## Dismissible
+
+Set `onClose` to add a dismiss button at the top-end corner. On a pressable summary it sits beside the press region, not inside it. Insight does not remove itself: remove the item from your data in `onClose`, and move focus as described under Accessibility. Here, dismissing removes the insight from the list and moves focus to the next insight, or to the button after the list when none is left.
+
+```tsx
+import { useRef, useState, type ComponentRef } from 'react';
+import { Box, Button, Insight } from '@cdx-ui/components';
+
+const insights = [
+  { id: 'subscriptions', copy: 'You have three subscriptions renewing in the next seven days.' },
+  { id: 'dining', copy: 'Your dining spending is 20% higher than last month.' },
+  { id: 'savings', copy: 'You could save $45.00 a month with annual billing.' },
+];
+
+export default function InsightDismissibleDemo() {
+  const [visible, setVisible] = useState(insights);
+  const insightRefs = useRef(new Map<string, ComponentRef<typeof Insight>>());
+  const restoreRef = useRef<ComponentRef<typeof Button>>(null);
+
+  const dismiss = (id: string) => {
+    const index = visible.findIndex((insight) => insight.id === id);
+    const next = visible[index + 1] ?? visible[index - 1];
+    setVisible((current) => current.filter((insight) => insight.id !== id));
+    if (next) {
+      insightRefs.current.get(next.id)?.focus();
+    } else {
+      restoreRef.current?.focus();
+    }
+  };
+
+  return (
+    <Box className="w-full max-w-md gap-3">
+      {visible.map((insight) => (
+        <Insight
+          key={insight.id}
+          ref={(node) => {
+            if (node) {
+              insightRefs.current.set(insight.id, node);
+            } else {
+              insightRefs.current.delete(insight.id);
+            }
+          }}
+          onPress={() => {}}
+          onClose={() => dismiss(insight.id)}
+        >
+          <Insight.Description>{insight.copy}</Insight.Description>
+        </Insight>
+      ))}
+      <Box className="items-start">
+        <Button
+          ref={restoreRef}
+          variant="outline"
+          size="small"
+          onPress={() => setVisible(insights)}
+        >
+          <Button.Label>Restore insights</Button.Label>
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Text wrapping
+
+Long copy wraps and the card grows downward, while the medallion stays aligned with the first line. With `onClose`, the text leaves room for the dismiss button. Set `numberOfLines` on `Insight.Description` to truncate, and pass the full copy as the Insight's `accessibilityLabel` so screen readers still read all of it.
+
+```tsx
+import { Box, Insight } from '@cdx-ui/components';
+
+const longCopy =
+  'You spent $1,240.00 on dining out over the last three months, which is $310.00 more than the three months before and the highest it has been this year.';
+
+export default function InsightTextWrappingDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      <Insight onPress={() => {}}>
+        <Insight.Description>{longCopy}</Insight.Description>
+      </Insight>
+      <Insight onPress={() => {}} onClose={() => {}}>
+        <Insight.Description>{longCopy}</Insight.Description>
+      </Insight>
+      <Insight onPress={() => {}} accessibilityLabel={longCopy}>
+        <Insight.Description numberOfLines={2}>{longCopy}</Insight.Description>
+      </Insight>
+      <Insight layout="detail" onClose={() => {}}>
+        <Insight.Tag>Spending</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>
+            Dining out is your fastest-growing category for the third month in a row
+          </Insight.Title>
+          <Insight.Description>{longCopy}</Insight.Description>
+        </Insight.Header>
+      </Insight>
+    </Box>
+  );
+}
+```
+
+## List
+
+The screen a summary Insight links to lists detail Insights, mixing colors, AI-generated cards, and cards with or without content and actions. The detail layout's top margin already makes room for each tag, so a plain `gap` between cards is enough.
+
+```tsx
+import { Box, Button, Heading, Insight, ProgressBar, Text } from '@cdx-ui/components';
+
+export default function InsightListDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      <Box className="gap-0.5">
+        <Heading size="md">Insights</Heading>
+        <Text size="sm" color="secondary">
+          Updated today at 8:00 AM
+        </Text>
+      </Box>
+      <Insight layout="detail" aiGenerated>
+        <Insight.Tag>Subscriptions</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Save $45.00 a month</Insight.Title>
+          <Insight.Description>
+            Two of your streaming subscriptions offer a cheaper annual plan.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Footer>
+          <Button variant="ghost" size="small">
+            <Button.Label>Not now</Button.Label>
+          </Button>
+          <Button size="small">
+            <Button.Label>Review plans</Button.Label>
+          </Button>
+        </Insight.Footer>
+      </Insight>
+      <Insight layout="detail" color="warning">
+        <Insight.Tag>Cash flow</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Your balance may run low</Insight.Title>
+          <Insight.Description>
+            Upcoming bills could bring checking below $50.00 before your Friday deposit.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Footer>
+          <Button variant="outline" size="small">
+            <Button.Label>View forecast</Button.Label>
+          </Button>
+        </Insight.Footer>
+      </Insight>
+      <Insight layout="detail">
+        <Insight.Tag>Spending</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Dining is trending higher</Insight.Title>
+          <Insight.Description>
+            You have spent $320.00 of your $400.00 dining budget, with 10 days left this month.
+          </Insight.Description>
+        </Insight.Header>
+        <Insight.Content>
+          <ProgressBar value={80} max={100} accessibilityLabel="Dining budget used">
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </Insight.Content>
+      </Insight>
+      <Insight layout="detail">
+        <Insight.Tag>Income</Insight.Tag>
+        <Insight.Header>
+          <Insight.Title>Your paycheck arrived early</Insight.Title>
+          <Insight.Description>
+            $2,450.00 was deposited to checking on Thursday.
+          </Insight.Description>
+        </Insight.Header>
+      </Insight>
+    </Box>
+  );
+}
+```
+
+## States
+
+A summary without `onPress` is static and has no role. With `onPress`, it scales on press and shows a focus ring on keyboard focus on web. `isDisabled` dims the whole card and suppresses `onPress`; it does not disable the dismiss button.
+
+```tsx
+import { Box, Insight, Text } from '@cdx-ui/components';
+
+export default function InsightStatesDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Static
+        </Text>
+        <Insight>
+          <Insight.Description>Your paycheck usually arrives on Fridays.</Insight.Description>
+        </Insight>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Pressable
+        </Text>
+        <Insight onPress={() => {}}>
+          <Insight.Description>
+            Your spending this month is 12% lower than last month.
+          </Insight.Description>
+        </Insight>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <Insight onPress={() => {}} isDisabled>
+          <Insight.Description>
+            Insights are unavailable while your accounts sync.
+          </Insight.Description>
+        </Insight>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Insight
+
+Root card. `className` and `style` apply to the outer frame that paints the border. `layout` defaults to `summary` and is a discriminated union: `onPress`, `isDisabled`, `onPressIn`, `onPressOut`, `onHoverIn`, and `onHoverOut` type-check only with `layout="summary"`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `onPressIn?` | `((event: GestureResponderEvent) => void) \| null` | — | Called when a touch is engaged before `onPress`. |
+| `onPressOut?` | `((event: GestureResponderEvent) => void) \| null` | — | Called when a touch is released before `onPress`. |
+| `onHoverIn?` | `((event: MouseEvent) => void) \| null` | — | Called when the hover is activated to provide visual feedback. |
+| `onHoverOut?` | `((event: MouseEvent) => void) \| null` | — | Called when the hover is deactivated to undo visual feedback. |
+| `onPress?` | `((event: GestureResponderEvent) => void) \| null` | — | When set, the root renders a press region with `role="button"`. |
+| `isDisabled?` | `boolean` | — | Suppresses `onPress` and marks the press region disabled. |
+| `asChild?` | `boolean` | — | Merge props onto a single child instead of rendering `View` or `Pressable`. |
+| `color?` | `'info' \| 'warning' \| 'danger'` | `'info'` | Tints the border, the summary medallion, and the detail tag. Visual only: any meaning it carries must also be in the text. |
+| `aiGenerated?` | `boolean` | `false` | Swaps the `color` border for the AI gradient border. |
+| `onClose?` | `(() => void)` | — | Renders a dismiss button at the top-end corner. In `summary`, it sits beside the press region, not inside it. |
+| `closeAccessibilityLabel?` | `string` | `'Dismiss insight'` | Accessible name for the dismiss button. |
+| `layout?` | `'summary' \| 'detail'` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+Pressing a summary Insight with `onPress` scales the card to 0.98 and back. The scale is skipped when the device's reduce motion setting is on, or when `ForgeDesignProvider` sets `animation: 'disable-all'`.
+
+| Attribute            | Values            | Description                          |
+| -------------------- | ----------------- | ------------------------------------ |
+| `data-hover`         | `true` \| `false` | Hover (web, when pressable)          |
+| `data-active`        | `true` \| `false` | Pressed (when pressable)             |
+| `data-focus`         | `true` \| `false` | Focused (when pressable)             |
+| `data-focus-visible` | `true` \| `false` | Keyboard focus (web, when pressable) |
+| `data-disabled`      | `true` \| `false` | Disabled (when pressable)            |
+
+## Sub-components
+
+### Insight.Tag
+
+The detail layout's category text. Insight renders it as a Sparkle chip on the card's top edge, tinted by `color`, wherever it appears among the children.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Classes for the positioned tag wrapper. |
+| `children?` | `ReactNode` | — | The insight's category, read before the title. |
+| `asChild?` | `boolean` | — | Merges the label props onto a single text child instead of rendering `Text`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Insight.Header
+
+Groups the title and description in the detail layout.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Insight.Title
+
+Heading text. Leaves room for the dismiss button when `onClose` is set.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Insight.Description
+
+Body text. In the summary layout it is the card's copy. Insight does not truncate it; set `numberOfLines` if you need to.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Insight.Content
+
+Free content slot, such as a chart, in the detail layout. It adds no styling of its own.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Insight.Footer
+
+End-aligned row of actions. Buttons keep their natural width, and Insight does not pass its `color` to them.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`           | Element                                          |
+| --------------------- | ------------------------------------------------ |
+| `insight-frame`       | Outer frame that paints the border               |
+| `insight`             | Card surface; carries the interaction attributes |
+| `insight-icon`        | Summary Sparkle medallion (internal, decorative) |
+| `insight-tag`         | Detail category chip                             |
+| `insight-header`      | Title and description group                      |
+| `insight-title`       | Title                                            |
+| `insight-description` | Description                                      |
+| `insight-content`     | Free content                                     |
+| `insight-footer`      | Actions row                                      |
+| `insight-close`       | Dismiss button, rendered when `onClose` is set   |
+
+## Accessibility
+
+| Attribute          | Behavior                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Summary**        | With `onPress`, the press region has the button role and takes its name from its text. Set `accessibilityLabel` when the text alone doesn't describe it. The Sparkle medallion is hidden from assistive tech.                                                                                                                                                                                   |
+| **Detail**         | No root role. `Insight.Title` has the heading role. `Insight.Tag` is plain text and is always read before the title, wherever it is written among the children.                                                                                                                                                                                                                                 |
+| **Dismiss button** | A separate focus stop. On a pressable summary it follows the press region and is never nested inside it; on a detail card it follows the content. Its label defaults to `Dismiss insight`; set `closeAccessibilityLabel` to change it.                                                                                                                                                          |
+| **Dismissing**     | Consumer-owned. Insight calls `onClose` and does not remove itself. After you remove the item, move focus to a sensible target, such as the next insight or the list heading, or it is lost. On a summary with `onPress`, `ref` points at the press region, so calling `focus()` on the next insight's `ref` moves focus to it. On a static Insight, `ref` points at its non-focusable surface. |
+| **Live region**    | None. Insights render with the screen, often several at once, so none of them is announced. Use [`Alert`](https://design.candescent.com/docs/components/alert/content.md) or [`Toast`](https://design.candescent.com/docs/components/toast/content.md) for messages that must be announced.                                                                                                                           |
+| **`color`**        | Visual only. Any meaning it carries must also be in the tag, title, or description.                                                                                                                                                                                                                                                                                                             |
+| **`aiGenerated`**  | Visual only. It changes the border and adds nothing to the accessibility tree.                                                                                                                                                                                                                                                                                                                  |