@coinbase/cds-mcp-server 8.41.0 → 8.42.0

package/mcp-docs/web/components/MessagingCard.txt

@@ -0,0 +1,1054 @@
+# MessagingCard
+
+MessagingCard displays promotional or informational content with two variants: 'upsell' for promoting features with a primary background, and 'nudge' for encouraging actions with an alternate background. It replaces the deprecated NudgeCard and UpsellCard components.
+
+## Import
+
+```tsx
+import { MessagingCard } from '@coinbase/cds-web/cards/MessagingCard'
+```
+
+## Examples
+
+MessagingCard provides two card types for promotional and informational content.
+
+:::info Migrating from NudgeCard or UpsellCard?
+See the [Migration Guide](#migration-from-deprecated-components) at the end of this page.
+:::
+
+### Basic Types
+
+Use `type` to set the card variant:
+
+- `upsell`: Primary background, used for promoting features or products. Use `variant="secondary"` buttons.
+- `nudge`: Alternate background, used for encouraging user actions. Use `variant="tertiary"` (transparent) buttons for a less intrusive appearance.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="upsell"
+    title="Upsell Card"
+    description="This is an upsell card with primary background"
+    width={320}
+    action="Get started"
+    onActionButtonClick={() => alert('Action clicked!')}
+    media={
+      <RemoteImage
+        alt="Feature promotional image"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/feature.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Nudge Card"
+    description="This is a nudge card with alternate background"
+    width={320}
+    action="Learn more"
+    onActionButtonClick={() => alert('Action clicked!')}
+    media={<Pictogram dimension="64x64" name="addToWatchlist" />}
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+:::tip Nudge Button Style
+Use transparent buttons (`variant="tertiary"` or `transparent` prop) for nudge cards. They provide a gentle reminder without being intrusive, blending more seamlessly with the card's alternate background.
+:::
+
+### Media Placement
+
+Use `mediaPlacement` to control the position of media content.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="nudge"
+    title="Media End"
+    description="Media placed at the end (right)"
+    width={320}
+    media={<Pictogram dimension="48x48" name="addToWatchlist" />}
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Media Start"
+    description="Media placed at the start (left)"
+    width={320}
+    media={<Pictogram dimension="48x48" name="addToWatchlist" />}
+    mediaPlacement="start"
+  />
+</VStack>
+```
+
+### Upsell Card Styles
+
+MessagingCard with `type="upsell"` supports various background colors to match different promotional purposes. Use the `background` prop for semantic tokens, or `dangerouslySetBackground` for custom spectrum colors.
+
+#### General Upsell
+
+Utilize the default background for general information and non-urgent promotions. Its versatile design is perfect for a broad range of content, providing a subtle yet effective approach to engage users. It's also the most suitable style for Pictogram illustrations.
+
+```jsx live
+<MessagingCard
+  type="upsell"
+  background="bgPrimaryWash"
+  title={
+    <Text as="h3" color="fg" font="headline">
+      Recurring Buy
+    </Text>
+  }
+  description={
+    <Text as="p" color="fg" font="label2">
+      Want to add funds to your card every week or month?
+    </Text>
+  }
+  width={360}
+  action={
+    <Button compact variant="secondary">
+      Get started
+    </Button>
+  }
+  media={
+    <Box paddingEnd={3}>
+      <Pictogram name="recurringPurchases" dimension="64x64" />
+    </Box>
+  }
+  mediaPlacement="end"
+  onDismissButtonClick={() => {}}
+  dismissButtonAccessibilityLabel="Dismiss"
+/>
+```
+
+#### Feature Upsell
+
+Ideal for highlighting Coinbase tools, innovative features, and unique functionalities. Choose from our palette of distinct colors to make your Feature Upsell stand out. Each color is carefully selected to grab attention while aligning with the specific nature of the feature being promoted.
+
+```jsx live
+function FeatureUpsell() {
+  const cards = [
+    { bg: 'rgb(var(--purple70))', label: 'Purple' },
+    { bg: 'rgb(var(--teal50))', label: 'Teal' },
+    { bg: 'rgb(var(--blue80))', label: 'Blue' },
+    { bg: 'rgb(var(--indigo70))', label: 'Indigo' },
+  ];
+  return (
+    <VStack gap={2}>
+      {cards.map((card) => (
+        <MessagingCard
+          key={card.label}
+          type="upsell"
+          dangerouslySetBackground={card.bg}
+          title={
+            <Text color="fgInverse" as="h3" font="headline">
+              Up to 3.29% APR on ETH
+            </Text>
+          }
+          description={
+            <Text as="p" font="label2" numberOfLines={3} color="fgInverse">
+              Earn staking rewards on ETH by holding it on Coinbase
+            </Text>
+          }
+          width={360}
+          action="Start earning"
+          onActionButtonClick={() => alert('Action clicked!')}
+          media={
+            <RemoteImage
+              alt="Feature illustration"
+              height={160}
+              resizeMode="cover"
+              shape="rectangle"
+              source="/img/feature.png"
+            />
+          }
+          mediaPlacement="end"
+          onDismissButtonClick={() => {}}
+          dismissButtonAccessibilityLabel="Dismiss"
+        />
+      ))}
+    </VStack>
+  );
+}
+```
+
+#### Community Upsell
+
+Designed for community-focused messaging. Vibrant colors spark enthusiasm and encourage active participation, fostering a sense of community engagement.
+
+```jsx live
+function CommunityUpsell() {
+  const cards = [
+    { bg: 'rgb(var(--teal70))', image: '/img/community.png' },
+    { bg: 'rgb(var(--purple70))', image: '/img/radial.png' },
+  ];
+  return (
+    <VStack gap={2}>
+      {cards.map((card, i) => (
+        <MessagingCard
+          key={i}
+          type="upsell"
+          dangerouslySetBackground={card.bg}
+          title={
+            <Text color="fgInverse" as="h3" font="headline">
+              Join the community
+            </Text>
+          }
+          description={
+            <Text as="p" font="label2" numberOfLines={3} color="fgInverse">
+              Chat with other devs in our Discord community
+            </Text>
+          }
+          width={360}
+          action="Join now"
+          onActionButtonClick={() => alert('Action clicked!')}
+          media={
+            <RemoteImage
+              alt="Community illustration"
+              height={160}
+              resizeMode="cover"
+              shape="rectangle"
+              source={card.image}
+            />
+          }
+          mediaPlacement="end"
+          onDismissButtonClick={() => {}}
+          dismissButtonAccessibilityLabel="Dismiss"
+        />
+      ))}
+    </VStack>
+  );
+}
+```
+
+#### Product Upsell
+
+Optimal for business products, security features, and functionalities that emphasize trust and reliability, such as Coinbase One and Coinbase Card. Blue and dark backgrounds symbolize stability, trustworthiness, and professionalism.
+
+```jsx live
+function ProductUpsell() {
+  const cards = [
+    {
+      title: 'Coinbase One offer',
+      description: 'Use code NOV60 when you sign up for Coinbase One',
+      action: 'Get 60 days free',
+      bg: 'rgb(var(--blue80))',
+      image: '/img/marketing.png',
+    },
+    {
+      title: 'Coinbase Card',
+      description: 'Spend USDC to get rewards with our Visa® debit card',
+      action: 'Get started',
+      bg: 'rgb(var(--gray100))',
+      image: '/img/object.png',
+    },
+  ];
+  return (
+    <VStack gap={2}>
+      {cards.map((card) => (
+        <MessagingCard
+          key={card.title}
+          type="upsell"
+          dangerouslySetBackground={card.bg}
+          title={
+            <Text color="fgInverse" as="h3" font="headline">
+              {card.title}
+            </Text>
+          }
+          description={
+            <Text as="p" font="label2" numberOfLines={3} color="fgInverse">
+              {card.description}
+            </Text>
+          }
+          width={360}
+          action={card.action}
+          onActionButtonClick={() => alert('Action clicked!')}
+          media={
+            <RemoteImage
+              alt="Product illustration"
+              height={160}
+              resizeMode="cover"
+              shape="rectangle"
+              source={card.image}
+            />
+          }
+          mediaPlacement="end"
+          onDismissButtonClick={() => {}}
+          dismissButtonAccessibilityLabel="Dismiss"
+        />
+      ))}
+    </VStack>
+  );
+}
+```
+
+#### News Upsell
+
+Specifically tailored for company announcements and policy updates. Its design ensures that important information is conveyed clearly and prominently, ensuring users stay well-informed about the latest developments.
+
+```jsx live
+function NewsUpsell() {
+  const cards = [{ bg: 'rgb(var(--gray100))' }, { bg: 'rgb(var(--indigo70))' }];
+  return (
+    <VStack gap={2}>
+      {cards.map((card, i) => (
+        <MessagingCard
+          key={i}
+          type="upsell"
+          dangerouslySetBackground={card.bg}
+          title={
+            <Text color="fgInverse" as="h3" font="headline">
+              Help defend crypto in America
+            </Text>
+          }
+          description={
+            <Text as="p" font="label2" numberOfLines={3} color="fgInverse">
+              Help us keep crypto in America with a single click
+            </Text>
+          }
+          width={360}
+          action="Join the fight"
+          onActionButtonClick={() => alert('Action clicked!')}
+          media={
+            <RemoteImage
+              alt="Place illustration"
+              height={180}
+              resizeMode="cover"
+              shape="rectangle"
+              source="/img/place.png"
+            />
+          }
+          mediaPlacement="end"
+          onDismissButtonClick={() => {}}
+          dismissButtonAccessibilityLabel="Dismiss"
+        />
+      ))}
+    </VStack>
+  );
+}
+```
+
+### Nudge Card Style
+
+Use `type="nudge"` for gentle reminders or secondary options. Nudge cards use the alternate background and blend more seamlessly with the page. Pair them with Pictogram illustrations and transparent buttons.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="nudge"
+    title="Earn more crypto"
+    description="You've got unstaked crypto. Stake it now to earn more."
+    width={360}
+    action="Start earning"
+    onActionButtonClick={() => alert('Action clicked!')}
+    media={<Pictogram dimension="64x64" name="key" />}
+    mediaPlacement="end"
+    onDismissButtonClick={() => {}}
+    dismissButtonAccessibilityLabel="Dismiss"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Derivatives Trading"
+    description="Derivative Exchange is available for all users"
+    width={360}
+    media={<Pictogram dimension="48x48" name="derivativesNavigation" />}
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+### Features
+
+#### Dismissible Cards
+
+Use `onDismissButtonClick` to add a dismiss button.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="upsell"
+    title="Dismissible Upsell"
+    description="Upsell card with dismiss button"
+    width={320}
+    media={
+      <RemoteImage
+        alt="Community illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/community.png"
+      />
+    }
+    mediaPlacement="end"
+    onDismissButtonClick={() => alert('Card dismissed!')}
+    dismissButtonAccessibilityLabel="Close card"
+    dangerouslySetBackground="rgb(var(--teal70))"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Dismissible Nudge"
+    description="Nudge card with dismiss button"
+    width={320}
+    media={<Pictogram dimension="48x48" name="baseStar" />}
+    mediaPlacement="end"
+    onDismissButtonClick={() => alert('Card dismissed!')}
+    dismissButtonAccessibilityLabel="Close card"
+  />
+</VStack>
+```
+
+#### Tags
+
+Use `tag` to add a label badge.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="upsell"
+    title="Tagged Upsell"
+    description="Upsell card with a tag"
+    width={320}
+    tag="New"
+    media={
+      <RemoteImage
+        alt="Place illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/place.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Tagged Nudge"
+    description="Nudge card with a tag"
+    width={320}
+    tag="New"
+    media={<Pictogram dimension="48x48" name="key" />}
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+#### Actions
+
+Use the `action` prop to add an action button. Pass a string to render a default button with `onActionButtonClick`, or pass a custom React element.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="upsell"
+    title="Upsell with Action"
+    description="Upsell card with action button"
+    width={320}
+    action="Action"
+    onActionButtonClick={() => alert('Action clicked!')}
+    media={
+      <RemoteImage
+        alt="Feature illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/feature.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Nudge with Action"
+    description="Nudge card with action button"
+    width={320}
+    action="Learn More"
+    onActionButtonClick={() => alert('Action clicked!')}
+    media={<Pictogram dimension="64x64" name="wallet" />}
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+#### Complete Example
+
+Combine all features in a complete card.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="upsell"
+    title="Complete Upsell Card"
+    description="Complete upsell card with all features"
+    width={360}
+    tag="New"
+    action="Get Started"
+    onActionButtonClick={() => alert('Action clicked!')}
+    onDismissButtonClick={() => alert('Dismissed')}
+    dismissButtonAccessibilityLabel="Dismiss"
+    media={
+      <RemoteImage
+        alt="Marketing illustration"
+        height={184}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/marketing.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    type="nudge"
+    title="Complete Nudge Card"
+    description="Complete nudge card with all features"
+    width={360}
+    tag="New"
+    action="Learn More"
+    onActionButtonClick={() => alert('Action clicked!')}
+    onDismissButtonClick={() => alert('Dismissed')}
+    dismissButtonAccessibilityLabel="Dismiss"
+    media={<Pictogram dimension="64x64" name="giftbox" />}
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+### Interactive Dismissible List
+
+This example shows a list of cards that can be dismissed interactively. Click the dismiss button to remove cards from the list.
+
+```jsx live
+function DismissibleCards() {
+  const cards = [
+    {
+      id: '1',
+      title: 'Welcome to Coinbase',
+      description: 'Get started with your crypto journey',
+      type: 'upsell',
+    },
+    {
+      id: '2',
+      title: 'Complete your profile',
+      description: 'Add your details to unlock more features',
+      type: 'nudge',
+    },
+    {
+      id: '3',
+      title: 'Enable notifications',
+      description: 'Stay updated on market movements',
+      type: 'upsell',
+    },
+    {
+      id: '4',
+      title: 'Invite friends',
+      description: 'Earn rewards when friends join',
+      type: 'nudge',
+    },
+  ];
+
+  const [dismissedIds, setDismissedIds] = React.useState(new Set());
+
+  const handleDismiss = (id) => {
+    setDismissedIds((prev) => new Set(prev).add(id));
+  };
+
+  const handleReset = () => {
+    setDismissedIds(new Set());
+  };
+
+  const visibleCards = cards.filter((card) => !dismissedIds.has(card.id));
+
+  return (
+    <VStack gap={2}>
+      <HStack gap={2} flexWrap="wrap">
+        {visibleCards.map((card) => (
+          <MessagingCard
+            key={card.id}
+            type={card.type}
+            dangerouslySetBackground={card.type === 'upsell' ? 'rgb(var(--gray100))' : undefined}
+            title={card.title}
+            description={card.description}
+            width={360}
+            media={
+              card.type === 'upsell' ? (
+                <RemoteImage
+                  alt="Promotional illustration"
+                  height={160}
+                  resizeMode="cover"
+                  shape="rectangle"
+                  source="/img/object.png"
+                />
+              ) : (
+                <Pictogram dimension="48x48" name="addToWatchlist" />
+              )
+            }
+            mediaPlacement="end"
+            onDismissButtonClick={() => handleDismiss(card.id)}
+            dismissButtonAccessibilityLabel={`Dismiss ${card.title}`}
+          />
+        ))}
+        {visibleCards.length === 0 && (
+          <Text color="fgNegative" font="label1">
+            All cards dismissed!
+          </Text>
+        )}
+      </HStack>
+      <Button onClick={handleReset} variant="tertiary">
+        Reset Cards
+      </Button>
+    </VStack>
+  );
+}
+```
+
+### Polymorphic and Interactive
+
+MessagingCard supports polymorphic rendering with `as` and can be made interactive with `renderAsPressable`.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    as="article"
+    type="upsell"
+    dangerouslySetBackground="rgb(var(--teal70))"
+    title="Title"
+    description="Description"
+    width={320}
+    media={
+      <RemoteImage
+        alt="Community illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/community.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    renderAsPressable
+    as="a"
+    href="https://www.coinbase.com"
+    target="_blank"
+    type="upsell"
+    dangerouslySetBackground="rgb(var(--purple70))"
+    title="Interactive Upsell"
+    description="Clickable card with href"
+    width={320}
+    media={
+      <RemoteImage
+        alt="Radial design"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/radial.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    renderAsPressable
+    as="a"
+    href="https://www.coinbase.com"
+    target="_blank"
+    type="nudge"
+    title="Interactive Nudge"
+    description="Clickable nudge with href"
+    width={320}
+    media={<Pictogram dimension="48x48" name="baseRocket" />}
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    renderAsPressable
+    as="button"
+    onClick={() => alert('Card clicked!')}
+    type="upsell"
+    dangerouslySetBackground="rgb(var(--gray100))"
+    title="Interactive Card"
+    description="Clickable card with onClick handler"
+    width={320}
+    media={
+      <RemoteImage
+        alt="Object illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/object.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+### Custom Content
+
+Use React nodes for custom styled content.
+
+```jsx live
+<VStack gap={2}>
+  <MessagingCard
+    type="upsell"
+    title="This is a very long title text that demonstrates text wrapping"
+    description="This is a very long description text that demonstrates how the card handles longer content and wraps appropriately within the card layout"
+    width={320}
+    media={
+      <RemoteImage
+        alt="Place illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/place.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+  <MessagingCard
+    type="upsell"
+    width={320}
+    height={160}
+    title={
+      <Text color="fgInverse" font="title3">
+        Custom Title
+      </Text>
+    }
+    tag={
+      <Text color="fgInverse" font="label2">
+        Custom Tag
+      </Text>
+    }
+    description={
+      <Text color="fgInverse" font="label2" numberOfLines={3}>
+        Custom description with <strong>bold text</strong> and <em>italic text</em>
+      </Text>
+    }
+    media={
+      <RemoteImage
+        alt="Collection illustration"
+        height={160}
+        resizeMode="cover"
+        shape="rectangle"
+        source="/img/collection.png"
+      />
+    }
+    mediaPlacement="end"
+  />
+</VStack>
+```
+
+### Multiple Cards
+
+Display multiple cards in a carousel.
+
+```jsx live
+<Carousel styles={{ carousel: { gap: 16 } }}>
+  <CarouselItem id="card1">
+    <MessagingCard
+      as="article"
+      type="upsell"
+      title="Card 1"
+      description="Non-interactive card"
+      width={320}
+      media={
+        <RemoteImage
+          alt="Marketing illustration"
+          height={160}
+          resizeMode="cover"
+          shape="rectangle"
+          source="/img/marketing.png"
+        />
+      }
+      mediaPlacement="end"
+    />
+  </CarouselItem>
+  <CarouselItem id="card2">
+    <MessagingCard
+      renderAsPressable
+      as="a"
+      href="https://www.coinbase.com"
+      target="_blank"
+      type="nudge"
+      title="Card 2"
+      description="Clickable card with href"
+      tag="Link"
+      media={<Pictogram dimension="64x64" name="addToWatchlist" />}
+      mediaPlacement="end"
+    />
+  </CarouselItem>
+  <CarouselItem id="card3">
+    <MessagingCard
+      renderAsPressable
+      as="button"
+      onClick={() => console.log('clicked')}
+      type="upsell"
+      dangerouslySetBackground="rgb(var(--purple70))"
+      title="Card 3"
+      description="Card with onClick handler"
+      tag="Action"
+      media={
+        <RemoteImage
+          alt="Radial design"
+          height={160}
+          resizeMode="cover"
+          shape="rectangle"
+          source="/img/radial.png"
+        />
+      }
+      mediaPlacement="end"
+    />
+  </CarouselItem>
+</Carousel>
+```
+
+### Accessibility
+
+#### Interactive Cards with Dismiss Button
+
+When you need both `onDismissButtonClick` and want the entire card to be clickable, you should handle accessibility carefully to avoid nested interactive elements.
+
+**The Problem**: If you use `renderAsPressable` with `onClick` and also have `onDismissButtonClick`, the card becomes a button containing another button (the dismiss button). This creates accessibility issues for screen reader users.
+
+**The Solution**: Mark the card as non-accessible and add a separate action button inside the card with the same action. This allows:
+
+- Regular users to click anywhere on the card
+- Screen reader users to focus on individual interactive elements (action button + dismiss button)
+
+```jsx live
+<MessagingCard
+  renderAsPressable
+  tabIndex={-1}
+  as="div"
+  onClick={() => alert('Card clicked - navigating...')}
+  type="upsell"
+  title="Accessible Interactive Card"
+  description="Card with both dismiss and card-level action"
+  width={360}
+  action={
+    <Button
+      compact
+      variant="secondary"
+      onClick={(event) => {
+        event.stopPropagation();
+        alert('Button clicked - navigating...');
+      }}
+    >
+      Learn More
+    </Button>
+  }
+  background="accentBoldPurple"
+  onDismissButtonClick={() => alert('Dismissed')}
+  dismissButtonAccessibilityLabel="Dismiss promotion"
+  media={
+    <RemoteImage
+      alt="Feature illustration"
+      height={160}
+      resizeMode="cover"
+      shape="rectangle"
+      source="/img/feature.png"
+    />
+  }
+  mediaPlacement="end"
+/>
+```
+
+**Key points:**
+
+- Use `as="div"` to avoid rendering as a semantic button
+- When using `as="div"` with `renderAsPressable`, the card remains keyboard focusable. Set `tabIndex={-1}` to remove it from the tab order if needed
+- Call `event.stopPropagation()` at the beginning of the event handler method passed into the `onClick` prop for action buttons. This will prevent two click events from firing if the user directly clicks the action button.
+- Use `actionButtonAccessibilityLabel` and `dismissButtonAccessibilityLabel` to add or override the `aria-label` for the action and dismiss buttons
+
+#### Color Contrast
+
+MessagingCard supports custom backgrounds via `background` and `dangerouslySetBackground` props. When using custom background colors, ensure sufficient color contrast between text and background:
+
+- Use `fgInverse` text color with dark backgrounds (e.g., `accentBoldPurple`, `bgInverse`)
+- Use `fg` text color with light backgrounds (e.g., `bgPrimaryWash`, `bgAlternate`)
+- Use the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your color combinations meet WCAG AA guidelines (4.5:1 for normal text)
+
+### Migration from Deprecated Components
+
+#### Migrating from NudgeCard
+
+Replace `NudgeCard` with `MessagingCard` using `type="nudge"`.
+
+```jsx
+// Before
+<NudgeCard
+  title="Title"
+  description="Description"
+  pictogram="addToWatchlist"
+  action="Learn more"
+  onActionPress={handleAction}
+  onDismissPress={handleDismiss}
+/>
+
+// After
+<MessagingCard
+  type="nudge"
+  title="Title"
+  description="Description"
+  media={<Pictogram dimension="64x64" name="addToWatchlist" />}
+  action="Learn more"
+  onActionButtonClick={handleAction}
+  onDismissButtonClick={handleDismiss}
+  mediaPlacement="end"
+/>
+```
+
+#### Migrating from UpsellCard
+
+Replace `UpsellCard` with `MessagingCard` using `type="upsell"`.
+
+```jsx
+// Before
+<UpsellCard
+  title="Title"
+  description="Description"
+  media={<RemoteImage ... />}
+  action="Get Started"
+  onActionPress={handleAction}
+  onDismissPress={handleDismiss}
+/>
+
+// After
+<MessagingCard
+  type="upsell"
+  title="Title"
+  description="Description"
+  media={<RemoteImage ... />}
+  action="Get Started"
+  onActionButtonClick={handleAction}
+  onDismissButtonClick={handleDismiss}
+  mediaPlacement="end"
+/>
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `mediaPlacement` | `start \| end` | Yes | `'end'` | Placement of the media content relative to the text content. |
+| `type` | `upsell \| nudge` | Yes | `-` | Type of messaging card. Determines background color and text color. |
+| `action` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Action element to display. Can be a string (renders as default button) or a custom ReactNode. When a string is provided, use onActionButtonClick to handle clicks. |
+| `actionButtonAccessibilityLabel` | `string` | No | `action value (when action is a string)` | Accessibility label for the action button. Only used when action is a string. |
+| `alignContent` | `ResponsiveProp<center \| normal \| start \| end \| flex-start \| flex-end \| stretch \| baseline \| first baseline \| last baseline \| space-between \| space-around \| space-evenly>` | No | `-` | - |
+| `alignItems` | `ResponsiveProp<center \| normal \| start \| end \| flex-start \| flex-end \| self-start \| self-end \| stretch \| baseline \| first baseline \| last baseline>` | No | `-` | - |
+| `alignSelf` | `ResponsiveProp<center \| normal \| auto \| start \| end \| flex-start \| flex-end \| self-start \| self-end \| stretch \| baseline \| first baseline \| last baseline>` | No | `-` | - |
+| `as` | `symbol \| object \| style \| div \| a \| abbr \| address \| area \| article \| aside \| audio \| b \| base \| bdi \| bdo \| big \| blockquote \| body \| br \| button \| canvas \| caption \| center \| cite \| code \| col \| colgroup \| data \| datalist \| dd \| del \| details \| dfn \| dialog \| dl \| dt \| em \| embed \| fieldset \| figcaption \| figure \| footer \| form \| h1 \| h2 \| h3 \| h4 \| h5 \| h6 \| head \| header \| hgroup \| hr \| html \| i \| iframe \| img \| input \| ins \| kbd \| keygen \| label \| legend \| li \| link \| main \| map \| mark \| menu \| menuitem \| meta \| meter \| nav \| noindex \| noscript \| ol \| optgroup \| option \| output \| p \| param \| picture \| pre \| progress \| q \| rp \| rt \| ruby \| s \| samp \| search \| slot \| script \| section \| select \| small \| source \| span \| strong \| sub \| summary \| sup \| table \| template \| tbody \| td \| textarea \| tfoot \| th \| thead \| time \| title \| tr \| track \| u \| ul \| var \| video \| wbr \| webview \| svg \| animate \| animateMotion \| animateTransform \| circle \| clipPath \| defs \| desc \| ellipse \| feBlend \| feColorMatrix \| feComponentTransfer \| feComposite \| feConvolveMatrix \| feDiffuseLighting \| feDisplacementMap \| feDistantLight \| feDropShadow \| feFlood \| feFuncA \| feFuncB \| feFuncG \| feFuncR \| feGaussianBlur \| feImage \| feMerge \| feMergeNode \| feMorphology \| feOffset \| fePointLight \| feSpecularLighting \| feSpotLight \| feTile \| feTurbulence \| filter \| foreignObject \| g \| image \| line \| linearGradient \| marker \| mask \| metadata \| mpath \| path \| pattern \| polygon \| polyline \| radialGradient \| rect \| set \| stop \| switch \| text \| textPath \| tspan \| use \| view \| ComponentClass<any, any> \| FunctionComponent<any>` | No | `-` | The underlying element or component the polymorphic component will render.  Changing as also changes the inherited native props (e.g. href for as=a) and the expected ref type. |
+| `aspectRatio` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `background` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | Background color of the overlay (element being interacted with). |
+| `blendStyles` | `InteractableBlendStyles` | No | `-` | - |
+| `block` | `boolean` | No | `-` | Set element to block and expand to 100% width. |
+| `borderBottomLeftRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
+| `borderBottomRightRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
+| `borderBottomWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
+| `borderColor` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | Border color of the element. |
+| `borderEndWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
+| `borderRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
+| `borderStartWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
+| `borderTopLeftRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
+| `borderTopRightRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
+| `borderTopWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
+| `borderWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
+| `bordered` | `boolean` | No | `-` | Add a border around all sides of the box. |
+| `borderedBottom` | `boolean` | No | `-` | Add a border to the bottom side of the box. |
+| `borderedEnd` | `boolean` | No | `-` | Add a border to the trailing side of the box. |
+| `borderedHorizontal` | `boolean` | No | `-` | Add a border to the leading and trailing sides of the box. |
+| `borderedStart` | `boolean` | No | `-` | Add a border to the leading side of the box. |
+| `borderedTop` | `boolean` | No | `-` | Add a border to the top side of the box. |
+| `borderedVertical` | `boolean` | No | `-` | Add a border to the top and bottom sides of the box. |
+| `bottom` | `ResponsiveProp<Bottom<string \| number>>` | No | `-` | - |
+| `className` | `string` | No | `-` | Apply class names to the outer container. |
+| `classNames` | `({ layoutContainer?: string; contentContainer?: string \| undefined; textContainer?: string \| undefined; mediaContainer?: string \| undefined; dismissButtonContainer?: string \| undefined; } & { root?: string \| undefined; }) \| undefined` | No | `-` | - |
+| `color` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | - |
+| `columnGap` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `dangerouslySetBackground` | `string` | No | `-` | - |
+| `description` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Text or React node to display as the card description. Use a Text component to override default color and font. |
+| `disabled` | `boolean` | No | `-` | Is the element currently disabled. |
+| `dismissButton` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | React node to display as the dismiss button. When provided, this will be rendered instead of the default dismiss button. |
+| `dismissButtonAccessibilityLabel` | `string` | No | `'Dismiss {title}' when title is a string, otherwise 'Dismiss card'` | Accessibility label for the dismiss button. |
+| `display` | `ResponsiveProp<grid \| revert \| none \| block \| inline \| inline-block \| flex \| inline-flex \| inline-grid \| contents \| flow-root \| list-item>` | No | `-` | - |
+| `elevation` | `0 \| 1 \| 2` | No | `-` | - |
+| `flexBasis` | `ResponsiveProp<FlexBasis<string \| number>>` | No | `-` | - |
+| `flexDirection` | `ResponsiveProp<column \| row \| row-reverse \| column-reverse>` | No | `-` | - |
+| `flexGrow` | `inherit \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `flexShrink` | `inherit \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `flexWrap` | `ResponsiveProp<nowrap \| wrap \| wrap-reverse>` | No | `-` | - |
+| `focusable` | `boolean` | No | `-` | - |
+| `font` | `ResponsiveProp<FontFamily \| inherit>` | No | `-` | - |
+| `fontFamily` | `ResponsiveProp<FontFamily \| inherit>` | No | `-` | - |
+| `fontSize` | `ResponsiveProp<FontSize \| inherit>` | No | `-` | - |
+| `fontWeight` | `ResponsiveProp<FontWeight \| inherit>` | No | `-` | - |
+| `gap` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `grid` | `inherit \| none \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridArea` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridAutoColumns` | `ResponsiveProp<GridAutoColumns<string \| number>>` | No | `-` | - |
+| `gridAutoFlow` | `inherit \| revert \| row \| column \| -moz-initial \| initial \| revert-layer \| unset \| dense` | No | `-` | - |
+| `gridAutoRows` | `ResponsiveProp<GridAutoRows<string \| number>>` | No | `-` | - |
+| `gridColumn` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridColumnEnd` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridColumnStart` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridRow` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridRowEnd` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridRowStart` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridTemplate` | `inherit \| none \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridTemplateAreas` | `inherit \| none \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `gridTemplateColumns` | `ResponsiveProp<GridTemplateColumns<string \| number>>` | No | `-` | - |
+| `gridTemplateRows` | `ResponsiveProp<GridTemplateRows<string \| number>>` | No | `-` | - |
+| `height` | `ResponsiveProp<Height<string \| number>>` | No | `-` | - |
+| `justifyContent` | `ResponsiveProp<left \| right \| center \| normal \| start \| end \| flex-start \| flex-end \| stretch \| space-between \| space-around \| space-evenly>` | No | `-` | - |
+| `left` | `ResponsiveProp<Left<string \| number>>` | No | `-` | - |
+| `lineHeight` | `ResponsiveProp<LineHeight \| inherit>` | No | `-` | - |
+| `loading` | `boolean` | No | `-` | Is the element currenty loading. When set to true, will disable element from press and keyboard events |
+| `margin` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `marginBottom` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `marginEnd` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `marginStart` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `marginTop` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `marginX` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `marginY` | `ResponsiveProp<0 \| -5 \| -10 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -3 \| -4 \| -6 \| -7 \| -8 \| -9>` | No | `-` | - |
+| `maxHeight` | `ResponsiveProp<MaxHeight<string \| number>>` | No | `-` | - |
+| `maxWidth` | `ResponsiveProp<MaxWidth<string \| number>>` | No | `-` | - |
+| `media` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | React node to display as the main media content. When provided, it will be rendered in a Box container. |
+| `minHeight` | `ResponsiveProp<MinHeight<string \| number>>` | No | `-` | - |
+| `minWidth` | `ResponsiveProp<MinWidth<string \| number>>` | No | `-` | - |
+| `noScaleOnPress` | `boolean` | No | `-` | Dont scale element on press. |
+| `onActionButtonClick` | `((event: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` | No | `-` | Callback fired when the action button is clicked. Only used when action is a string. |
+| `onDismissButtonClick` | `((event: MouseEvent<HTMLButtonElement, MouseEvent>) => void)` | No | `-` | Callback fired when the dismiss button is clicked. When provided, a default dismiss button will be rendered in the top-right corner. |
+| `opacity` | `inherit \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `overflow` | `ResponsiveProp<hidden \| auto \| visible \| clip \| scroll>` | No | `-` | - |
+| `padding` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `paddingBottom` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `paddingEnd` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `paddingStart` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `paddingTop` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `paddingX` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `paddingY` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `pin` | `top \| bottom \| left \| right \| all` | No | `-` | Direction in which to absolutely pin the box. |
+| `position` | `ResponsiveProp<fixed \| static \| relative \| absolute \| sticky>` | No | `-` | - |
+| `pressed` | `boolean` | No | `-` | Is the element being pressed. Primarily a mobile feature, but can be used on the web. |
+| `ref` | `any` | No | `-` | - |
+| `renderAsPressable` | `boolean` | No | `true if `as` is 'button' or 'a', otherwise false` | If true, the CardRoot will be rendered as a Pressable component. When false, renders as an HStack for layout purposes. |
+| `right` | `ResponsiveProp<Right<string \| number>>` | No | `-` | - |
+| `rowGap` | `0 \| 1 \| 2 \| 0.25 \| 0.5 \| 0.75 \| 1.5 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10` | No | `-` | - |
+| `style` | `CSSProperties` | No | `-` | - |
+| `styles` | `({ layoutContainer?: CSSProperties; contentContainer?: CSSProperties \| undefined; textContainer?: CSSProperties \| undefined; mediaContainer?: CSSProperties \| undefined; dismissButtonContainer?: CSSProperties \| undefined; } & { root?: CSSProperties \| undefined; }) \| undefined` | No | `-` | - |
+| `tag` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Text or React node to display as a tag. When a string is provided, it will be rendered in a Tag component. |
+| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
+| `textAlign` | `ResponsiveProp<center \| start \| end \| justify>` | No | `-` | - |
+| `textDecoration` | `ResponsiveProp<none \| underline \| overline \| line-through \| underline overline \| underline double>` | No | `-` | - |
+| `textTransform` | `ResponsiveProp<capitalize \| lowercase \| none \| uppercase>` | No | `-` | - |
+| `title` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Text or React node to display as the card title. Use a Text component to override default color and font. |
+| `top` | `ResponsiveProp<Top<string \| number>>` | No | `-` | - |
+| `transform` | `inherit \| none \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+| `transparentWhileInactive` | `boolean` | No | `-` | Mark the background and border as transparent until the element is interacted with (hovered, pressed, etc). Must be used in conjunction with the pressed prop |
+| `transparentWhilePressed` | `boolean` | No | `-` | Mark the background and border as transparent even while element is interacted with (elevation underlay issue). Must be used in conjunction with the pressed prop |
+| `userSelect` | `ResponsiveProp<text \| none \| auto \| all>` | No | `-` | - |
+| `visibility` | `ResponsiveProp<hidden \| visible>` | No | `-` | - |
+| `width` | `ResponsiveProp<Width<string \| number>>` | No | `-` | - |
+| `zIndex` | `inherit \| auto \| revert \| -moz-initial \| initial \| revert-layer \| unset` | No | `-` | - |
+
+