From 8e2c7570ad0a9ed9e429cab5cf7f64227cb90db3 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 27 Mar 2025 16:07:02 -0400
Subject: [PATCH 1/3] chore(clerk-js,types): Remove `<PlanCard />` from
 commerce components

---
 .../ui/components/PricingTable/PlanCard.tsx   | 474 ------------------
 .../PricingTable/PricingTableMatrix.tsx       |   4 +-
 .../PricingTable/SubscriptionDetailDrawer.tsx | 320 +++++++++++-
 .../ui/customizables/elementDescriptors.ts    |  46 +-
 .../clerk-js/src/ui/polishedAppearance.ts     |   7 -
 packages/types/src/appearance.ts              |  44 +-
 6 files changed, 354 insertions(+), 541 deletions(-)
 delete mode 100644 packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx

diff --git a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
deleted file mode 100644
index de5b2fee4f9..00000000000
--- a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
+++ /dev/null
@@ -1,474 +0,0 @@
-import type {
-  __experimental_CommercePlanResource,
-  __experimental_CommerceSubscriptionPlanPeriod,
-  __experimental_PricingTableProps,
-} from '@clerk/types';
-import * as React from 'react';
-
-import {
-  Badge,
-  Box,
-  Button,
-  descriptors,
-  Flex,
-  Heading,
-  Icon,
-  localizationKeys,
-  SimpleButton,
-  Span,
-  Text,
-  useAppearance,
-} from '../../customizables';
-import { Avatar, SegmentedControl } from '../../elements';
-import { usePrefersReducedMotion } from '../../hooks';
-import { Check, InformationCircle, Minus, Plus } from '../../icons';
-import type { ThemableCssProp } from '../../styledSystem';
-import { common } from '../../styledSystem';
-import { colors } from '../../utils';
-
-/* -------------------------------------------------------------------------------------------------
- * PlanCard
- * -----------------------------------------------------------------------------------------------*/
-
-interface PlanCardProps {
-  plan: __experimental_CommercePlanResource;
-  planPeriod: __experimental_CommerceSubscriptionPlanPeriod;
-  setPlanPeriod: (p: __experimental_CommerceSubscriptionPlanPeriod) => void;
-  onSelect: (plan: __experimental_CommercePlanResource) => void;
-  isCompact?: boolean;
-  props: __experimental_PricingTableProps;
-}
-
-export function PlanCard(props: PlanCardProps) {
-  const { plan, planPeriod, setPlanPeriod, onSelect, props: pricingTableProps, isCompact = false } = props;
-  const isDefaultLayout = pricingTableProps.layout === 'default';
-  const ctaPosition = (isDefaultLayout && pricingTableProps.ctaPosition) || 'top';
-  const collapseFeatures = (isDefaultLayout && pricingTableProps.collapseFeatures) || false;
-  const { id, slug, subscriptionIdForCurrentSubscriber, features } = plan;
-  const totalFeatures = features.length;
-  const hasFeatures = totalFeatures > 0;
-
-  return (
-    <Box
-      key={id}
-      elementDescriptor={[descriptors.planCard, isCompact ? descriptors.planCardCompact : descriptors.planCardDefault]}
-      elementId={descriptors.planCard.setId(slug)}
-      sx={t => ({
-        display: 'flex',
-        flexDirection: 'column',
-        background: common.mergedColorsBackground(
-          colors.setAlpha(t.colors.$colorBackground, 1),
-          t.colors.$neutralAlpha50,
-        ),
-        borderWidth: t.borderWidths.$normal,
-        borderStyle: t.borderStyles.$solid,
-        borderColor: t.colors.$neutralAlpha100,
-        boxShadow: !isCompact ? t.shadows.$cardBoxShadow : undefined,
-        borderRadius: t.radii.$xl,
-        overflow: 'hidden',
-        textAlign: 'left',
-      })}
-    >
-      <PlanCardHeader
-        plan={plan}
-        isCompact={isCompact}
-        isActivePlan={!!subscriptionIdForCurrentSubscriber}
-        planPeriod={planPeriod}
-        setPlanPeriod={setPlanPeriod}
-      />
-      <ReversibleContainer reverse={ctaPosition === 'top'}>
-        {!collapseFeatures && hasFeatures ? (
-          <Box
-            elementDescriptor={descriptors.planCardFeatures}
-            sx={t => ({
-              display: 'flex',
-              flexDirection: 'column',
-              flex: '1',
-              padding: isCompact ? t.space.$3 : t.space.$4,
-              backgroundColor: t.colors.$colorBackground,
-              borderTopWidth: t.borderWidths.$normal,
-              borderTopStyle: t.borderStyles.$solid,
-              borderTopColor: t.colors.$neutralAlpha100,
-            })}
-          >
-            <PlanCardFeaturesList
-              plan={plan}
-              isCompact={isCompact}
-            />
-          </Box>
-        ) : null}
-        <Box
-          elementDescriptor={descriptors.planCardAction}
-          sx={t => ({
-            marginTop: 'auto',
-            padding: isCompact ? t.space.$3 : t.space.$4,
-            borderTopWidth: t.borderWidths.$normal,
-            borderTopStyle: t.borderStyles.$solid,
-            borderTopColor: t.colors.$neutralAlpha100,
-            background: collapseFeatures || !hasFeatures ? t.colors.$colorBackground : undefined,
-          })}
-        >
-          <Button
-            block
-            textVariant={isCompact ? 'buttonSmall' : 'buttonLarge'}
-            variant={isCompact || !!subscriptionIdForCurrentSubscriber ? 'bordered' : 'solid'}
-            colorScheme={isCompact || !!subscriptionIdForCurrentSubscriber ? 'secondary' : 'primary'}
-            localizationKey={
-              subscriptionIdForCurrentSubscriber
-                ? localizationKeys('__experimental_commerce.manageMembership')
-                : localizationKeys('__experimental_commerce.getStarted')
-            }
-            onClick={() => {
-              onSelect(plan);
-            }}
-          />
-        </Box>
-      </ReversibleContainer>
-    </Box>
-  );
-}
-
-/* -------------------------------------------------------------------------------------------------
- * PlanCardHeader
- * -----------------------------------------------------------------------------------------------*/
-
-interface PlanCardHeaderProps {
-  plan: __experimental_CommercePlanResource;
-  isCompact?: boolean;
-  isActivePlan?: boolean;
-  planPeriod: __experimental_CommerceSubscriptionPlanPeriod;
-  setPlanPeriod: (val: __experimental_CommerceSubscriptionPlanPeriod) => void;
-  closeSlot?: React.ReactNode;
-}
-
-export const PlanCardHeader = React.forwardRef<HTMLDivElement, PlanCardHeaderProps>((props, ref) => {
-  const prefersReducedMotion = usePrefersReducedMotion();
-  const { animations: layoutAnimations } = useAppearance().parsedLayout;
-  const { plan, isCompact, planPeriod, setPlanPeriod, closeSlot } = props;
-  const { name, avatarUrl, subscriptionIdForCurrentSubscriber, annualMonthlyAmount } = plan;
-  const isMotionSafe = !prefersReducedMotion && layoutAnimations === true;
-  const planCardFeePeriodNoticeAnimation: ThemableCssProp = t => ({
-    transition: isMotionSafe
-      ? `grid-template-rows ${t.transitionDuration.$slower} ${t.transitionTiming.$slowBezier}`
-      : 'none',
-  });
-  const getPlanFee = React.useMemo(() => {
-    if (annualMonthlyAmount <= 0) {
-      return plan.amountFormatted;
-    }
-    return planPeriod === 'annual' ? plan.annualMonthlyAmountFormatted : plan.amountFormatted;
-  }, [annualMonthlyAmount, planPeriod, plan.amountFormatted, plan.annualMonthlyAmountFormatted]);
-  return (
-    <Box
-      ref={ref}
-      elementDescriptor={descriptors.planCardHeader}
-      sx={t => ({
-        width: '100%',
-        padding: isCompact ? t.space.$3 : t.space.$4,
-      })}
-    >
-      {avatarUrl || !!subscriptionIdForCurrentSubscriber || closeSlot ? (
-        <Box
-          elementDescriptor={descriptors.planCardAvatarBadgeContainer}
-          sx={t => ({
-            marginBlockEnd: t.space.$3,
-            display: 'flex',
-            alignItems: 'flex-start',
-            justifyContent: 'space-between',
-            flexWrap: 'wrap',
-            gap: t.space.$3,
-            float: !avatarUrl && !subscriptionIdForCurrentSubscriber ? 'right' : undefined,
-          })}
-        >
-          {avatarUrl ? (
-            <Avatar
-              boxElementDescriptor={descriptors.planCardAvatar}
-              size={_ => 40}
-              title={name}
-              initials={name[0]}
-              rounded={false}
-              imageUrl={avatarUrl}
-            />
-          ) : null}
-          <ReversibleContainer reverse={!avatarUrl}>
-            {closeSlot}
-            {subscriptionIdForCurrentSubscriber ? (
-              <Span
-                elementDescriptor={descriptors.planCardBadgeContainer}
-                sx={{
-                  flexBasis: closeSlot && avatarUrl ? '100%' : undefined,
-                }}
-              >
-                <Badge
-                  elementDescriptor={descriptors.planCardBadge}
-                  localizationKey={localizationKeys('badge__currentPlan')}
-                  colorScheme='secondary'
-                />
-              </Span>
-            ) : null}
-          </ReversibleContainer>
-        </Box>
-      ) : null}
-      <Heading
-        elementDescriptor={descriptors.planCardTitle}
-        as='h2'
-        textVariant={isCompact ? 'h3' : 'h2'}
-      >
-        {plan.name}
-      </Heading>
-      {!isCompact && plan.description ? (
-        <Text
-          elementDescriptor={descriptors.planCardDescription}
-          variant='subtitle'
-          colorScheme='secondary'
-        >
-          {plan.description}
-        </Text>
-      ) : null}
-      <Flex
-        elementDescriptor={descriptors.planCardFeeContainer}
-        align='center'
-        wrap='wrap'
-        sx={t => ({
-          marginTop: isCompact ? t.space.$2 : t.space.$3,
-          columnGap: t.space.$1x5,
-        })}
-      >
-        {plan.hasBaseFee ? (
-          <>
-            <Text
-              elementDescriptor={descriptors.planCardFee}
-              variant={isCompact ? 'h2' : 'h1'}
-              colorScheme='body'
-            >
-              {plan.currencySymbol}
-              {getPlanFee}
-            </Text>
-            <Text
-              elementDescriptor={descriptors.planCardFeePeriod}
-              variant='caption'
-              colorScheme='secondary'
-              sx={t => ({
-                textTransform: 'lowercase',
-                ':before': {
-                  content: '"/"',
-                  marginInlineEnd: t.space.$1,
-                },
-              })}
-              localizationKey={localizationKeys('__experimental_commerce.month')}
-            />
-            {annualMonthlyAmount > 0 ? (
-              <Box
-                elementDescriptor={descriptors.planCardFeePeriodNotice}
-                sx={[
-                  _ => ({
-                    width: '100%',
-                    display: 'grid',
-                    gridTemplateRows: planPeriod === 'annual' ? '1fr' : '0fr',
-                  }),
-                  planCardFeePeriodNoticeAnimation,
-                ]}
-                // @ts-ignore - Needed until React 19 support
-                inert={planPeriod !== 'annual' ? 'true' : undefined}
-              >
-                <Box
-                  elementDescriptor={descriptors.planCardFeePeriodNoticeInner}
-                  sx={{
-                    overflow: 'hidden',
-                    minHeight: 0,
-                  }}
-                >
-                  <Text
-                    elementDescriptor={descriptors.planCardFeePeriodNoticeLabel}
-                    variant='caption'
-                    colorScheme='secondary'
-                    sx={t => ({
-                      width: '100%',
-                      display: 'flex',
-                      alignItems: 'center',
-                      columnGap: t.space.$1,
-                    })}
-                  >
-                    <Icon
-                      icon={InformationCircle}
-                      colorScheme='neutral'
-                      size='sm'
-                      aria-hidden
-                    />{' '}
-                    <Span localizationKey={localizationKeys('__experimental_commerce.billedAnnually')} />
-                  </Text>
-                </Box>
-              </Box>
-            ) : null}
-          </>
-        ) : (
-          <Text
-            elementDescriptor={descriptors.planCardFee}
-            variant={isCompact ? 'h2' : 'h1'}
-            localizationKey={localizationKeys('__experimental_commerce.free')}
-            colorScheme='body'
-          />
-        )}
-      </Flex>
-      {plan.hasBaseFee && annualMonthlyAmount > 0 && setPlanPeriod ? (
-        <Box
-          elementDescriptor={descriptors.planCardPeriodToggle}
-          sx={t => ({
-            display: 'flex',
-            marginTop: t.space.$3,
-          })}
-        >
-          <SegmentedControl.Root
-            aria-label='Set pay period'
-            value={planPeriod}
-            onChange={value => setPlanPeriod(value as __experimental_CommerceSubscriptionPlanPeriod)}
-          >
-            <SegmentedControl.Button
-              value='month'
-              // TODO(@Commerce): needs localization
-              text='Monthly'
-            />
-            <SegmentedControl.Button
-              value='annual'
-              // TODO(@Commerce): needs localization
-              text='Annually'
-            />
-          </SegmentedControl.Root>
-        </Box>
-      ) : null}
-    </Box>
-  );
-});
-
-/* -------------------------------------------------------------------------------------------------
- * PlanCardFeaturesList
- * -----------------------------------------------------------------------------------------------*/
-
-interface PlanCardFeaturesListProps {
-  plan: __experimental_CommercePlanResource;
-  /**
-   * @default false
-   */
-  isCompact?: boolean;
-  /**
-   * @default `checkmark`
-   */
-  variant?: 'checkmark' | 'avatar';
-}
-
-export const PlanCardFeaturesList = React.forwardRef<HTMLDivElement, PlanCardFeaturesListProps>((props, ref) => {
-  const { plan, isCompact, variant = 'checkmark' } = props;
-  const totalFeatures = plan.features.length;
-  const [showAllFeatures, setShowAllFeatures] = React.useState(false);
-  const canToggleFeatures = isCompact && totalFeatures > 3;
-  const toggleFeatures = () => {
-    setShowAllFeatures(prev => !prev);
-  };
-  return (
-    <Box
-      ref={ref}
-      elementDescriptor={descriptors.planCardFeatures}
-      sx={t => ({
-        display: 'grid',
-        flex: '1',
-        rowGap: isCompact ? t.space.$2 : t.space.$3,
-      })}
-    >
-      <Box
-        elementDescriptor={descriptors.planCardFeaturesList}
-        elementId={
-          isCompact
-            ? descriptors.planCardFeaturesList.setId('compact')
-            : descriptors.planCardFeaturesList.setId(variant)
-        }
-        as='ul'
-        role='list'
-        sx={t => ({
-          display: 'grid',
-          flex: '1',
-          rowGap: variant === 'avatar' ? t.space.$4 : isCompact ? t.space.$2 : t.space.$3,
-        })}
-      >
-        {plan.features.slice(0, showAllFeatures || !canToggleFeatures ? totalFeatures : 3).map(feature => (
-          <Box
-            elementDescriptor={descriptors.planCardFeaturesListItem}
-            elementId={descriptors.planCardFeaturesListItem.setId(feature.slug)}
-            key={feature.id}
-            as='li'
-            sx={t => ({
-              display: 'flex',
-              alignItems: 'baseline',
-              gap: variant === 'checkmark' ? t.space.$2 : t.space.$3,
-            })}
-          >
-            {variant === 'checkmark' ? (
-              <Icon
-                icon={Check}
-                colorScheme='neutral'
-                size='sm'
-                aria-hidden
-                sx={t => ({
-                  transform: `translateY(${t.space.$0x25})`,
-                })}
-              />
-            ) : feature.avatarUrl ? (
-              <Avatar
-                size={_ => 24}
-                title={feature.name}
-                initials={feature.name[0]}
-                rounded={false}
-                imageUrl={feature.avatarUrl}
-              />
-            ) : null}
-            <Span elementDescriptor={descriptors.planCardFeaturesListItemContent}>
-              <Text
-                elementDescriptor={descriptors.planCardFeaturesListItemTitle}
-                colorScheme='body'
-                sx={t => ({
-                  fontWeight: variant === 'checkmark' ? t.fontWeights.$normal : t.fontWeights.$medium,
-                })}
-              >
-                {feature.name}
-              </Text>
-              {variant === 'avatar' && feature.description ? (
-                <Text
-                  elementDescriptor={descriptors.planCardFeaturesListItemDescription}
-                  colorScheme='secondary'
-                  sx={t => ({
-                    marginBlockStart: t.space.$0x25,
-                    fontSize: t.fontSizes.$xs,
-                  })}
-                >
-                  {feature.description}
-                </Text>
-              ) : null}
-            </Span>
-          </Box>
-        ))}
-      </Box>
-      {canToggleFeatures && (
-        <SimpleButton
-          onClick={toggleFeatures}
-          variant='link'
-          sx={t => ({
-            marginBlockStart: t.space.$2,
-            gap: t.space.$1,
-          })}
-        >
-          <Icon
-            icon={showAllFeatures ? Minus : Plus}
-            colorScheme='neutral'
-            size='md'
-            aria-hidden
-          />
-          {showAllFeatures ? 'Hide features' : 'See all features'}
-        </SimpleButton>
-      )}
-    </Box>
-  );
-});
-
-function ReversibleContainer(props: React.PropsWithChildren<{ reverse?: boolean }>) {
-  const { children, reverse } = props;
-  return <>{reverse ? React.Children.toArray(children).reverse() : children}</>;
-}
diff --git a/packages/clerk-js/src/ui/components/PricingTable/PricingTableMatrix.tsx b/packages/clerk-js/src/ui/components/PricingTable/PricingTableMatrix.tsx
index 4bad13fa7e4..e873873b6b8 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/PricingTableMatrix.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/PricingTableMatrix.tsx
@@ -41,7 +41,7 @@ export function PricingTableMatrix({
   const pricingTableMatrixId = React.useId();
   const segmentedControlId = `${pricingTableMatrixId}-segmented-control`;
 
-  const planCardFeePeriodNoticeAnimation: ThemableCssProp = t => ({
+  const feePeriodNoticeAnimation: ThemableCssProp = t => ({
     transition: isMotionSafe
       ? `grid-template-rows ${t.transitionDuration.$slower} ${t.transitionTiming.$slowBezier}`
       : 'none',
@@ -258,7 +258,7 @@ export function PricingTableMatrix({
                                     display: 'grid',
                                     gridTemplateRows: planPeriod === 'annual' ? '1fr' : '0fr',
                                   }),
-                                  planCardFeePeriodNoticeAnimation,
+                                  feePeriodNoticeAnimation,
                                 ]}
                                 // @ts-ignore - Needed until React 19 support
                                 inert={planPeriod !== 'annual' ? 'true' : undefined}
diff --git a/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx b/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx
index 154f68bb905..d9ec78c350b 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx
@@ -1,15 +1,28 @@
 import type {
+  __experimental_CommercePlanResource,
   __experimental_CommerceSubscriptionPlanPeriod,
   __experimental_CommerceSubscriptionResource,
   ClerkAPIError,
   ClerkRuntimeError,
 } from '@clerk/types';
 import { useState } from 'react';
+import * as React from 'react';
 
-import { Box, Button, descriptors, Heading, Text } from '../../customizables';
-import { Alert, Drawer } from '../../elements';
+import {
+  Badge,
+  Box,
+  Button,
+  descriptors,
+  Flex,
+  Heading,
+  Icon,
+  localizationKeys,
+  Span,
+  Text,
+} from '../../customizables';
+import { Alert, Avatar, Drawer, ReversibleContainer } from '../../elements';
+import { InformationCircle } from '../../icons';
 import { handleError } from '../../utils';
-import { PlanCardFeaturesList, PlanCardHeader } from './PlanCard';
 
 type DrawerRootProps = React.ComponentProps<typeof Drawer.Root>;
 
@@ -38,7 +51,73 @@ export function SubscriptionDetailDrawer({
   if (!subscription) {
     return null;
   }
-  const hasFeatures = subscription.plan.features.length > 0;
+  const features = [
+    {
+      id: 'cfeat_2uapwNo0lHXMvNaMt0PFgd1V6Ps',
+      pathRoot: '',
+      name: 'Feature 1',
+      description: '',
+      slug: 'feature-1',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT5CevPPwmuFJhT5qR2UHO7l4',
+      pathRoot: '',
+      name: 'Feature 2',
+      description: '',
+      slug: 'feature-2',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT5zIQRIcRugQVl2Xnz2KXnli',
+      pathRoot: '',
+      name: 'Feature 3',
+      description: '',
+      slug: 'feature-3',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT6m2hnOSJ3qRERIfs1rD5bCc',
+      pathRoot: '',
+      name: 'Feature 4',
+      description: '',
+      slug: 'feature-4',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT7VaMzkn3gaCM1fH5ji8Jycl',
+      pathRoot: '',
+      name: 'Feature 5',
+      description: '',
+      slug: 'feature-5',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT8GyPDO9m3optnA8qPF5oCeX',
+      pathRoot: '',
+      name: 'Feature 6',
+      description: '',
+      slug: 'feature-6',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT90HapHS5U0xyCotqUSZJ9wm',
+      pathRoot: '',
+      name: 'Feature 7',
+      description: '',
+      slug: 'feature-7',
+      avatarUrl: '',
+    },
+    {
+      id: 'cfeat_2udT9nT2DEI4bsls80IdbgWBrZf',
+      pathRoot: '',
+      name: 'Feature 8',
+      description: 'This is an example description',
+      slug: 'feature-8',
+      avatarUrl: '',
+    },
+  ];
+  const hasFeatures = features.length > 0;
   const cancelSubscription = async () => {
     setCancelError(undefined);
     setIsSubmitting(true);
@@ -76,7 +155,7 @@ export function SubscriptionDetailDrawer({
               : null
           }
         >
-          <PlanCardHeader
+          <Header
             plan={subscription.plan}
             planPeriod={subscription.planPeriod}
             setPlanPeriod={setPlanPeriod}
@@ -87,14 +166,60 @@ export function SubscriptionDetailDrawer({
         {hasFeatures ? (
           <Drawer.Body>
             <Box
+              elementDescriptor={descriptors.subscriptionDetailFeaturesList}
+              as='ul'
+              role='list'
               sx={t => ({
+                display: 'grid',
+                rowGap: t.space.$4,
                 padding: t.space.$4,
               })}
             >
-              <PlanCardFeaturesList
-                plan={subscription.plan}
-                variant='avatar'
-              />
+              {features.map(feature => (
+                <Box
+                  key={feature.id}
+                  elementDescriptor={descriptors.subscriptionDetailFeaturesListItem}
+                  as='li'
+                  sx={t => ({
+                    display: 'flex',
+                    alignItems: 'baseline',
+                    gap: t.space.$3,
+                  })}
+                >
+                  {feature.avatarUrl ? (
+                    <Avatar
+                      size={_ => 24}
+                      title={feature.name}
+                      initials={feature.name[0]}
+                      rounded={false}
+                      imageUrl={feature.avatarUrl}
+                    />
+                  ) : null}
+                  <Span elementDescriptor={descriptors.subscriptionDetailFeaturesListItemContent}>
+                    <Text
+                      elementDescriptor={descriptors.subscriptionDetailFeaturesListItemTitle}
+                      colorScheme='body'
+                      sx={t => ({
+                        fontWeight: t.fontWeights.$medium,
+                      })}
+                    >
+                      {feature.name}
+                    </Text>
+                    {feature.description ? (
+                      <Text
+                        elementDescriptor={descriptors.subscriptionDetailFeaturesListItemDescription}
+                        colorScheme='secondary'
+                        sx={t => ({
+                          marginBlockStart: t.space.$0x25,
+                          fontSize: t.fontSizes.$xs,
+                        })}
+                      >
+                        {feature.description}
+                      </Text>
+                    ) : null}
+                  </Span>
+                </Box>
+              ))}
             </Box>
           </Drawer.Body>
         ) : null}
@@ -171,3 +296,180 @@ export function SubscriptionDetailDrawer({
     </Drawer.Root>
   );
 }
+
+/* -------------------------------------------------------------------------------------------------
+ * Header
+ * -----------------------------------------------------------------------------------------------*/
+
+interface HeaderProps {
+  plan: __experimental_CommercePlanResource;
+  isActivePlan?: boolean;
+  planPeriod: __experimental_CommerceSubscriptionPlanPeriod;
+  setPlanPeriod: (val: __experimental_CommerceSubscriptionPlanPeriod) => void;
+  closeSlot?: React.ReactNode;
+}
+
+const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
+  const { plan, planPeriod, setPlanPeriod, closeSlot } = props;
+  const { name, avatarUrl, subscriptionIdForCurrentSubscriber, annualMonthlyAmount } = plan;
+  const getPlanFee = React.useMemo(() => {
+    if (annualMonthlyAmount <= 0) {
+      return plan.amountFormatted;
+    }
+    return planPeriod === 'annual' ? plan.annualMonthlyAmountFormatted : plan.amountFormatted;
+  }, [annualMonthlyAmount, planPeriod, plan.amountFormatted, plan.annualMonthlyAmountFormatted]);
+
+  return (
+    <Box
+      ref={ref}
+      elementDescriptor={descriptors.subscriptionDetailHeader}
+      sx={t => ({
+        width: '100%',
+        padding: t.space.$4,
+      })}
+    >
+      {avatarUrl || !!subscriptionIdForCurrentSubscriber || closeSlot ? (
+        <Box
+          elementDescriptor={descriptors.subscriptionDetailAvatarBadgeContainer}
+          sx={t => ({
+            marginBlockEnd: t.space.$3,
+            display: 'flex',
+            alignItems: 'flex-start',
+            justifyContent: 'space-between',
+            flexWrap: 'wrap',
+            gap: t.space.$3,
+            float: !avatarUrl && !subscriptionIdForCurrentSubscriber ? 'right' : undefined,
+          })}
+        >
+          {avatarUrl ? (
+            <Avatar
+              boxElementDescriptor={descriptors.subscriptionDetailAvatar}
+              size={_ => 40}
+              title={name}
+              initials={name[0]}
+              rounded={false}
+              imageUrl={avatarUrl}
+            />
+          ) : null}
+          <ReversibleContainer reverse={!avatarUrl}>
+            {closeSlot}
+            {subscriptionIdForCurrentSubscriber ? (
+              <Span
+                elementDescriptor={descriptors.subscriptionDetailBadgeContainer}
+                sx={{
+                  flexBasis: closeSlot && avatarUrl ? '100%' : undefined,
+                }}
+              >
+                <Badge
+                  elementDescriptor={descriptors.subscriptionDetailBadge}
+                  localizationKey={localizationKeys('badge__currentPlan')}
+                  colorScheme='secondary'
+                />
+              </Span>
+            ) : null}
+          </ReversibleContainer>
+        </Box>
+      ) : null}
+      <Heading
+        elementDescriptor={descriptors.subscriptionDetailTitle}
+        as='h2'
+        textVariant='h2'
+      >
+        {plan.name}
+      </Heading>
+      {plan.description ? (
+        <Text
+          elementDescriptor={descriptors.subscriptionDetailDescription}
+          variant='subtitle'
+          colorScheme='secondary'
+        >
+          {plan.description}
+        </Text>
+      ) : null}
+      <Flex
+        elementDescriptor={descriptors.subscriptionDetailFeeContainer}
+        align='center'
+        wrap='wrap'
+        sx={t => ({
+          marginTop: t.space.$3,
+          columnGap: t.space.$1x5,
+        })}
+      >
+        {plan.hasBaseFee ? (
+          <>
+            <Text
+              elementDescriptor={descriptors.subscriptionDetailFee}
+              variant='h1'
+              colorScheme='body'
+            >
+              {plan.currencySymbol}
+              {getPlanFee}
+            </Text>
+            <Text
+              elementDescriptor={descriptors.subscriptionDetailFeePeriod}
+              variant='caption'
+              colorScheme='secondary'
+              sx={t => ({
+                textTransform: 'lowercase',
+                ':before': {
+                  content: '"/"',
+                  marginInlineEnd: t.space.$1,
+                },
+              })}
+              localizationKey={localizationKeys('__experimental_commerce.month')}
+            />
+            {annualMonthlyAmount > 0 ? (
+              <Box
+                elementDescriptor={descriptors.subscriptionDetailFeePeriodNotice}
+                sx={[
+                  _ => ({
+                    width: '100%',
+                    display: 'grid',
+                    gridTemplateRows: planPeriod === 'annual' ? '1fr' : '0fr',
+                  }),
+                ]}
+                // @ts-ignore - Needed until React 19 support
+                inert={planPeriod !== 'annual' ? 'true' : undefined}
+              >
+                <Box
+                  elementDescriptor={descriptors.subscriptionDetailFeePeriodNoticeInner}
+                  sx={{
+                    overflow: 'hidden',
+                    minHeight: 0,
+                  }}
+                >
+                  <Text
+                    elementDescriptor={descriptors.subscriptionDetailFeePeriodNoticeLabel}
+                    variant='caption'
+                    colorScheme='secondary'
+                    sx={t => ({
+                      width: '100%',
+                      display: 'flex',
+                      alignItems: 'center',
+                      columnGap: t.space.$1,
+                    })}
+                  >
+                    <Icon
+                      icon={InformationCircle}
+                      colorScheme='neutral'
+                      size='sm'
+                      aria-hidden
+                    />{' '}
+                    <Span localizationKey={localizationKeys('__experimental_commerce.billedAnnually')} />
+                  </Text>
+                </Box>
+              </Box>
+            ) : null}
+          </>
+        ) : (
+          <Text
+            elementDescriptor={descriptors.subscriptionDetailFee}
+            variant='h1'
+            localizationKey={localizationKeys('__experimental_commerce.free')}
+            colorScheme='body'
+          />
+        )}
+      </Flex>
+    </Box>
+  );
+});
diff --git a/packages/clerk-js/src/ui/customizables/elementDescriptors.ts b/packages/clerk-js/src/ui/customizables/elementDescriptors.ts
index 55d1227815d..9658dc0ad4d 100644
--- a/packages/clerk-js/src/ui/customizables/elementDescriptors.ts
+++ b/packages/clerk-js/src/ui/customizables/elementDescriptors.ts
@@ -235,31 +235,6 @@ export const APPEARANCE_KEYS = containsAllElementsConfigKeys([
   'accountSwitcherActionButtonIconBox',
   'accountSwitcherActionButtonIcon',
 
-  'planCard',
-  'planCardDefault',
-  'planCardCompact',
-  'planCardHeader',
-  'planCardTitle',
-  'planCardDescription',
-  'planCardAvatarBadgeContainer',
-  'planCardAvatar',
-  'planCardBadgeContainer',
-  'planCardBadge',
-  'planCardFeatures',
-  'planCardFeaturesList',
-  'planCardFeaturesListItem',
-  'planCardFeaturesListItemContent',
-  'planCardFeaturesListItemTitle',
-  'planCardFeaturesListItemDescription',
-  'planCardAction',
-  'planCardPeriodToggle',
-  'planCardFeeContainer',
-  'planCardFee',
-  'planCardFeePeriod',
-  'planCardFeePeriodNotice',
-  'planCardFeePeriodNoticeInner',
-  'planCardFeePeriodNoticeLabel',
-
   'pricingTable',
   'pricingTableCard',
   'pricingTableCardHeader',
@@ -305,6 +280,27 @@ export const APPEARANCE_KEYS = containsAllElementsConfigKeys([
   'pricingTableMatrixFeePeriodNoticeLabel',
   'pricingTableMatrixFooter',
 
+  'subscriptionDetailHeader',
+  'subscriptionDetailAvatarBadgeContainer',
+  'subscriptionDetailAvatar',
+  'subscriptionDetailBadgeContainer',
+  'subscriptionDetailBadge',
+  'subscriptionDetailTitle',
+  'subscriptionDetailDescription',
+  'subscriptionDetailAction',
+  'subscriptionDetailFeeContainer',
+  'subscriptionDetailFee',
+  'subscriptionDetailFeePeriod',
+  'subscriptionDetailFeePeriodNotice',
+  'subscriptionDetailFeePeriodNoticeInner',
+  'subscriptionDetailFeePeriodNoticeLabel',
+  'subscriptionDetailFeatures',
+  'subscriptionDetailFeaturesList',
+  'subscriptionDetailFeaturesListItem',
+  'subscriptionDetailFeaturesListItemContent',
+  'subscriptionDetailFeaturesListItemTitle',
+  'subscriptionDetailFeaturesListItemDescription',
+
   'segmentedControlRoot',
   'segmentedControlButton',
 
diff --git a/packages/clerk-js/src/ui/polishedAppearance.ts b/packages/clerk-js/src/ui/polishedAppearance.ts
index ea4f43792e1..5315d127be4 100644
--- a/packages/clerk-js/src/ui/polishedAppearance.ts
+++ b/packages/clerk-js/src/ui/polishedAppearance.ts
@@ -241,13 +241,6 @@ export const polishedAppearance: Appearance = {
           boxShadow: 'none',
         },
       },
-      planCardDefault: {
-        borderWidth: 0,
-        boxShadow: `${theme.shadows.$cardBoxShadow}, ${BORDER_SHADOW_LENGTH} ${theme.colors.$neutralAlpha100}`,
-      },
-      planCardCompact: {
-        boxShadow: 'none',
-      },
       scrollBox: {
         ...cardContentStyles(theme),
       },
diff --git a/packages/types/src/appearance.ts b/packages/types/src/appearance.ts
index e407169cd87..a992b7dfbef 100644
--- a/packages/types/src/appearance.ts
+++ b/packages/types/src/appearance.ts
@@ -407,30 +407,26 @@ export type ElementsConfig = {
   pricingTableMatrixFeePeriodNoticeLabel: WithOptions;
   pricingTableMatrixFooter: WithOptions;
 
-  planCard: WithOptions<string>;
-  planCardDefault: WithOptions;
-  planCardCompact: WithOptions;
-  planCardHeader: WithOptions;
-  planCardAvatarBadgeContainer: WithOptions;
-  planCardAvatar: WithOptions;
-  planCardBadgeContainer: WithOptions;
-  planCardBadge: WithOptions;
-  planCardTitle: WithOptions;
-  planCardDescription: WithOptions;
-  planCardFeatures: WithOptions;
-  planCardFeaturesList: WithOptions<string>;
-  planCardFeaturesListItem: WithOptions<string>;
-  planCardFeaturesListItemContent: WithOptions;
-  planCardFeaturesListItemTitle: WithOptions;
-  planCardFeaturesListItemDescription: WithOptions;
-  planCardAction: WithOptions;
-  planCardPeriodToggle: WithOptions;
-  planCardFeeContainer: WithOptions;
-  planCardFee: WithOptions;
-  planCardFeePeriod: WithOptions;
-  planCardFeePeriodNotice: WithOptions;
-  planCardFeePeriodNoticeInner: WithOptions;
-  planCardFeePeriodNoticeLabel: WithOptions;
+  subscriptionDetailHeader: WithOptions;
+  subscriptionDetailAvatarBadgeContainer: WithOptions;
+  subscriptionDetailAvatar: WithOptions;
+  subscriptionDetailBadgeContainer: WithOptions;
+  subscriptionDetailBadge: WithOptions;
+  subscriptionDetailTitle: WithOptions;
+  subscriptionDetailDescription: WithOptions;
+  subscriptionDetailAction: WithOptions;
+  subscriptionDetailFeeContainer: WithOptions;
+  subscriptionDetailFee: WithOptions;
+  subscriptionDetailFeePeriod: WithOptions;
+  subscriptionDetailFeePeriodNotice: WithOptions;
+  subscriptionDetailFeePeriodNoticeInner: WithOptions;
+  subscriptionDetailFeePeriodNoticeLabel: WithOptions;
+  subscriptionDetailFeatures: WithOptions;
+  subscriptionDetailFeaturesList: WithOptions<string>;
+  subscriptionDetailFeaturesListItem: WithOptions<string>;
+  subscriptionDetailFeaturesListItemContent: WithOptions;
+  subscriptionDetailFeaturesListItemTitle: WithOptions;
+  subscriptionDetailFeaturesListItemDescription: WithOptions;
 
   alert: WithOptions<AlertId>;
   alertIcon: WithOptions<AlertId>;

From 84d0e2851c1bc00adf8f6b854bab8529123841bb Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 27 Mar 2025 16:09:21 -0400
Subject: [PATCH 2/3] add changeset

---
 .changeset/shaggy-garlics-remain.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .changeset/shaggy-garlics-remain.md

diff --git a/.changeset/shaggy-garlics-remain.md b/.changeset/shaggy-garlics-remain.md
new file mode 100644
index 00000000000..99d588424a0
--- /dev/null
+++ b/.changeset/shaggy-garlics-remain.md
@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Remove usage of `<PlanCard />` from `<SubscriptionDetailDrawer />`.

From 23e87a1c1dfa6a3d2fe071f2f687fcf9895b5ea7 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 27 Mar 2025 16:10:38 -0400
Subject: [PATCH 3/3] cleanup

---
 .../PricingTable/SubscriptionDetailDrawer.tsx | 69 +------------------
 1 file changed, 2 insertions(+), 67 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx b/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx
index d9ec78c350b..0f10817382e 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/SubscriptionDetailDrawer.tsx
@@ -51,72 +51,7 @@ export function SubscriptionDetailDrawer({
   if (!subscription) {
     return null;
   }
-  const features = [
-    {
-      id: 'cfeat_2uapwNo0lHXMvNaMt0PFgd1V6Ps',
-      pathRoot: '',
-      name: 'Feature 1',
-      description: '',
-      slug: 'feature-1',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT5CevPPwmuFJhT5qR2UHO7l4',
-      pathRoot: '',
-      name: 'Feature 2',
-      description: '',
-      slug: 'feature-2',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT5zIQRIcRugQVl2Xnz2KXnli',
-      pathRoot: '',
-      name: 'Feature 3',
-      description: '',
-      slug: 'feature-3',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT6m2hnOSJ3qRERIfs1rD5bCc',
-      pathRoot: '',
-      name: 'Feature 4',
-      description: '',
-      slug: 'feature-4',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT7VaMzkn3gaCM1fH5ji8Jycl',
-      pathRoot: '',
-      name: 'Feature 5',
-      description: '',
-      slug: 'feature-5',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT8GyPDO9m3optnA8qPF5oCeX',
-      pathRoot: '',
-      name: 'Feature 6',
-      description: '',
-      slug: 'feature-6',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT90HapHS5U0xyCotqUSZJ9wm',
-      pathRoot: '',
-      name: 'Feature 7',
-      description: '',
-      slug: 'feature-7',
-      avatarUrl: '',
-    },
-    {
-      id: 'cfeat_2udT9nT2DEI4bsls80IdbgWBrZf',
-      pathRoot: '',
-      name: 'Feature 8',
-      description: 'This is an example description',
-      slug: 'feature-8',
-      avatarUrl: '',
-    },
-  ];
+  const features = subscription.plan.features;
   const hasFeatures = features.length > 0;
   const cancelSubscription = async () => {
     setCancelError(undefined);
@@ -310,7 +245,7 @@ interface HeaderProps {
 }
 
 const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
-  const { plan, planPeriod, setPlanPeriod, closeSlot } = props;
+  const { plan, planPeriod, closeSlot } = props;
   const { name, avatarUrl, subscriptionIdForCurrentSubscriber, annualMonthlyAmount } = plan;
   const getPlanFee = React.useMemo(() => {
     if (annualMonthlyAmount <= 0) {