@cdx-ui/components 0.2.4 → 0.3.0

package/docs/components/tabs/content.md

@@ -15,7 +15,7 @@ import { Tabs, Text } from '@cdx-ui/components';
 
 export default function TabsBasicDemo() {
   return (
-    <Tabs defaultValue="overview" className="w-[360px]">
+    <Tabs defaultValue="overview" className="w-full max-w-90">
       <Tabs.List accessibilityLabel="Account sections">
         <Tabs.Tab value="overview">
           <Tabs.TabLabel>Overview</Tabs.TabLabel>
@@ -50,7 +50,7 @@ import { Box, Tabs, Text } from '@cdx-ui/components';
 
 export default function TabsVariantsDemo() {
   return (
-    <Box className="w-[360px] gap-8">
+    <Box className="w-full max-w-90 gap-8">
       <Tabs defaultValue="checking">
         <Tabs.List accessibilityLabel="Solid account tabs">
           <Tabs.Tab value="checking">
@@ -60,10 +60,10 @@ export default function TabsVariantsDemo() {
             <Tabs.TabLabel>Savings</Tabs.TabLabel>
           </Tabs.Tab>
         </Tabs.List>
-        <Tabs.Panel value="checking" className="pt-3">
+        <Tabs.Panel value="checking" className="mt-3">
           <Text>Solid (default)</Text>
         </Tabs.Panel>
-        <Tabs.Panel value="savings" className="pt-3">
+        <Tabs.Panel value="savings" className="mt-3">
           <Text>Savings account</Text>
         </Tabs.Panel>
       </Tabs>
@@ -77,10 +77,10 @@ export default function TabsVariantsDemo() {
             <Tabs.TabLabel>Savings</Tabs.TabLabel>
           </Tabs.Tab>
         </Tabs.List>
-        <Tabs.Panel value="checking" className="pt-3">
+        <Tabs.Panel value="checking" className="mt-3">
           <Text>Outline</Text>
         </Tabs.Panel>
-        <Tabs.Panel value="savings" className="pt-3">
+        <Tabs.Panel value="savings" className="mt-3">
           <Text>Savings account</Text>
         </Tabs.Panel>
       </Tabs>
@@ -102,7 +102,12 @@ function VerticalTabs({ variant }: { variant: TabsVariant }) {
       <Text weight="semibold" className="capitalize">
         {variant}
       </Text>
-      <Tabs defaultValue="profile" orientation="vertical" variant={variant} className="w-105">
+      <Tabs
+        defaultValue="profile"
+        orientation="vertical"
+        variant={variant}
+        className="w-full max-w-105"
+      >
         <Tabs.List accessibilityLabel={`${variant} settings sections`}>
           <Tabs.Tab value="profile">
             <Tabs.TabLabel>Profile</Tabs.TabLabel>
@@ -149,7 +154,7 @@ const sections = ['Overview', 'Activity', 'Statements', 'Settings', 'Security',
 
 export default function TabsOverflowDemo() {
   return (
-    <Tabs defaultValue="overview" className="w-[360px]">
+    <Tabs defaultValue="overview" className="w-90">
       <Tabs.List accessibilityLabel="Account sections">
         {sections.map((section) => {
           const value = section.toLowerCase();
@@ -184,7 +189,7 @@ import { Tabs, Text } from '@cdx-ui/components';
 
 export default function TabsDisabledDemo() {
   return (
-    <Tabs defaultValue="open" className="w-[360px]">
+    <Tabs defaultValue="open" className="w-full max-w-90">
       <Tabs.List accessibilityLabel="Request status">
         <Tabs.Tab value="open">
           <Tabs.TabLabel>Open</Tabs.TabLabel>

package/docs/components/tile/content.md

@@ -14,14 +14,14 @@ import { Tile } from '@cdx-ui/components';
 
 ```tsx
 import { useState } from 'react';
-import { Tile, View } from '@cdx-ui/components';
+import { Box, Tile } from '@cdx-ui/components';
 
 export default function TileShapesDemo() {
   const [card, setCard] = useState('checking');
   const [flat, setFlat] = useState('checking');
 
   return (
-    <View className="w-full max-w-md gap-6">
+    <Box className="w-full max-w-md gap-6">
       <Tile.Group
         type="single"
         shape="card"
@@ -67,7 +67,7 @@ export default function TileShapesDemo() {
           <Tile.Indicator />
         </Tile>
       </Tile.Group>
-    </View>
+    </Box>
   );
 }
 ```
@@ -95,7 +95,7 @@ export default function TileCardDemo() {
     >
       <Tile value="checking">
         <Tile.LeadingSlot>
-          <Avatar size="md">
+          <Avatar>
             <Avatar.Icon as={Person} />
           </Avatar>
         </Tile.LeadingSlot>
@@ -107,7 +107,7 @@ export default function TileCardDemo() {
       </Tile>
       <Tile value="savings">
         <Tile.LeadingSlot>
-          <Avatar size="md">
+          <Avatar>
             <Avatar.Icon as={Person} />
           </Avatar>
         </Tile.LeadingSlot>
@@ -409,7 +409,6 @@ export default function TileStandaloneDemo() {
   return (
     <Tile
       value="terms"
-      shape="card"
       isSelected={agreed}
       onSelectedChange={setAgreed}
       className="w-full max-w-md"
@@ -447,7 +446,7 @@ export default function TileWithTrailingDemo() {
     >
       <Tile value="checking">
         <Tile.LeadingSlot>
-          <Avatar size="md">
+          <Avatar>
             <Avatar.Icon as={Person} />
           </Avatar>
         </Tile.LeadingSlot>
@@ -462,7 +461,7 @@ export default function TileWithTrailingDemo() {
       </Tile>
       <Tile value="savings">
         <Tile.LeadingSlot>
-          <Avatar size="md">
+          <Avatar>
             <Avatar.Icon as={Person} />
           </Avatar>
         </Tile.LeadingSlot>
@@ -499,7 +498,7 @@ export default function TileDisabledDemo() {
     >
       <Tile value="open">
         <Tile.LeadingSlot>
-          <Avatar size="md">
+          <Avatar>
             <Avatar.Icon as={Person} />
           </Avatar>
         </Tile.LeadingSlot>
@@ -511,7 +510,7 @@ export default function TileDisabledDemo() {
       </Tile>
       <Tile value="closed" disabled>
         <Tile.LeadingSlot>
-          <Avatar size="md">
+          <Avatar>
             <Avatar.Icon as={Person} />
           </Avatar>
         </Tile.LeadingSlot>

package/docs/components/toggle-button/content.md

@@ -314,7 +314,7 @@ export default function ToggleButtonControlledDemo() {
           Everyday Checking ••4821
         </Text>
         {hideBalance ? (
-          <Heading size="lg" accessibilityLabel="Balance hidden" className="py-0.5">
+          <Heading accessibilityLabel="Balance hidden" className="my-0.5">
             $•,•••.••
           </Heading>
         ) : (

package/docs/components/tooltip/content.md

@@ -19,7 +19,7 @@ export default function TooltipBasicDemo() {
   return (
     <Tooltip>
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>Hover for tooltip</Button.Label>
         </Button>
       </Tooltip.Trigger>
@@ -43,7 +43,7 @@ export default function TooltipWithoutArrowDemo() {
   return (
     <Tooltip>
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>Hover me</Button.Label>
         </Button>
       </Tooltip.Trigger>
@@ -64,7 +64,7 @@ export default function TooltipFocusTriggerDemo() {
   return (
     <Tooltip trigger="focus">
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>Focus me</Button.Label>
         </Button>
       </Tooltip.Trigger>
@@ -88,7 +88,7 @@ export default function TooltipClickTriggerDemo() {
   return (
     <Tooltip trigger="click">
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>Click for tooltip</Button.Label>
         </Button>
       </Tooltip.Trigger>
@@ -118,7 +118,7 @@ function PlacementExample({
   return (
     <Tooltip placement={placement}>
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>{label}</Button.Label>
         </Button>
       </Tooltip.Trigger>
@@ -184,7 +184,7 @@ export default function TooltipCustomTriggersDemo() {
   return (
     <Box className="items-start gap-8">
       <CustomTriggerRow label="Avatar" content="Account owner profile">
-        <Avatar size="md">
+        <Avatar>
           <Avatar.Image src="https://www.loremfaces.net/128/id/1.jpg" />
           <Avatar.Text>Jane Doe</Avatar.Text>
         </Avatar>
@@ -209,7 +209,7 @@ export default function TooltipCustomTriggersDemo() {
       </CustomTriggerRow>
 
       <CustomTriggerRow label="Button" content="Initiate a funds transfer">
-        <Button color="action" variant="outline">
+        <Button variant="outline">
           <Button.Label>Transfer</Button.Label>
         </Button>
       </CustomTriggerRow>
@@ -229,7 +229,7 @@ export default function TooltipDelayDemo() {
   return (
     <Tooltip enterDelay={500} leaveDelay={300}>
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>Delayed tooltip</Button.Label>
         </Button>
       </Tooltip.Trigger>
@@ -253,7 +253,7 @@ export default function TooltipDisabledDemo() {
   return (
     <Tooltip isDisabled>
       <Tooltip.Trigger asChild>
-        <Button variant="solid" color="action">
+        <Button>
           <Button.Label>Disabled tooltip</Button.Label>
         </Button>
       </Tooltip.Trigger>

package/docs/components/virtualized-list/content.md

@@ -27,7 +27,7 @@ export default function VirtualizedListBasicDemo() {
             ItemSeparatorComponent={() => <Divider />}
             renderItem={({ item }) => (
               <Box className="flex-row items-center gap-3 px-4 py-3">
-                <Avatar size="md">
+                <Avatar>
                   <Avatar.Text>{item.name.slice(0, 2)}</Avatar.Text>
                 </Avatar>
                 <Box className="flex-1 gap-0.5">
@@ -84,7 +84,7 @@ export default function VirtualizedListEmptyDemo() {
 `ListHeaderComponent` and `ListFooterComponent` render above and below the scrollable items.
 
 ```tsx
-import { Avatar, Box, Card, Divider, Text, VirtualizedList } from '@cdx-ui/components';
+import { Avatar, Box, Card, Divider, ListItem, Text, VirtualizedList } from '@cdx-ui/components';
 import { CONTACTS } from './_data';
 
 export default function VirtualizedListHeaderFooterDemo() {
@@ -112,17 +112,17 @@ export default function VirtualizedListHeaderFooterDemo() {
               </Box>
             }
             renderItem={({ item }) => (
-              <Box className="flex-row items-center gap-3 px-4 py-3">
-                <Avatar size="md">
-                  <Avatar.Text>{item.name.slice(0, 2)}</Avatar.Text>
-                </Avatar>
-                <Box className="flex-1 gap-0.5">
-                  <Text weight="semibold">{item.name}</Text>
-                  <Text color="secondary" size="sm">
-                    {item.role}
-                  </Text>
-                </Box>
-              </Box>
+              <ListItem showSeparator={false}>
+                <ListItem.LeadingSlot>
+                  <Avatar>
+                    <Avatar.Text>{item.name.slice(0, 2)}</Avatar.Text>
+                  </Avatar>
+                </ListItem.LeadingSlot>
+                <ListItem.Content>
+                  <ListItem.Title>{item.name}</ListItem.Title>
+                  <ListItem.Description>{item.role}</ListItem.Description>
+                </ListItem.Content>
+              </ListItem>
             )}
           />
         </Card.Content>
@@ -163,7 +163,7 @@ export default function VirtualizedListWithListItemDemo() {
             renderItem={({ item, index }) => (
               <ListItem onPress={() => undefined} showSeparator={index < transactions.length - 1}>
                 <ListItem.LeadingSlot>
-                  <Avatar size="md">
+                  <Avatar>
                     <Avatar.Text>{item.title.slice(0, 2).toUpperCase()}</Avatar.Text>
                   </Avatar>
                 </ListItem.LeadingSlot>

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

@@ -228,7 +228,6 @@ Components carry their own look, so the example sets no colors or typography. Be
 
 ```tsx
 import {
-  View,
   ScrollView,
   KeyboardAvoidingView,
   SafeAreaView,
@@ -238,12 +237,13 @@ import {
 
 | Export                 | Source                           |
 | ---------------------- | -------------------------------- |
-| `View`                 | `react-native`                   |
 | `ScrollView`           | `react-native`                   |
 | `KeyboardAvoidingView` | `react-native`                   |
 | `SafeAreaView`         | `react-native-safe-area-context` |
 | `useSafeAreaInsets`    | `react-native-safe-area-context` |
 
+`View` is also still exported but is deprecated — use `Box` for layout containers.
+
 These are convenience re-exports of the underlying packages — not Uniwind wrappers. `className` works on RN views when Uniwind's Metro pipeline is configured; importing from `@cdx-ui/components` vs `react-native` does not change that.
 
 ---

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

@@ -72,7 +72,7 @@ Every component's API table lists the props that choose its look. Reach for them
 > **Text on a colored surface**
 >
 > The `text-content-*-on-strong` and `text-content-*-on-subtle` tokens have no prop. Use them as a
-> class only when your own code paints the surface underneath, such as a `View` with
+> class only when your own code paints the surface underneath, such as a `Box` with
 > `bg-surface-action-strong`. For a status message use `Alert`; for a dark section use
 > `ScopedTheme`.
 
@@ -102,7 +102,7 @@ Padding, backgrounds, borders, radii, colors, typography and heights are not all
 
 ## Lay out screens with layout primitives
 
-`View`, `ScrollView`, `SafeAreaView`, `KeyboardAvoidingView`, `HStack` and `VStack` have no look of their own. They can take layout classes (`flex-row`, `items-center`, `justify-between`, `flex-wrap`), padding on the spacing scale, and a semantic surface background (`bg-surface-*`). On `HStack` and `VStack`, set the gap between children with `space`, not `gap-*`.
+`Box`, `HStack`, `VStack`, `ScrollView`, `SafeAreaView` and `KeyboardAvoidingView` have no look of their own. They can take layout classes (`flex-row`, `items-center`, `justify-between`, `flex-wrap`), padding on the spacing scale, and a semantic surface background (`bg-surface-*`). `Box` is the general-purpose container: use it wherever you would reach for a `View`. On `HStack` and `VStack`, set the gap between children with `space`, not `gap-*`.
 
 ```tsx
 // Wrong: a react-native View with pixel values
@@ -118,7 +118,7 @@ import { VStack } from '@cdx-ui/components';
 </VStack>;
 ```
 
-Don't add a `View` or a stack that does nothing. If a design's spacing doesn't match a component's default, keep the default and raise the difference with whoever owns the design.
+Don't add a `Box` or a stack that does nothing. If a design's spacing doesn't match a component's default, keep the default and raise the difference with whoever owns the design.
 
 ## Use semantic tokens
 
@@ -140,9 +140,9 @@ Wrap a dark or inverse section in [`ScopedTheme`](https://design.candescent.com/
 
 ```tsx
 // Wrong
-<View className="bg-black">
+<Box className="bg-black">
   <Text className="text-white">Premium rewards</Text>
-</View>
+</Box>
 
 // Right
 <ScopedTheme theme="dark">
@@ -156,7 +156,8 @@ Wrap a dark or inverse section in [`ScopedTheme`](https://design.candescent.com/
 
 ## Imports
 
-- Import `View`, `ScrollView`, `SafeAreaView` and `KeyboardAvoidingView` from `@cdx-ui/components`, not from `react-native`.
+- Use `Box` in place of `View`. `View` from `react-native` is not part of the Forge UI API, and the `View` export of `@cdx-ui/components` is deprecated.
+- Import `ScrollView`, `SafeAreaView` and `KeyboardAvoidingView` from `@cdx-ui/components`, not from `react-native`.
 - Don't wrap Forge UI components with `withUniwind`; they already accept `className`.
 - Don't import from `@cdx-ui/primitives` or from deep paths inside a package. Only the public entry points are a stable API across releases.
 - Merge class names with `cn` from `@cdx-ui/utils`.
@@ -179,15 +180,16 @@ When generating or reviewing code:
 - When a rule blocks the design, don't work around it. Apply the closest variant, leave the `TODO`, and tell the person you're working for what's missing.
 - Review your own output for these patterns before you finish:
 
-| Pattern                                                                                     | Fix                                                          |
-| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `text-content-*`, `body-*` or `font-*` classes on `Text` or `Icon`                          | Use the `color`, `size` and `weight` props                   |
-| Padding, background, border, radius or height classes on a Forge UI component or its parts  | Remove them. Use props, or move layout to a layout primitive |
-| `style={...}` on a Forge UI component                                                       | Remove it. Use props or placement classes                    |
-| Primitive tokens, hex or rgb values, `white`, `black`, or `[...]` values                    | Use a semantic token                                         |
-| `text-left` or `text-right`                                                                 | Use `text-start` or `text-end`                               |
-| `View`, `ScrollView`, `SafeAreaView` or `KeyboardAvoidingView` imported from `react-native` | Import it from `@cdx-ui/components`                          |
-| Imports from `@cdx-ui/primitives` or a deep package path                                    | Import from the package's public entry point                 |
-| `withUniwind` around a Forge UI component                                                   | Remove the wrapper                                           |
-| A dark section built from `bg-black` and `text-white`                                       | Use `ScopedTheme`                                            |
-| A default restated, such as `color="primary"` or `size-5` on `Icon`                         | Remove it                                                    |
+| Pattern                                                                                    | Fix                                                          |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
+| `text-content-*`, `body-*` or `font-*` classes on `Text` or `Icon`                         | Use the `color`, `size` and `weight` props                   |
+| Padding, background, border, radius or height classes on a Forge UI component or its parts | Remove them. Use props, or move layout to a layout primitive |
+| `style={...}` on a Forge UI component                                                      | Remove it. Use props or placement classes                    |
+| Primitive tokens, hex or rgb values, `white`, `black`, or `[...]` values                   | Use a semantic token                                         |
+| `text-left` or `text-right`                                                                | Use `text-start` or `text-end`                               |
+| `View` imported from `react-native` or `@cdx-ui/components`                                | Use `Box`                                                    |
+| `ScrollView`, `SafeAreaView` or `KeyboardAvoidingView` imported from `react-native`        | Import it from `@cdx-ui/components`                          |
+| Imports from `@cdx-ui/primitives` or a deep package path                                   | Import from the package's public entry point                 |
+| `withUniwind` around a Forge UI component                                                  | Remove the wrapper                                           |
+| A dark section built from `bg-black` and `text-white`                                      | Use `ScopedTheme`                                            |
+| A default restated, such as `color="primary"` or `size-5` on `Icon`                        | Remove it                                                    |

package/docs/llms.txt

@@ -49,12 +49,12 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [Select](components/select/content.md): A form control that allows users to choose one option from a dropdown list. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=427-2296), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-select--default) Design guidance: [design.md](components/select/design.md)
   - [Textarea](components/textarea/content.md): A multi-line text entry for longer free-form content. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=7078-1235), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-textarea--default)
   - [Slider](components/slider/content.md): A control for selecting a numeric value along a track. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=11500-17763), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-slider--default)
-  - [ColorPicker](components/color-picker/content.md): A compound color picker that coordinates an opaque color value with a trigger and popover. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorpicker--default)
-  - [ColorArea](components/color-area/content.md): A two-dimensional control for selecting saturation and brightness in the HSB color space. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorarea--default)
-  - [ColorSlider](components/color-slider/content.md): A one-dimensional control for selecting a channel from an opaque RGB, HSL, or HSB color. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorslider--default)
-  - [ColorField](components/color-field/content.md): A text field for editing an opaque color or one RGB or HSL channel. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorfield--default)
-  - [ColorSwatch](components/color-swatch/content.md): A presentational sample of an opaque color in configurable sizes and shapes. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorswatch--default)
-  - [ColorSwatchPicker](components/color-swatch-picker/content.md): A radio-style compound for choosing from consumer-supplied color presets. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorswatchpicker--default)
+  - [Color Picker](components/color-picker/content.md): A compound color picker that coordinates an opaque color value with a trigger and popover. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorpicker--default)
+  - [Color Area](components/color-area/content.md): A two-dimensional control for selecting saturation and brightness in the HSB color space. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorarea--default)
+  - [Color Slider](components/color-slider/content.md): A one-dimensional control for selecting a channel from an opaque RGB, HSL, or HSB color. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorslider--default)
+  - [Color Field](components/color-field/content.md): A text field for editing an opaque color or one RGB or HSL channel. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorfield--default)
+  - [Color Swatch](components/color-swatch/content.md): A presentational sample of an opaque color in configurable sizes and shapes. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorswatch--default)
+  - [Color Swatch Picker](components/color-swatch-picker/content.md): A radio-style compound for choosing from consumer-supplied color presets. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-colorswatchpicker--default)
   - [Switch](components/switch/content.md): A toggle control that lets users turn a single option on or off. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=308-19827), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-switch--default) Design guidance: [design.md](components/switch/design.md)
   - [Tile](components/tile/content.md): A composable, selectable card/row for pick-one or pick-many flows such as account pickers and category selectors. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8843-7101), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-tile--default)
 
@@ -86,7 +86,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [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)
   - [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)
-  - [ReorderableList](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)
+  - [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)
   - [Virtualized List](components/virtualized-list/content.md): A performant virtualized list for large datasets — only visible rows mount at a time. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4040-4933), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-virtualizedlist--large-data-set)
   - [Text](components/text/content.md): Body text with a responsive, token-based typography scale. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=400-3), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-text--default)
   - [Heading](components/heading/content.md): Semantic heading text with an accessible, token-based typography scale. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=399-3385), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-heading--default)
@@ -101,10 +101,11 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
 
   - **Surfaces & layout**
   - [Bottom Sheet](components/bottom-sheet/content.md): A surface that slides up from the bottom of the screen to present secondary tasks without leaving the current context. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=3187-706), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-bottomsheet--default) Design guidance: [design.md](components/bottom-sheet/design.md)
+  - [Box](components/box/content.md): The layout container for building screens, with semantic web elements through role and an asChild escape hatch. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-box--default)
   - [Card](components/card/content.md): A composable surface for grouping related content, with optional brand stripe, header, content, and footer regions. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=456-14), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-card--with-stripe)
   - [Drawer](components/drawer/content.md): A panel attached to an edge of the viewport or container, with modal and permanent presentations. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=9956-15204), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-drawer--default)
-  - [ScopedTheme](components/scoped-theme/content.md): Forces a specific theme on a component subtree, regardless of the application's global theme. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/theming-scopedtheme--default)
-  - [ScrollShadow](components/scroll-shadow/content.md): Fades the edges of a scroll view so overflowing content reads as scrollable on iOS, Android, and web. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-scrollshadow--default)
+  - [Scoped Theme](components/scoped-theme/content.md): Forces a specific theme on a component subtree, regardless of the application's global theme. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/theming-scopedtheme--default)
+  - [Scroll Shadow](components/scroll-shadow/content.md): Fades the edges of a scroll view so overflowing content reads as scrollable on iOS, Android, and web. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-scrollshadow--default)
   - [Stack](components/stack/content.md): Horizontal and vertical layout primitives with token-based spacing and optional reversed order. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-vstack--default)
 
   - **Navigation**
@@ -137,6 +138,8 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
 
 ## Release notes
 
+- [0.2.5](resources/release-notes/0.2.5/content.md): Box is the supported layout primitive with hardened stacks; View from @cdx-ui/components is deprecated. Align Expo apps with SDK 57 and React Native 0.86.
+- [0.2.4](resources/release-notes/0.2.4/content.md): ScrollShadow fades scroll edges on iOS, Android, and web; ListItem.SectionHeader adds a gradient variant for account-style lists.
 - [0.2.3](resources/release-notes/0.2.3/content.md): ReorderableList brings drag-and-drop list reordering on web and native; Tile flat rows show the selected background again.
 - [0.2.2](resources/release-notes/0.2.2/content.md): Fixes web Text layout in production, Button solid edges on native, and Field required labels on web.
 - [0.2.1](resources/release-notes/0.2.1/content.md): Calendar and DatePicker add isDateUnavailable and shared typed-entry validation integrated with Field and @cdx-ui/formatters.

package/docs/patterns/authentication/content.md

@@ -11,13 +11,11 @@ import { Button, Card, Field, Heading, Input, Link, Text, VStack } from '@cdx-ui
 
 export default function LoginSimpleBlock() {
   return (
-    <Card className="w-full max-w-sm shadow-lg">
+    <Card className="w-full max-w-sm">
       <Card.Header>
         <VStack space="sm" className="items-center">
-          <Heading size="lg">Sign in</Heading>
-          <Text className="text-content-secondary">
-            Enter your credentials to access your account
-          </Text>
+          <Heading>Sign in</Heading>
+          <Text color="secondary">Enter your credentials to access your account</Text>
         </VStack>
       </Card.Header>
       <Card.Content>
@@ -34,7 +32,7 @@ export default function LoginSimpleBlock() {
               <Input.Field placeholder="Enter your password" secureTextEntry />
             </Input>
           </Field>
-          <Button variant="solid" fullWidth>
+          <Button fullWidth>
             <Button.Label>Sign In</Button.Label>
           </Button>
         </VStack>

package/docs/patterns/dashboard/content.md

@@ -7,28 +7,23 @@ A personalized greeting header with search, notifications, and avatar.
 **Platforms:** iOS, Android
 
 ```tsx
-import { Avatar, Heading, HStack, IconButton, Text, VStack, View } from '@cdx-ui/components';
+import { Avatar, Badge, Heading, HStack, IconButton, Text, VStack } from '@cdx-ui/components';
 import { Notifications, Search } from '@cdx-ui/icons';
 
 export default function DashboardGreetingBlock() {
   return (
     <HStack className="w-full max-w-md items-center justify-between py-4 px-4">
-      <VStack className="gap-0.5">
-        <Text size="sm" className="text-content-secondary">
+      <VStack space="xs">
+        <Text size="sm" color="secondary">
           Good morning,
         </Text>
-        <Heading size="lg">Bernadette</Heading>
+        <Heading>Bernadette</Heading>
       </VStack>
       <HStack space="sm" className="items-center">
-        <IconButton as={Search} color="neutral" />
-        <View className="relative">
-          <IconButton as={Notifications} color="neutral" />
-          <View className="absolute -top-1 -right-1 flex size-5 items-center justify-center rounded-full bg-surface-danger-strong border border-white">
-            <Text size="xs" className="font-bold text-white">
-              3
-            </Text>
-          </View>
-        </View>
+        <IconButton as={Search} accessibilityLabel="Search" />
+        <Badge label={3} color="danger" overlap="circular" accessibilityLabel="3 notifications">
+          <IconButton as={Notifications} accessibilityLabel="Notifications" />
+        </Badge>
         <Avatar size="lg">
           <Avatar.Text>Bernadette Miller</Avatar.Text>
         </Avatar>

package/docs/patterns/empty-states/content.md

@@ -7,22 +7,23 @@ An empty state shown when no transaction history is available.
 **Platforms:** iOS, Android, Web
 
 ```tsx
-import { Button, Heading, Icon, Text, VStack } from '@cdx-ui/components';
+import { Avatar, Button, Heading, Text, VStack } from '@cdx-ui/components';
 import { ReceiptLong } from '@cdx-ui/icons';
 
 export default function NoTransactionsBlock() {
   return (
     <VStack space="lg" className="w-full max-w-sm items-center py-12 px-6">
-      <VStack space="md" className="items-center bg-surface-secondary rounded-full p-5">
-        <Icon as={ReceiptLong} className="size-10 text-content-secondary" />
-      </VStack>
+      {/* TODO(forge-ui): Avatar has no size larger than 2xl for an empty-state illustration; using 2xl. */}
+      <Avatar size="2xl" color="neutral">
+        <Avatar.Icon as={ReceiptLong} />
+      </Avatar>
       <VStack space="sm" className="items-center">
         <Heading size="md">No transactions yet</Heading>
-        <Text className="text-content-secondary text-center">
+        <Text color="secondary" className="text-center">
           Once you make your first transaction, it will appear here.
         </Text>
       </VStack>
-      <Button variant="solid">
+      <Button>
         <Button.Label>Make a transfer</Button.Label>
       </Button>
     </VStack>

package/docs/patterns/forms/content.md

@@ -11,7 +11,7 @@ import { Button, Card, Field, Heading, Input, VStack } from '@cdx-ui/components'
 
 export default function ContactInfoFormBlock() {
   return (
-    <Card className="w-full max-w-md shadow-lg">
+    <Card className="w-full max-w-md">
       <Card.Header>
         <VStack space="xs">
           <Heading size="md">Contact information</Heading>
@@ -46,7 +46,7 @@ export default function ContactInfoFormBlock() {
         </VStack>
       </Card.Content>
       <Card.Footer>
-        <Button variant="solid" fullWidth>
+        <Button fullWidth>
           <Button.Label>Save changes</Button.Label>
         </Button>
       </Card.Footer>
@@ -65,11 +65,10 @@ A card that reveals a date range picker for choosing a start and end date.
 import { useState } from 'react';
 import {
   Accordion,
-  Box,
+  Avatar,
   Card,
   DateField,
   DateRangePicker,
-  Icon,
   type DateRangeValue,
 } from '@cdx-ui/components';
 import { CalendarToday } from '@cdx-ui/icons';
@@ -83,9 +82,9 @@ export default function DateRangeBlock() {
         <Accordion.Item value="date-range" showSeparator={false}>
           <Accordion.Trigger>
             <Accordion.LeadingSlot>
-              <Box className="size-10 items-center justify-center rounded-full bg-surface-info-subtle">
-                <Icon as={CalendarToday} />
-              </Box>
+              <Avatar size="lg" color="info">
+                <Avatar.Icon as={CalendarToday} />
+              </Avatar>
             </Accordion.LeadingSlot>
             <Accordion.Label>
               <Accordion.Title>Date range</Accordion.Title>