@cdx-ui/components 0.3.6 → 0.3.7

package/docs/components/content.md

@@ -61,6 +61,7 @@
 - [Divider](https://design.candescent.com/docs/components/divider/content.md) — A horizontal or vertical separator for grouping related content, with an optional inline label.
 - [Insurance Disclosure](https://design.candescent.com/docs/components/insurance-disclosure/content.md) — Domain-specific regulatory disclosure — official FDIC lockup with optional copy for account footers, deposit screens, and onboarding.
 - [Icon](https://design.candescent.com/docs/components/icon/content.md) — A cross-platform SVG icon wrapper with semantic color, sizing, filled variants, and accessibility support.
+- [Country Flag](https://design.candescent.com/docs/components/country-flag/content.md) — A country flag rendered from an officially assigned ISO 3166-1 alpha-2 code.
 - [Image](https://design.candescent.com/docs/components/image/content.md) — Displays local or remote images across native and web platforms.
 - [List Item](https://design.candescent.com/docs/components/list-item/content.md) — A composable row for display and navigation — accounts, transactions, alerts, settings, and nav rows.
 - [Reorderable List](https://design.candescent.com/docs/components/reorderable-list/content.md) — A short, mount-all list that lets members drag rows into a new order via an explicit handle.

package/docs/components/country-flag/content.md

@@ -0,0 +1,232 @@
+# Country Flag (https://design.candescent.com/docs/components/country-flag)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-countryflag--default)
+
+`CountryFlag` renders a country's flag from an officially assigned ISO 3166-1 alpha-2 `code`.
+
+```tsx
+import { CountryFlag, Select } from '@cdx-ui/components';
+import { FlagUS } from '@cdx-ui/icons/flags';
+```
+
+Flags keep their source colors. Each path has an explicit fill, so text color classes and theme tokens do not recolor the artwork.
+
+An app that shows one fixed flag can import that component from `@cdx-ui/icons/flags` (`FlagUS`) instead of `CountryFlag`. `CountryFlag` pulls in the `flags` record and therefore every flag.
+
+## Basic
+
+Pass `code`. The default box is `size-5`.
+
+```tsx
+import { Box, CountryFlag, Text, type FlagCode } from '@cdx-ui/components';
+
+const examples: { code: FlagCode; name: string }[] = [
+  { code: 'US', name: 'United States' },
+  { code: 'CA', name: 'Canada' },
+  { code: 'GB', name: 'United Kingdom' },
+  { code: 'JP', name: 'Japan' },
+];
+
+export default function CountryFlagBasicDemo() {
+  return (
+    <Box className="flex-row items-end gap-5">
+      {examples.map((country) => (
+        <Box key={country.code} className="items-center gap-2">
+          <CountryFlag code={country.code} accessibilityLabel={country.name} />
+          <Text size="sm" color="secondary">
+            {country.code}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+A `size-*` class overrides the default box. The flag scales with the box. The default `size-5` box is 20 pixels.
+
+```tsx
+import { Box, CountryFlag, Text } from '@cdx-ui/components';
+
+const sizes = [
+  { className: 'size-4', label: '16' },
+  { className: 'size-5', label: '20' },
+  { className: 'size-6', label: '24' },
+  { className: 'size-8', label: '32' },
+  { className: 'size-10', label: '40' },
+] as const;
+
+export default function CountryFlagSizesDemo() {
+  return (
+    <Box className="flex-row items-end gap-5">
+      {sizes.map((size) => (
+        <Box key={size.className} className="items-center gap-2">
+          <CountryFlag code="US" className={size.className} />
+          <Text size="sm" color="secondary">
+            {size.label}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## With icons
+
+Place the flag in the leading slot of a [`Select`](https://design.candescent.com/docs/components/select/content.md). `position="leading"` emits `data-icon="inline-start"`, and the slot's size class wins over `size-5`. A small select uses `size-4`. The same flag works in an [`Input`](https://design.candescent.com/docs/components/input/content.md) through `Input.Icon` with `asChild`, which sizes the flag for both the default and small input. On that composed node, `data-slot` is `country-flag` and `data-icon` is kept.
+
+```tsx
+import { useState } from 'react';
+import {
+  Box,
+  CountryFlag,
+  Input,
+  Select,
+  Text,
+  type FlagCode,
+  type InputProps,
+  type SelectProps,
+} from '@cdx-ui/components';
+
+const countries: { value: FlagCode; label: string }[] = [
+  { value: 'US', label: 'United States (+1)' },
+  { value: 'CA', label: 'Canada (+1)' },
+  { value: 'GB', label: 'United Kingdom (+44)' },
+  { value: 'JP', label: 'Japan (+81)' },
+];
+
+function isListedCode(value: string): value is FlagCode {
+  return countries.some((country) => country.value === value);
+}
+
+function CountryCodeSelect({
+  size,
+  defaultCode,
+}: {
+  size: NonNullable<SelectProps['size']>;
+  defaultCode: FlagCode;
+}) {
+  const [code, setCode] = useState(defaultCode);
+
+  return (
+    <Select
+      items={countries}
+      size={size}
+      value={code}
+      onValueChange={(value) => {
+        if (isListedCode(value)) setCode(value);
+      }}
+      className="w-full"
+      accessibilityLabel="Country code"
+    >
+      <Select.Trigger>
+        <Select.Icon asChild position="leading">
+          <CountryFlag code={code} />
+        </Select.Icon>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {countries.map((country) => (
+          <Select.Item key={country.value} value={country.value}>
+            <CountryFlag code={country.value} />
+            <Select.ItemLabel>{country.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+
+function CountryInput({ size, code }: { size: NonNullable<InputProps['size']>; code: FlagCode }) {
+  return (
+    <Input size={size}>
+      <Input.Icon asChild>
+        <CountryFlag code={code} />
+      </Input.Icon>
+      <Input.Field accessibilityLabel={`${size} phone number`} placeholder="Phone number" />
+    </Input>
+  );
+}
+
+export default function CountryFlagWithIconsDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          default
+        </Text>
+        <CountryCodeSelect size="default" defaultCode="US" />
+        <CountryInput size="default" code="US" />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          small
+        </Text>
+        <CountryCodeSelect size="small" defaultCode="CA" />
+        <CountryInput size="small" code="CA" />
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Accessibility
+
+The flag is decorative unless `accessibilityLabel` is set. Omit the label when the country name or dialing code is already next to the flag.
+
+```tsx
+import { Box, CountryFlag, Text } from '@cdx-ui/components';
+
+export default function CountryFlagAccessibilityDemo() {
+  return (
+    <Box className="gap-5">
+      <Box className="flex-row items-center gap-3">
+        <CountryFlag code="US" accessibilityLabel="United States" />
+        <Text>Informative flag with a screen reader label</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <CountryFlag code="CA" />
+        <Text>Canada</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## API
+
+### CountryFlag
+
+Renders the flag for `code`. An unknown `code` renders nothing and logs a warning in development only. It does not throw.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `React.ReactNode` | — | — |
+| `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. |
+| `code` | `'AD' \| 'AE' \| 'AF' \| 'AG' \| 'AI' \| 'AL' \| 'AM' \| 'AO' \| 'AQ' \| 'AR' \| 'AS' \| 'AT' \| 'AU' \| 'AW' \| 'AX' \| 'AZ' \| 'BA' \| 'BB' \| 'BD' \| 'BE' \| 'BF' \| 'BG' \| 'BH' \| 'BI' \| 'BJ' \| 'BL' \| 'BM' \| 'BN' \| 'BO' \| 'BQ' \| 'BR' \| 'BS' \| 'BT' \| 'BV' \| 'BW' \| 'BY' \| 'BZ' \| 'CA' \| 'CC' \| 'CD' \| 'CF' \| 'CG' \| 'CH' \| 'CI' \| 'CK' \| 'CL' \| 'CM' \| 'CN' \| 'CO' \| 'CR' \| 'CU' \| 'CV' \| 'CW' \| 'CX' \| 'CY' \| 'CZ' \| 'DE' \| 'DJ' \| 'DK' \| 'DM' \| 'DO' \| 'DZ' \| 'EC' \| 'EE' \| 'EG' \| 'EH' \| 'ER' \| 'ES' \| 'ET' \| 'FI' \| 'FJ' \| 'FK' \| 'FM' \| 'FO' \| 'FR' \| 'GA' \| 'GB' \| 'GD' \| 'GE' \| 'GF' \| 'GG' \| 'GH' \| 'GI' \| 'GL' \| 'GM' \| 'GN' \| 'GP' \| 'GQ' \| 'GR' \| 'GS' \| 'GT' \| 'GU' \| 'GW' \| 'GY' \| 'HK' \| 'HM' \| 'HN' \| 'HR' \| 'HT' \| 'HU' \| 'ID' \| 'IE' \| 'IL' \| 'IM' \| 'IN' \| 'IO' \| 'IQ' \| 'IR' \| 'IS' \| 'IT' \| 'JE' \| 'JM' \| 'JO' \| 'JP' \| 'KE' \| 'KG' \| 'KH' \| 'KI' \| 'KM' \| 'KN' \| 'KP' \| 'KR' \| 'KW' \| 'KY' \| 'KZ' \| 'LA' \| 'LB' \| 'LC' \| 'LI' \| 'LK' \| 'LR' \| 'LS' \| 'LT' \| 'LU' \| 'LV' \| 'LY' \| 'MA' \| 'MC' \| 'MD' \| 'ME' \| 'MF' \| 'MG' \| 'MH' \| 'MK' \| 'ML' \| 'MM' \| 'MN' \| 'MO' \| 'MP' \| 'MQ' \| 'MR' \| 'MS' \| 'MT' \| 'MU' \| 'MV' \| 'MW' \| 'MX' \| 'MY' \| 'MZ' \| 'NA' \| 'NC' \| 'NE' \| 'NF' \| 'NG' \| 'NI' \| 'NL' \| 'NO' \| 'NP' \| 'NR' \| 'NU' \| 'NZ' \| 'OM' \| 'PA' \| 'PE' \| 'PF' \| 'PG' \| 'PH' \| 'PK' \| 'PL' \| 'PM' \| 'PN' \| 'PR' \| 'PS' \| 'PT' \| 'PW' \| 'PY' \| 'QA' \| 'RE' \| 'RO' \| 'RS' \| 'RU' \| 'RW' \| 'SA' \| 'SB' \| 'SC' \| 'SD' \| 'SE' \| 'SG' \| 'SH' \| 'SI' \| 'SJ' \| 'SK' \| 'SL' \| 'SM' \| 'SN' \| 'SO' \| 'SR' \| 'SS' \| 'ST' \| 'SV' \| 'SX' \| 'SY' \| 'SZ' \| 'TC' \| 'TD' \| 'TF' \| 'TG' \| 'TH' \| 'TJ' \| 'TK' \| 'TL' \| 'TM' \| 'TN' \| 'TO' \| 'TR' \| 'TT' \| 'TV' \| 'TW' \| 'TZ' \| 'UA' \| 'UG' \| 'UM' \| 'US' \| 'UY' \| 'UZ' \| 'VA' \| 'VC' \| 'VE' \| 'VG' \| 'VI' \| 'VN' \| 'VU' \| 'WF' \| 'WS' \| 'YE' \| 'YT' \| 'ZA' \| 'ZM' \| 'ZW'` | — | ISO 3166-1 alpha-2 country code. |
+
+Inherits [`SvgProps`](https://github.com/software-mansion/react-native-svg#common-props) except `color`, including `style` and `accessibilityLabel`. `as`, `filled`, and `color` are not accepted. `code` is the officially assigned ISO 3166-1 alpha-2 set, exported as `FlagCode` from `@cdx-ui/components` and `@cdx-ui/icons/flags`.
+
+## Defaults and styling
+
+- `className` defaults to a `size-5` box. Consumer classes are merged after that default, so a `size-*` utility overrides it.
+- Flag artwork keeps its source colors. Text color classes and theme tokens do not recolor it, because each path has an explicit fill.
+- Prefer a `size-*` class over the inherited numeric `size` prop. The numeric prop bypasses the spacing scale.
+
+## Anatomy
+
+| `data-slot`    | Element       |
+| -------------- | ------------- |
+| `country-flag` | Rendered flag |
+
+When `CountryFlag` is the child of `Select.Icon` with `asChild`, the rendered node keeps `data-slot="country-flag"`. `position="leading"` still sets `data-icon="inline-start"`, and `position="trailing"` sets `data-icon="inline-end"`. The select's icon size class replaces the default `size-5`. A small select uses `size-4`.
+
+## Accessibility
+
+- Without `accessibilityLabel`, the flag is decorative and hidden from assistive technology.
+- With `accessibilityLabel`, the flag is exposed as an image and announced with that label.

package/docs/components/data-grid/content.md

@@ -2,7 +2,7 @@
 
 Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/data-visualization-datagrid--default)
 
-`DataGrid` is a **web-only** data-driven grid. Install `@cdx-ui/data-grid` in addition to `@cdx-ui/components`. For fully custom markup use `Table`. For a standalone pager use `TablePagination`.
+`DataGrid` is a **web-only** data-driven grid. Install `@cdx-ui/data-grid` in addition to `@cdx-ui/components`, and add `@import '@cdx-ui/data-grid/styles.css';` after `@cdx-ui/components/styles.css` in your Tailwind CSS entry; without it the grid renders without its border, header background, or row dividers. For fully custom markup use `Table`. For a standalone pager use `TablePagination`.
 
 ```tsx
 import {
@@ -26,6 +26,8 @@ Search is **not** always on. Set `showToolbar` to show the search field (same op
 
 The grid is a fixed viewport like MUI Data Grid Community: **300px** tall by default. Column headers stay visible while rows scroll; pagination stays at the bottom. Override height with a `className` such as `h-full` or a spacing-scale height (`h-130`).
 
+Set `autoHeight` to size the grid to its rows instead, so a short table leaves no empty space below the last row. The grid then grows with every row on the page, so pair it with pagination for long data. The empty state keeps a minimum height.
+
 When `rows` is empty, a centered "No rows" message is shown and pagination is omitted. Pass `noRowsOverlay` to replace the default message.
 
 ```tsx

package/docs/components/icon/content.md

@@ -180,7 +180,7 @@ Inherits all `ForgeIconProps` except the SVG `color`: [`SvgProps`](https://githu
 - A raw `color` value, such as a hex string, is deprecated. It is passed to the SVG unchanged and logs a one-time warning in development. Use a semantic color instead.
 - `className` defaults to `size-5 shrink-0`, so an icon keeps its size in a row of text on web.
 - Consumer classes are merged after the defaults, so `size-*` and `shrink` utilities override them.
-- Don't pass the inherited numeric `size` prop; it bypasses the spacing scale. Use `size-4` or `size-6` when the default doesn't fit.
+- Don't pass the inherited numeric `size` prop; it bypasses the spacing scale. Use another `size-*` class on the spacing scale when the default doesn't fit.
 - `filled` defaults to `false`.
 
 ## Accessibility

package/docs/components/input/content.md

@@ -346,6 +346,7 @@ Renders a Forge icon sized to the input. Inherits size from the parent Input con
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `ReactNode` | — | The element rendered when `asChild` is set. |
 | `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. |

package/docs/components/progress-bar/content.md

@@ -47,6 +47,165 @@ export default function ProgressBarValuesDemo() {
 }
 ```
 
+## Sizes
+
+`default` is 6px tall; `large` is 8px. Size is set on the root and applied to the track.
+
+```tsx
+import { Box, ProgressBar, Text } from '@cdx-ui/components';
+
+export default function ProgressBarSizesDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      <Box className="gap-1.5">
+        <Text size="sm" color="secondary">
+          default
+        </Text>
+        <ProgressBar value={60} max={100} size="default" accessibilityLabel="Default size progress">
+          <ProgressBar.Indicator />
+        </ProgressBar>
+      </Box>
+      <Box className="gap-1.5">
+        <Text size="sm" color="secondary">
+          large
+        </Text>
+        <ProgressBar value={60} max={100} size="large" accessibilityLabel="Large size progress">
+          <ProgressBar.Indicator />
+        </ProgressBar>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Colors
+
+Severity colors use `surface-*-strong` fills. Categorical colors use `chart-categorical-*` so FI theme overrides flow through without a component change. The track is always `surface-neutral-subtle`.
+
+```tsx
+import { Box, ProgressBar, Text, type ProgressBarColor } from '@cdx-ui/components';
+
+const COLORS: readonly ProgressBarColor[] = [
+  'action',
+  'danger',
+  'warning',
+  'success',
+  'info',
+  'categorical-1',
+  'categorical-2',
+  'categorical-3',
+  'categorical-4',
+  'categorical-5',
+  'categorical-6',
+];
+
+export default function ProgressBarColorsDemo() {
+  return (
+    <Box className="w-full max-w-md gap-3">
+      {COLORS.map((color) => (
+        <Box key={color} className="gap-1.5">
+          <Text size="sm" color="secondary">
+            {color}
+          </Text>
+          <ProgressBar value={65} max={100} color={color} accessibilityLabel={`${color} progress`}>
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Indeterminate
+
+Pass `value={null}` for a segment that passes across the track until a value is known.
+
+```tsx
+import { ProgressBar } from '@cdx-ui/components';
+
+export default function ProgressBarIndeterminateDemo() {
+  return (
+    <ProgressBar value={null} accessibilityLabel="Loading">
+      <ProgressBar.Indicator />
+    </ProgressBar>
+  );
+}
+```
+
+## Budget rows
+
+Compose a label, percent, bar, and caption so status is clear in text, not by color alone.
+
+```tsx
+import { Box, HStack, ProgressBar, Text, type ProgressBarColor } from '@cdx-ui/components';
+
+interface BudgetRow {
+  readonly label: string;
+  readonly percent: number;
+  readonly caption: string;
+  readonly color: ProgressBarColor;
+}
+
+const ROWS: readonly BudgetRow[] = [
+  {
+    label: 'Dining',
+    percent: 80,
+    caption: '$320 of $400 — 10 days left',
+    color: 'categorical-1',
+  },
+  {
+    label: 'Groceries',
+    percent: 55,
+    caption: '$275 of $500 — on track',
+    color: 'categorical-2',
+  },
+  {
+    label: 'Transport',
+    percent: 95,
+    caption: '$190 of $200 — near limit',
+    color: 'warning',
+  },
+  {
+    label: 'Entertainment',
+    percent: 40,
+    caption: '$60 of $150 — under budget',
+    color: 'success',
+  },
+];
+
+export default function ProgressBarBudgetRowsDemo() {
+  return (
+    <Box className="w-full max-w-md gap-4">
+      {ROWS.map((row) => (
+        <Box key={row.label} className="gap-1.5">
+          <HStack space="sm" className="items-baseline justify-between">
+            <Text size="sm" weight="medium">
+              {row.label}
+            </Text>
+            <Text size="sm" color="secondary">
+              {row.percent}%
+            </Text>
+          </HStack>
+          <ProgressBar
+            value={row.percent}
+            max={100}
+            size="large"
+            color={row.color}
+            accessibilityLabel={`${row.label} budget ${String(row.percent)} percent used`}
+          >
+            <ProgressBar.Indicator />
+          </ProgressBar>
+          <Text size="sm" color="secondary">
+            {row.caption}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
 ## API
 
 ### ProgressBar
@@ -55,8 +214,10 @@ Sets `role="progressbar"` and `accessibilityRole="progressbar"`. Pass `value={nu
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `className?` | `string` | — | — |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the track's own styles. |
 | `children?` | `React.ReactNode` | — | — |
+| `size?` | `'default' \| 'large'` | `'default'` | Track height. Inherited by `ProgressBar.Indicator` via style context. |
+| `color?` | `'action' \| 'danger' \| 'warning' \| 'success' \| 'info' \| 'categorical-1' \| 'categorical-2' \| 'categorical-3' \| 'categorical-4' \| 'categorical-5' \| 'categorical-6'` | `'action'` | Indicator fill color. Inherited by `ProgressBar.Indicator` via style context. The track is always `surface-neutral-subtle`. |
 | `value?` | `number \| null` | `0` | Current value in the range `[0, max]`, or `null` for indeterminate progress. Values below `0` clamp to `0`; values above `max` clamp to `max`. Non-finite values (such as `NaN`) are treated as `0`. |
 | `max?` | `number` | `100` | Maximum value. The minimum is always `0`. A `max` of `0` or less is treated as complete. |
 | `getValueLabel?` | `((value: number, max: number) => string)` | — | Screen-reader text for determinate progress (`accessibilityValue.text`). Defaults to a rounded percentage of `max`, such as `"45%"`. No effect when `value` is `null`, or when `accessibilityValue` is set. |
@@ -73,11 +234,11 @@ Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
 
 ### ProgressBar.Indicator
 
-The filled portion of the track. Width is set automatically from `value / max`.
+The filled portion of the track. Width is set automatically from `value / max`. In indeterminate mode a partial segment passes across the track.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `className?` | `string` | — | — |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the indicator's own styles. |
 | `children?` | `React.ReactNode` | — | — |
 
 Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).

package/docs/components/select/content.md

@@ -644,6 +644,7 @@ Renders a Forge icon sized to the select. Use it as the `indicator` value when a
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `ReactNode` | — | The element rendered when `asChild` is set. |
 | `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. |

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/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

@@ -85,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)
@@ -141,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
@@ -148,6 +150,7 @@ 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.

package/docs/patterns/insights/content.md

@@ -391,7 +391,7 @@ export default function InsightsOverviewBlock() {
 
 ## Insight with Chart
 
-Dismissible insight cards that back their headline with a chart: a horizontal bar comparison with month-over-month change, and a cash-flow waterfall.
+Dismissible insight cards that back their headline with a chart: a horizontal bar comparison with month-over-month change, a cash-flow waterfall, and budget progress bars.
 
 **Platforms:** iOS, Android
 
@@ -399,11 +399,15 @@ Dismissible insight cards that back their headline with a chart: a horizontal ba
 import {
   BarChart,
   Button,
+  HStack,
+  Icon,
   Insight,
+  ProgressBar,
   Text,
   VStack,
   type ChartValueFormatter,
 } from '@cdx-ui/components';
+import { CheckCircle, Error } from '@cdx-ui/icons';
 import { FILL_WIDTH, formatUsd } from '../_utils';
 
 const SPENDING = [
@@ -516,11 +520,76 @@ function CashFlowInsight() {
   );
 }
 
+function BudgetInsight() {
+  return (
+    <Insight layout="detail" onClose={() => {}}>
+      <Insight.Tag>Budget</Insight.Tag>
+      <Insight.Header>
+        <Insight.Title>You’ve gone over your Entertainment budget this month</Insight.Title>
+        <Insight.Description>
+          Dining Out is close to its limit · <Text weight="bold">8 days left</Text>
+        </Insight.Description>
+      </Insight.Header>
+      <Insight.Content className="gap-4">
+        <VStack space="xs">
+          <HStack className="items-center justify-between">
+            <Text weight="semibold">Entertainment</Text>
+            <HStack space="xs" className="items-center">
+              <Icon as={Error} className="size-4 text-chart-categorical-2" />
+              <Text size="sm" weight="semibold">
+                $65 over
+              </Text>
+            </HStack>
+          </HStack>
+          <ProgressBar
+            value={100}
+            max={100}
+            size="large"
+            color="categorical-2"
+            accessibilityLabel="Entertainment budget, $65 over"
+          >
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </VStack>
+        <VStack space="xs">
+          <HStack className="items-center justify-between">
+            <Text weight="semibold">Dining Out</Text>
+            <Text size="sm" weight="medium" color="secondary">
+              $120 left
+            </Text>
+          </HStack>
+          <ProgressBar
+            value={73}
+            max={100}
+            size="large"
+            color="categorical-1"
+            accessibilityLabel="Dining Out budget, $120 left"
+          >
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </VStack>
+      </Insight.Content>
+      <Insight.Footer className="justify-between">
+        <HStack space="xs" className="shrink items-center">
+          <Icon as={CheckCircle} color="success" className="size-4" />
+          <Text size="sm" color="secondary">
+            3 other budgets on track
+          </Text>
+        </HStack>
+        <Button variant="outline" color="action" size="small">
+          <Button.Label>View budgets</Button.Label>
+        </Button>
+      </Insight.Footer>
+    </Insight>
+  );
+}
+
 export default function InsightChartBlock() {
   return (
     <VStack space="lg" className="w-full">
       <SpendingInsight />
       <CashFlowInsight />
+      <BudgetInsight />
     </VStack>
   );
 }

package/docs/resources/content.md

@@ -3,6 +3,7 @@
 ## Tools
 
 - [Figma libraries](https://design.candescent.com/docs/resources/figma-libraries/content.md) — Access our official design system Figma libraries
+- [Agent skills](https://design.candescent.com/docs/resources/skills/content.md) — Teach AI coding agents to build with Forge UI components as they ship, without restyling them.
 
 ## Changelogs