@pantheon-systems/pds-toolkit-react 2.0.0-alpha.34 → 2.0.0-alpha.36

package/codemods/v1-to-v2/mappings.json

@@ -0,0 +1,1281 @@
+{
+	"version": "2.0.0",
+	"description": "Mappings for migrating from v1.x to v2.x of PDS Toolkit React",
+	"components": {
+		"renames": [
+			{
+				"from": "IndicatorBadge",
+				"to": "Badge",
+				"reason": "IndicatorBadge has been renamed to Badge in v2. The component API has also changed \u2014 see props.typeChanges for color and size migration details."
+			},
+			{
+				"from": "NavMenu",
+				"to": "SiteMenu",
+				"reason": "NavMenu has been renamed to SiteMenu in v2 to better reflect its purpose as a website navigation menu. The component now uses the Disclosure Navigation pattern instead of ARIA menu roles, making it semantically correct for navigation links. The internal NavMenuDropdown subcomponent is now SiteMenuDropdown but was never publicly exported."
+			},
+			{
+				"from": "RefreshChecker",
+				"to": "StatusChecker",
+				"reason": "RefreshChecker has been renamed to StatusChecker in v2 to better reflect its purpose as a general-purpose status display and polling trigger, not limited to page refresh."
+			},
+			{
+				"from": "FlowSteps",
+				"to": "StepList",
+				"reason": "FlowSteps has been renamed to StepList in v2. The FlowStep item type has also been renamed to StepListItem. All props remain the same."
+			},
+			{
+				"from": "CardSelectGroup",
+				"to": "CardSelect",
+				"description": "Renamed for clarity. The Group suffix was redundant since the component is inherently a group."
+			},
+			{
+				"from": "DashboardSearch",
+				"to": "SiteSearch",
+				"reason": "Renamed to SiteSearch to better reflect its purpose as a general-purpose site search input, not limited to dashboard navigation. The component has also moved out of the navigation subdirectory."
+			},
+			{
+				"from": "SideNavCompact",
+				"to": "TreeNav",
+				"description": "SideNavCompact has been renamed to TreeNav in V2 to better reflect its purpose as a multi-level tree navigation for documentation sites. It now implements the ARIA tree view pattern."
+			}
+		],
+		"removals": [
+			{
+				"component": "DashboardStat",
+				"reason": "DashboardStat has been removed in v2 and is not being carried forward. Remove any usage from your application."
+			},
+			{
+				"component": "CardHeading",
+				"reason": "Component removed. Use a semantic heading element (h2, h3, h4, etc.) with a pds-heading-* utility class to control visual size (e.g. <h3 className='pds-heading-xl'>Card title</h3>)."
+			},
+			{
+				"component": "EmptyStateCard",
+				"reason": "Component removed. Use Card with a footer slot. See Patterns/Cards/Empty State Card in Storybook for the recipe."
+			},
+			{
+				"component": "LinksCard",
+				"reason": "Component removed. Use Card. See Patterns/Cards/Links Card in Storybook for the recipe."
+			},
+			{
+				"component": "NewSiteCard",
+				"reason": "Component removed. Use ActionCard. See Patterns/Cards/New Site Card in Storybook for the recipe."
+			},
+			{
+				"component": "PaymentCard",
+				"reason": "Component removed. Use ActionCard. See Patterns/Cards/Payment Card in Storybook for the recipe."
+			},
+			{
+				"component": "PricingCard",
+				"reason": "Component removed. Use Card with a footer slot. See Patterns/Cards/Pricing Card in Storybook for the recipe."
+			},
+			{
+				"component": "SiteCard",
+				"reason": "Component removed. Use ActionCard. See Patterns/Cards/Site Card in Storybook for the recipe."
+			},
+			{
+				"component": "SiteDashboardHeading",
+				"reason": "Component removed. Compose locally using Icon, Badge, Button, and optionally Popover with SiteTypeIcon from custom-types. See Patterns/Site Dashboard Heading in Storybook for the recipe."
+			}
+		],
+		"additions": [
+			{
+				"component": "PaginationMini",
+				"description": "New for V2. A previous/next navigation control with descriptive page labels. Suited for article or document navigation where page numbers are less relevant than content names.",
+				"usage": "Use when navigating linearly through a series of pages such as blog posts, documentation chapters, or wizard steps."
+			},
+			{
+				"component": "PaginationCompact",
+				"description": "New for V2. A space-efficient pagination control combining a page selector dropdown with previous/next buttons. Suited for dense layouts such as table toolbars or sidebars.",
+				"usage": "Use when horizontal space is limited or the total page count is high and users need direct access to any page."
+			}
+		],
+		"deprecations": [
+			{
+				"component": "DashboardGlobal",
+				"reason": "DashboardGlobal has been removed in v2. Use AppLayout instead, which provides a more flexible and composable application shell.",
+				"replacement": "Replace <DashboardGlobal> with <AppLayout>. See the AppLayout documentation for slot-based composition."
+			},
+			{
+				"component": "DashboardInner",
+				"reason": "DashboardInner has been removed in v2. It is no longer necessary as a dedicated inner content wrapper.",
+				"replacement": "No direct replacement. Structure your page content directly within AppLayout's content area."
+			},
+			{
+				"component": "DashboardNav",
+				"reason": "DashboardNav has been removed in v2. Use SideNavGlobal instead, which provides a more flexible sidebar navigation pattern.",
+				"replacement": "Replace <DashboardNav> with <SideNavGlobal>. See the SideNavGlobal documentation for menu item configuration."
+			},
+			{
+				"component": "CTASlice",
+				"reason": "CTASlice has been removed in v2 and is no longer published as a component.",
+				"replacement": "No replacement. Remove usage of <CTASlice> from your application."
+			},
+			{
+				"component": "FooterHeading",
+				"reason": "FooterHeading has been removed in v2.",
+				"replacement": "No direct replacement. Contact the design team for guidance on how to handle footer headings in your application."
+			},
+			{
+				"component": "FooterLinks",
+				"reason": "FooterLinks has been removed in v2.",
+				"replacement": "No direct replacement. Contact the design team for guidance on how to handle footer link groups in your application."
+			},
+			{
+				"component": "PullQuote",
+				"reason": "PullQuote has been removed in v2 and is no longer published as a component.",
+				"replacement": "No replacement. Remove usage of <PullQuote> from your application."
+			},
+			{
+				"component": "AvatarTileList",
+				"reason": "AvatarTileList has been removed in v2 and is no longer published as a component.",
+				"replacement": "No replacement. Remove usage of <AvatarTileList> from your application."
+			},
+			{
+				"component": "Tile",
+				"reason": "Tile has been removed in v2 and is no longer published as a component.",
+				"replacement": "No replacement. Remove usage of <Tile> from your application."
+			},
+			{
+				"component": "TileGrid",
+				"reason": "TileGrid has been removed in v2 and is no longer published as a component.",
+				"replacement": "No replacement. Remove usage of <TileGrid> from your application."
+			},
+			{
+				"component": "SocialLinks",
+				"reason": "SocialLinks has been removed in v2 and is no longer published as a component.",
+				"replacement": "No replacement. Remove usage of <SocialLinks> from your application."
+			}
+		]
+	},
+	"props": {
+		"renames": [
+			{
+				"component": "GlobalWrapper",
+				"from": "mobileMenuMaxWidth",
+				"to": "mobileMaxWidth",
+				"reason": "Renamed for clarity \u2014 the value is the maximum viewport width at which mobile styles are active. The prop now drives the data-pds-mobile attribute on :root used by component CSS to apply mobile styles, replacing the ResponsiveContext isMobile pattern. The default value has changed from 640 to 767 to align exactly with --pds-bp-s-only (max-width: 767px)."
+			},
+			{
+				"component": "ComboboxMultiselect",
+				"from": "auxiliaryPanel",
+				"to": "aiSuggestions",
+				"reason": "Renamed for clarity \u2014 the auxiliary panel is specifically for AI suggestions. General-purpose floating panels can now be built with the Dropdown compound component."
+			},
+			{
+				"component": "Button",
+				"from": "isLoading",
+				"to": "isWorking",
+				"reason": "The v1 isLoading prop (which showed a spinner and disabled the button) has been renamed to isWorking. A new isLoading prop has been added with different behavior - it displays a pulsing skeleton loader for initial page/section loads, while isWorking shows a spinner for action completion."
+			},
+			{
+				"component": "Icon",
+				"from": "iconSize",
+				"to": "size",
+				"reason": "The iconSize prop has been renamed to size for consistency across V2 icon components. The available size values and defaults remain unchanged."
+			},
+			{
+				"component": "CloseButton",
+				"from": "iconSize",
+				"to": "size",
+				"reason": "The iconSize prop has been renamed to size for consistency with other button components. The available size values remain the same ('m', 'l', 'xl')."
+			},
+			{
+				"component": "PlatformIcon",
+				"from": "iconSize",
+				"to": "size",
+				"reason": "The iconSize prop has been renamed to size for consistency with V2 component conventions. Size values have also changed to align with the Icon component scale \u2014 'xs', 's', 'm', 'l', 'xl', '2xl', '3xl' \u2014 replacing the previous 1.2\u00d7 ratio scale. The pixel sizes for 'l', 'xl', and '2xl' are different: l is now 1.25rem (was 1.2rem), xl is 1.5rem (was 1.44rem), 2xl is 2rem (was 1.728rem)."
+			},
+			{
+				"component": "FileDiff",
+				"from": "labelStrings",
+				"to": "translationStrings",
+				"reason": "Renamed for consistency with other V2 components."
+			},
+			{
+				"component": "DocsLayout",
+				"from": "sidebarMinWidth",
+				"to": "sidebarWidthMin",
+				"reason": "Renamed for consistency with the sidebarWidth/sidebarWidthMax/sidebarWidthMin naming convention used across layout components."
+			},
+			{
+				"component": "CardSelect",
+				"from": "options[].description",
+				"to": "options[].children",
+				"description": "Each option now accepts children (ReactNode) instead of description (string | ReactNode), enabling richer composition inside card options."
+			}
+		],
+		"additions": [
+			{
+				"component": "Card",
+				"prop": "imageVariant",
+				"description": "New imageVariant prop controls how the image slot is presented. bleed (default) extends the image to the card edges; inset adds padding around the image with all corners rounded. Note: the padding prop does not affect image padding.",
+				"usage": "Use imageVariant='inset' when the image should appear contained within the card rather than bleeding to the edges."
+			},
+			{
+				"component": "Card",
+				"prop": "footer slot",
+				"description": "New footer named slot renders a bottom-aligned content area below the main slot. The footer is pinned to the bottom of the card regardless of main content length, enabling CTA alignment across cards of varying heights in a grid.",
+				"usage": "Pass content with slot='footer' to place it in the footer area. Use for CTAs such as ButtonLink."
+			},
+			{
+				"component": "Button",
+				"prop": "isLoading",
+				"description": "New isLoading prop displays a pulsing skeleton loader effect (hides all button content) and is used during initial page or section loads. This is different from the v1 isLoading which showed a spinner - that functionality is now the isWorking prop.",
+				"usage": "Use isLoading for initial loads, use isWorking when performing an action like form submission."
+			},
+			{
+				"component": "IconButton",
+				"prop": "hasBorder",
+				"description": "New hasBorder prop controls border visibility. Defaults to false (no border). When true, shows a border using variant-specific border color tokens. Hover background is identical in both states.",
+				"usage": "Use hasBorder={true} when the button needs a visible border for emphasis or grouping. Omit (or set false) for a borderless icon button."
+			},
+			{
+				"component": "Select",
+				"prop": "size",
+				"description": "New size prop adds three height/padding/font-size variants. Defaults to 's' (32px). 'm' gives 40px and 'l' gives 48px, matching the TextInput size scale.",
+				"usage": "Use size='s' (default) for standard form controls, size='m' for more prominent inputs, size='l' for large/prominent form layouts."
+			},
+			{
+				"component": "Combobox",
+				"prop": "size",
+				"description": "New size prop adds three height/padding/font-size variants. Defaults to 's' (32px). 'm' gives 40px and 'l' gives 48px, matching the TextInput and Select size scale.",
+				"usage": "Use size='s' (default) for standard form controls, size='m' for more prominent inputs, size='l' for large/prominent form layouts."
+			},
+			{
+				"component": "Pagination",
+				"prop": "size",
+				"description": "New size prop adds two height/font-size variants. Defaults to 'm' (40px). 's' gives 20px items for compact layouts.",
+				"usage": "Use size='m' (default) for standard pagination, size='s' for compact or dense layouts."
+			},
+			{
+				"component": "Tabs",
+				"prop": "size",
+				"description": "New size prop adds two tab height variants. Defaults to 's' (32px). 'm' gives 40px tabs with larger text and icons.",
+				"usage": "Use size='s' (default) for standard tabs, size='m' for more prominent tab bars."
+			},
+			{
+				"component": "TabMenu",
+				"prop": "size",
+				"description": "New size prop adds two tab height variants. Defaults to 's' (32px). 'm' gives 40px tabs with larger text and icons.",
+				"usage": "Use size='s' (default) for standard navigation, size='m' for more prominent tab navigation."
+			},
+			{
+				"component": "ComboboxMultiselect",
+				"prop": "size",
+				"description": "New size prop adds three height/padding/font-size variants. Defaults to 's' (32px). 'm' gives 40px and 'l' gives 48px, matching the TextInput and Select size scale.",
+				"usage": "Use size='s' (default) for standard form controls, size='m' for more prominent inputs, size='l' for large/prominent form layouts."
+			},
+			{
+				"component": "ComparisonList",
+				"prop": "size",
+				"description": "New size prop adds two density variants affecting font size, row spacing, column gap, and icon size. Defaults to 's'.",
+				"usage": "Use size='s' (default) for compact lists, size='m' for a larger, more spacious layout."
+			},
+			{
+				"component": "PaymentIcon",
+				"prop": "size",
+				"description": "New size prop controls icon height using the standard icon scale: 'xs' (0.625rem), 's' (0.75rem), 'm' (1rem), 'l' (1.25rem), 'xl' (1.5rem), '2xl' (2rem, default), '3xl' (2.5rem). Width scales automatically to preserve aspect ratio. Previously the icon had a fixed width of 4rem with no size control.",
+				"usage": "Use size='2xl' (default) for standard usage. Adjust as needed to match surrounding content scale."
+			},
+			{
+				"component": "Tag",
+				"prop": "size",
+				"type": "'xs' | 's' | 'm'",
+				"default": "'s'",
+				"description": "Controls the size of the tag.",
+				"usage": "Use size='s' (default), size='xs' for compact, or size='m' for large."
+			},
+			{
+				"component": "FileUpload",
+				"prop": "size",
+				"description": "New size prop controls the height and padding of the file upload input. Accepts 's' | 'm'.",
+				"usage": "Use size='s' (default) for compact forms, size='m' for standard forms."
+			},
+			{
+				"component": "SidebarLayout",
+				"prop": "sidebarWidthMin",
+				"description": "New prop that sets the minimum width of the sidebar in rems. Ensures the sidebar remains usable on medium-sized screens. Default: 15.",
+				"usage": "Use to prevent the sidebar from becoming too narrow as the viewport shrinks."
+			},
+			{
+				"component": "SidebarLayout",
+				"prop": "sidebarWidthMax",
+				"description": "New prop that sets the maximum width of the sidebar in rems. Prevents the sidebar from growing too wide on large screens. Default: 25.",
+				"usage": "Use to cap the sidebar width on wide viewports when using a large percentage value."
+			},
+			{
+				"component": "DocsLayout",
+				"prop": "sidebarWidthMax",
+				"description": "New prop that sets the maximum width of the sidebar in rems. Prevents the sidebar from growing too wide on large screens. Default: 20.",
+				"usage": "Use to cap the sidebar width on wide viewports."
+			},
+			{
+				"component": "Table",
+				"prop": "columns",
+				"description": "Replaces `headers`. An array of column definition objects, each with a required `id` (stable string identifier), `header` (ReactNode), and optional `sortable` (boolean).",
+				"usage": "columns={[{ id: 'name', header: 'Site name', sortable: true }]}"
+			},
+			{
+				"component": "Table",
+				"prop": "isLoading",
+				"description": "When true, renders skeleton rows in place of data. Use while data is fetching.",
+				"usage": "Use isLoading={true} during data fetches. Pair with loadingRowCount to control how many skeleton rows appear."
+			},
+			{
+				"component": "Table",
+				"prop": "loadingRowCount",
+				"description": "Number of skeleton rows to render when isLoading is true. Defaults to 5.",
+				"usage": "Set to approximate the expected row count to reduce layout shift when data loads."
+			},
+			{
+				"component": "Table",
+				"prop": "emptyState",
+				"description": "Custom ReactNode rendered when rowData is empty and isLoading is false. Defaults to a CompactEmptyState with heading 'No results found.'",
+				"usage": "Pass a custom <CompactEmptyState> or any ReactNode for a tailored empty experience."
+			},
+			{
+				"component": "Table",
+				"prop": "itemsPerPage",
+				"description": "Enables pagination. In uncontrolled mode the Table slices rowData internally. In controlled mode (with onPageChange) the consumer passes the current page slice as rowData.",
+				"usage": "Set itemsPerPage={25} for uncontrolled paging. Pair with onPageChange, currentPage, and totalItemCount for controlled mode."
+			},
+			{
+				"component": "Table",
+				"prop": "currentPage",
+				"description": "Current 1-based page number for controlled pagination. Pair with onPageChange.",
+				"usage": "Required in controlled pagination mode alongside onPageChange and totalItemCount."
+			},
+			{
+				"component": "Table",
+				"prop": "totalItemCount",
+				"description": "Total number of items across all pages. Required in controlled pagination mode so the Pagination component can compute the page count.",
+				"usage": "Pass the total count from your API response, not the length of the current page slice."
+			},
+			{
+				"component": "Table",
+				"prop": "onPageChange",
+				"description": "Callback fired when the user navigates to a new page. Receives the new 1-based page number. Providing this prop activates controlled pagination mode.",
+				"usage": "onPageChange={(page) => fetchPage(page)}"
+			},
+			{
+				"component": "Table",
+				"prop": "onRowSelectionChange",
+				"description": "Enables the checkbox column. Fires with the full array of currently selected row IDs on every selection change.",
+				"usage": "onRowSelectionChange={(ids) => setSelectedRows(ids)}"
+			},
+			{
+				"component": "Table",
+				"prop": "selectedRows",
+				"description": "Controlled selected row IDs. When provided alongside onRowSelectionChange, enables controlled selection mode.",
+				"usage": "selectedRows={selectedRows}"
+			},
+			{
+				"component": "Table",
+				"prop": "getRowId",
+				"description": "Derives a stable string ID from a row object for selection tracking. Defaults to array index. Required when using pagination to preserve selection across page changes.",
+				"usage": "getRowId={(row) => String(row.id)}"
+			},
+			{
+				"component": "Table",
+				"prop": "selectAllLabel",
+				"description": "Visually hidden accessible label for the select-all header checkbox. Defaults to 'Select all rows'.",
+				"usage": "Override for translation."
+			},
+			{
+				"component": "Table",
+				"prop": "getSelectRowLabel",
+				"description": "Returns the visually hidden accessible label for each row's checkbox. Defaults to () => 'Select row'.",
+				"usage": "Override for translation."
+			},
+			{
+				"component": "TagsInput",
+				"prop": "size",
+				"description": "New size prop adds three height/padding/font-size variants for the tag pills and input wrapper. Defaults to 's' (compact, 12px chip font). 'm' gives more padding. 'l' gives 14px chip font and larger input text, matching the ComboboxMultiselect size scale.",
+				"usage": "Use size='s' (default) for standard form controls, size='m' for more prominent inputs, size='l' for large/prominent form layouts."
+			},
+			{
+				"component": "SideNav",
+				"prop": "hasMobileDropdown",
+				"description": "New hasMobileDropdown prop opts in to rendering a dropdown menu in place of the standard navigation at mobile viewports. Defaults to false \u2014 the standard navigation is shown at all breakpoints.",
+				"usage": "Use hasMobileDropdown={true} if your layout requires a dropdown menu at mobile. The mobile breakpoint is controlled by the mobileBreakpoint prop on GlobalWrapper."
+			}
+		],
+		"removals": [
+			{
+				"component": "SiteSearch",
+				"prop": "horizontalOffset",
+				"replacement": "Remove the prop. It was deprecated and had no effect.",
+				"reason": "Deprecated prop removed in v2. Absolute positioning was removed from the component in an earlier release, making this prop a no-op."
+			},
+			{
+				"component": "Card",
+				"prop": "background",
+				"removedValues": [
+					"mint-gradient",
+					"sundown-gradient",
+					"yellow-gradient"
+				],
+				"replacement": "No direct replacement. Remove the prop or use background='default'.",
+				"reason": "Gradient background options removed from Card in v2. Only 'default' and 'transparent' are supported."
+			},
+			{
+				"component": "Button",
+				"prop": "variant",
+				"oldValue": "brand-secondary",
+				"replacement": "Use variant=\"secondary\"",
+				"reason": "The brand-secondary variant has been removed in v2. Use the standard secondary variant instead."
+			},
+			{
+				"component": "Button",
+				"prop": "variant",
+				"oldValue": "navbar",
+				"replacement": "Use variant=\"subtle\"",
+				"reason": "The navbar variant has been removed in v2. It was visually identical to subtle \u2014 replace with subtle."
+			},
+			{
+				"component": "MenuButton",
+				"prop": "variant",
+				"oldValue": "navbar",
+				"replacement": "Use variant=\"subtle\"",
+				"reason": "The navbar variant has been removed in v2. Use subtle instead. The expanded-state transparency and icon-color behavior previously specific to the navbar variant now applies to all subtle MenuButton triggers automatically."
+			},
+			{
+				"component": "IconButton",
+				"prop": "variant",
+				"oldValue": "critical-hover",
+				"replacement": "Use variant=\"critical\"",
+				"reason": "The critical-hover variant has been removed in v2. Use the standard critical variant instead."
+			},
+			{
+				"component": "Avatar",
+				"prop": "size",
+				"oldValue": "xl",
+				"replacement": "Use size=\"l\"",
+				"reason": "The 'xl' size has been removed in v2. The largest available size is now 'l' (40px)."
+			},
+			{
+				"component": "Panel",
+				"prop": "hasStatusIndicator",
+				"replacement": "Remove this prop. Status indicators have been removed from Panel in v2.",
+				"reason": "Panel no longer supports status indicators. Use an alternate approach to communicate status to screen readers."
+			},
+			{
+				"component": "Panel",
+				"prop": "statusType",
+				"replacement": "Remove this prop. Status indicators have been removed from Panel in v2.",
+				"reason": "Panel no longer supports status indicators. Use an alternate approach to communicate status to screen readers."
+			},
+			{
+				"component": "Panel",
+				"prop": "typeLabels",
+				"replacement": "Remove this prop. Status indicators have been removed from Panel in v2.",
+				"reason": "Panel no longer supports status indicators. Use an alternate approach to communicate status to screen readers."
+			},
+			{
+				"component": "SideNavGlobal",
+				"prop": "hasLogo",
+				"replacement": "Remove this prop. Use the IdentityBlock component in the AppLayout identity slot instead.",
+				"reason": "Logo display is now handled by the IdentityBlock component, which is placed in the AppLayout identity slot."
+			},
+			{
+				"component": "SideNavGlobal",
+				"prop": "logoLinkContent",
+				"replacement": "Remove this prop. Use the IdentityBlock component in the AppLayout identity slot instead.",
+				"reason": "Logo display is now handled by the IdentityBlock component, which is placed in the AppLayout identity slot."
+			},
+			{
+				"component": "SideNavGlobal",
+				"prop": "mobileMenuSelectTextFallback",
+				"replacement": "Remove this prop. SideNavGlobal no longer switches to a dropdown menu on mobile.",
+				"reason": "The sidebar navigation now renders the same at all breakpoints. Mobile behavior is handled by AppLayout."
+			},
+			{
+				"component": "Switch",
+				"prop": "showStatusLabel",
+				"replacement": "Remove the prop. The on/off state is now communicated to screen readers via a visually-hidden element. Use onLabel/offLabel to customize the screen-reader text.",
+				"reason": "The visual status label (On/Off text next to the switch) has been removed in V2. State is still accessible to screen readers via a visually-hidden element controlled by onLabel and offLabel."
+			},
+			{
+				"component": "Switch",
+				"prop": "statusLabelPlacement",
+				"replacement": "Remove the prop. No replacement \u2014 the status label is no longer rendered visually.",
+				"reason": "The visual status label has been removed in V2, making its placement prop obsolete."
+			},
+			{
+				"component": "Switch",
+				"prop": "onLabel",
+				"replacement": "Remove the prop. Screen readers announce the on/off state natively via role=\"switch\".",
+				"reason": "onLabel was used for visual and screen-reader status text. The visual label has been removed in V2, and role=\"switch\" already communicates state to screen readers without a custom label."
+			},
+			{
+				"component": "Switch",
+				"prop": "offLabel",
+				"replacement": "Remove the prop. Screen readers announce the on/off state natively via role=\"switch\".",
+				"reason": "offLabel was used for visual and screen-reader status text. The visual label has been removed in V2, and role=\"switch\" already communicates state to screen readers without a custom label."
+			},
+			{
+				"component": "MenuButton",
+				"prop": "withinNavbar",
+				"reason": "Removed in V2. The dropdown no longer adjusts its border radius based on navbar context \u2014 it floats normally regardless of placement.",
+				"migration": "Remove the withinNavbar prop. No replacement needed."
+			},
+			{
+				"component": "UserMenu",
+				"prop": "withinNavbar",
+				"reason": "Removed in V2. Mobile accordion behavior is now driven by DOM context ([data-pds-mobile] .pds-navbar__mobile) rather than this prop.",
+				"migration": "Remove the withinNavbar prop. No replacement needed."
+			},
+			{
+				"component": "WorkspaceSelector",
+				"prop": "withinNavbar",
+				"reason": "Removed in V2. Mobile accordion behavior is now driven by DOM context ([data-pds-mobile] .pds-navbar__mobile) rather than this prop.",
+				"migration": "Remove the withinNavbar prop. No replacement needed."
+			},
+			{
+				"component": "NotificationsPopover",
+				"prop": "withinNavbar",
+				"reason": "Removed in V2. Mobile accordion behavior is now driven by DOM context ([data-pds-mobile] .pds-navbar__mobile) rather than this prop.",
+				"migration": "Remove the withinNavbar prop. No replacement needed."
+			},
+			{
+				"component": "SiteMenu",
+				"prop": "mobileMenuMaxWidth",
+				"reason": "Removed in V2. Mobile behavior is now driven by the data-pds-mobile attribute set by GlobalWrapper, so per-component breakpoint configuration is no longer supported.",
+				"migration": "Remove the mobileMenuMaxWidth prop. Configure the mobile breakpoint via the mobileMaxWidth prop on GlobalWrapper instead."
+			},
+			{
+				"component": "Table",
+				"prop": "headers",
+				"reason": "Replaced by `columns`. Each column now requires a stable `id` field used for sort keys and cell lookup. Rename each header object to include an `id`, rename `title` to `header`."
+			},
+			{
+				"component": "TreeNav",
+				"prop": "mobileMenuMaxWidth",
+				"reason": "Removed in V2. The mobile breakpoint is now controlled globally by the mobileBreakpoint prop on GlobalWrapper.",
+				"replacement": "Use the mobileBreakpoint prop on GlobalWrapper to configure the mobile breakpoint."
+			},
+			{
+				"component": "TreeNav",
+				"prop": "hasMobileMenu",
+				"reason": "Removed in V2. TreeNav renders at all breakpoints without switching to a dropdown menu.",
+				"replacement": "Remove this prop. TreeNav always renders the full tree navigation."
+			},
+			{
+				"component": "TreeNav",
+				"prop": "mobileMenuSelectTextFallback",
+				"reason": "Removed in V2 along with the mobile dropdown functionality.",
+				"replacement": "Remove this prop."
+			}
+		],
+		"deprecations": [],
+		"defaultValueChanges": [
+			{
+				"component": "GlobalWrapper",
+				"prop": "mobileMaxWidth",
+				"v1Default": "640",
+				"v2Default": "767",
+				"reason": "Default updated to 767 to align exactly with --pds-bp-s-only (max-width: 767px), so the JS-driven data-pds-mobile attribute and the CSS media query fire at the same threshold.",
+				"migration": "If your site was relying on the 640px default, pass mobileMaxWidth={640} explicitly to preserve v1 behavior. Note that the prop was also renamed from mobileMenuMaxWidth to mobileMaxWidth."
+			},
+			{
+				"component": "Spinner",
+				"prop": "size",
+				"v1Default": "'m'",
+				"v2Default": "'3xl'",
+				"reason": "Default size increased to '3xl' to better match design system specifications. The small 'm' spinner was too subtle in most UI contexts.",
+				"migration": "If you relied on the default spinner size being small, explicitly pass size='m' to maintain the v1 appearance."
+			},
+			{
+				"component": "MenuButton",
+				"prop": "size",
+				"v1Default": "'md'",
+				"v2Default": "'s'",
+				"reason": "Default size changed from 'md' to 's' to align with new standardized size naming. In v2, 's' is equivalent to v1's 'md' (medium size).",
+				"migration": "If you relied on the default MenuButton size, no changes needed as 's' in v2 visually matches 'md' in v1. If you explicitly passed size='md', update to size='s' or size='m' based on desired appearance."
+			},
+			{
+				"component": "SplitButton",
+				"prop": "size",
+				"v1Default": "'md'",
+				"v2Default": "'s'",
+				"reason": "Default size changed from 'md' to 's' to align with new standardized size naming. In v2, 's' is equivalent to v1's 'md' (medium size).",
+				"migration": "If you relied on the default SplitButton size, no changes needed as 's' in v2 visually matches 'md' in v1. If you explicitly passed size='md', update to size='s' or size='m' based on desired appearance."
+			},
+			{
+				"component": "IconButton",
+				"prop": "size",
+				"v1Default": "'md'",
+				"v2Default": "'s'",
+				"reason": "Default size changed from 'md' to 's' to align with new standardized size naming. In v2, 's' is equivalent to v1's 'sm' (small size).",
+				"migration": "If you relied on the default IconButton size, note that 's' in v2 is smaller than v1's 'md'. Explicitly pass size='m' to match the v1 'md' size. If you explicitly passed size='md', update to size='m'. If you passed size='sm', update to size='s'."
+			},
+			{
+				"component": "Tooltip",
+				"prop": "triggerIconSize",
+				"v1Default": "'sm'",
+				"v2Default": "'m'",
+				"reason": "Default trigger icon size changed from 'sm' to 'm' to align with new standardized size naming and provide better default visibility.",
+				"migration": "If you relied on the default trigger icon size being small, explicitly pass triggerIconSize='s' to maintain the v1 appearance."
+			},
+			{
+				"component": "ComparisonList",
+				"prop": "showBorder",
+				"v1Default": "true",
+				"v2Default": "false",
+				"reason": "Borders are now opt-in. The borderless style is the new default as it suits the most common use cases.",
+				"migration": "Add showBorder={true} to preserve the bordered appearance from V1."
+			}
+		],
+		"typeChanges": [
+			{
+				"component": "StepList",
+				"prop": "steps",
+				"description": "The steps item type has been renamed from FlowStep to StepListItem to match the component rename.",
+				"v1Type": "FlowStep[]",
+				"v2Type": "StepListItem[]",
+				"migration": {
+					"note": "Update any FlowStep type imports to StepListItem. The shape of the type is unchanged \u2014 { header: string | ReactNode, content?: string | ReactNode }."
+				},
+				"reason": "Renamed alongside the FlowSteps \u2192 StepList component rename for naming consistency."
+			},
+			{
+				"component": "CloseButton",
+				"prop": "onClick",
+				"description": "onClick callback now receives a MouseEvent parameter",
+				"v1Type": "() => void",
+				"v2Type": "(e: React.MouseEvent<HTMLButtonElement>) => void",
+				"migration": {
+					"note": "Backwards compatible \u2014 existing handlers that ignore the event parameter continue to work. Update handlers if you need access to the event."
+				},
+				"reason": "Updated to allow consumers to call e.stopPropagation() or access other event properties when needed."
+			},
+			{
+				"component": "Spinner",
+				"prop": "size",
+				"description": "Size naming convention updated to match Button and Icon components",
+				"v1Type": "'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"v2Type": "'s' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"migration": {
+					"sm": "s",
+					"md": "m",
+					"lg": "l"
+				},
+				"reason": "Standardized size naming across all components. The 'sm', 'md', and 'lg' values have been shortened to 's', 'm', and 'l' for consistency."
+			},
+			{
+				"component": "MenuButton",
+				"prop": "size",
+				"description": "Size naming convention updated and reduced to two sizes",
+				"v1Type": "Exclude<ButtonSize, 'lg'> (which was 'xs' | 'sm' | 'md')",
+				"v2Type": "'s' | 'm'",
+				"migration": {
+					"xs": "s (removed, use 's' instead)",
+					"sm": "s",
+					"md": "m"
+				},
+				"reason": "Standardized size naming to match Button component v2 conventions. MenuButton now only supports 's' and 'm' sizes. The 'xs' size has been removed."
+			},
+			{
+				"component": "SplitButton",
+				"prop": "size",
+				"description": "Size naming convention updated and reduced to two sizes",
+				"v1Type": "Exclude<ButtonSize, 'lg'> (which was 'xs' | 'sm' | 'md')",
+				"v2Type": "'s' | 'm'",
+				"migration": {
+					"xs": "s (removed, use 's' instead)",
+					"sm": "s",
+					"md": "m"
+				},
+				"reason": "Standardized size naming to match Button component v2 conventions. SplitButton now only supports 's' and 'm' sizes. The 'xs' size has been removed."
+			},
+			{
+				"component": "IconButton",
+				"prop": "size",
+				"description": "Size naming convention updated and reduced to two sizes",
+				"v1Type": "ButtonSize (which was 'xs' | 'sm' | 'md' | 'lg')",
+				"v2Type": "'s' | 'm'",
+				"migration": {
+					"xs": "s (removed, use 's' instead)",
+					"sm": "s",
+					"md": "m",
+					"lg": "m (removed, use 'm' instead)"
+				},
+				"reason": "Standardized size naming to match other button components. IconButton now only supports 's' and 'm' sizes. The 'xs' and 'lg' sizes have been removed."
+			},
+			{
+				"component": "CloseButton",
+				"prop": "size",
+				"description": "Prop renamed from iconSize to size, and size naming convention updated to match standardized naming",
+				"v1Type": "'md' | 'lg' | 'xl' (on iconSize prop)",
+				"v2Type": "'m' | 'l' | 'xl' (on size prop)",
+				"migration": {
+					"md": "m",
+					"lg": "l",
+					"xl": "xl (unchanged)"
+				},
+				"reason": "Prop renamed from iconSize to size for consistency with other button components. Size value naming also standardized - the 'md' and 'lg' values have been shortened to 'm' and 'l' for consistency."
+			},
+			{
+				"component": "Icon",
+				"prop": "iconName",
+				"description": "Several icon names have been removed. Their outlined variants are now the default style.",
+				"migration": {
+					"circlePlusOutline": "circlePlus",
+					"circleMinusOutline": "circleMinus",
+					"globeLine": "globe"
+				},
+				"reason": "The 'Outline' and 'Line' suffixed icon names have been removed. The base names (circlePlus, circleMinus, globe) now render the outlined/regular style by default."
+			},
+			{
+				"component": "Tooltip",
+				"prop": "triggerIconSize",
+				"description": "Size naming convention updated to match standardized naming",
+				"v1Type": "'sm' | 'md' | 'lg'",
+				"v2Type": "'s' | 'm' | 'l'",
+				"migration": {
+					"sm": "s",
+					"md": "m",
+					"lg": "l"
+				},
+				"reason": "Standardized size naming across all components. The 'sm', 'md', and 'lg' values have been shortened to 's', 'm', and 'l' for consistency."
+			},
+			{
+				"component": "Badge",
+				"prop": "color",
+				"description": "IndicatorBadge renamed to Badge with new color system based on design token naming. Colors now use named palettes instead of semantic/tier names.",
+				"v1Type": "'ai' | 'critical' | 'info' | 'success' | 'warning' | 'neutral' | 'brand' | 'silver' | 'gold' | 'platinum' | 'diamond' | 'default'",
+				"v2Type": "'aether' | 'aether-secondary' | 'amber' | 'amber-secondary' | 'apollo' | 'apollo-secondary' | 'critical' | 'critical-secondary' | 'discovery' | 'discovery-secondary' | 'gaia' | 'gaia-secondary' | 'hypnos' | 'hypnos-secondary' | 'indigo' | 'indigo-secondary' | 'info' | 'info-secondary' | 'iris' | 'iris-secondary' | 'lime' | 'lime-secondary' | 'mint' | 'mint-secondary' | 'orange' | 'orange-secondary' | 'rose' | 'rose-secondary' | 'sand' | 'sand-secondary' | 'silver' | 'silver-secondary' | 'sky' | 'sky-secondary' | 'slate' | 'slate-secondary' | 'stone' | 'stone-secondary' | 'success' | 'success-secondary' | 'teal' | 'teal-secondary' | 'warning' | 'warning-secondary' | 'feature'",
+				"migration": {
+					"ai": "discovery-secondary",
+					"neutral": "stone",
+					"brand": "discovery",
+					"silver": "silver",
+					"gold": "sand",
+					"platinum": "slate",
+					"diamond": "sky",
+					"default": "gaia",
+					"critical": "critical",
+					"info": "info",
+					"success": "success",
+					"warning": "warning"
+				},
+				"reason": "Color names updated to use the design token palette naming system. Semantic and tier-based names replaced with palette names. Many new colors added including secondary variants."
+			},
+			{
+				"component": "Badge",
+				"prop": "size",
+				"description": "Size naming convention updated and xs size added",
+				"v1Type": "'sm' | 'md'",
+				"v2Type": "'xs' | 's' | 'm'",
+				"migration": {
+					"sm": "s",
+					"md": "m"
+				},
+				"reason": "Standardized size naming to match other v2 components. New 'xs' size added for compact contexts."
+			},
+			{
+				"component": "StatusIndicator",
+				"prop": "size",
+				"description": "Size naming convention updated",
+				"v1Type": "'sm' | 'md'",
+				"v2Type": "'xs' | 's'",
+				"migration": {
+					"sm": "xs",
+					"md": "s"
+				},
+				"reason": "Standardized size naming to match other v2 components."
+			},
+			{
+				"component": "StatusIndicator",
+				"prop": "type",
+				"description": "Type values updated to align with design token naming",
+				"v1Type": "'critical' | 'info' | 'neutral' | 'new' | 'success' | 'warning' | 'working'",
+				"v2Type": "'critical' | 'disabled' | 'discovery' | 'info' | 'neutral' | 'success' | 'warning' | 'working'",
+				"migration": {
+					"new": "discovery"
+				},
+				"reason": "The 'new' type has been renamed to 'discovery' to match design token naming. A 'disabled' type has been added."
+			},
+			{
+				"component": "Avatar",
+				"prop": "size",
+				"description": "Size naming convention updated and reduced to four sizes",
+				"v1Type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
+				"v2Type": "'xs' | 's' | 'm' | 'l'",
+				"migration": {
+					"xs": "xs",
+					"sm": "s",
+					"md": "s",
+					"lg": "m",
+					"xl": "l"
+				},
+				"reason": "Standardized size naming and reduced to four sizes with updated pixel values (16, 24, 32, 40px)."
+			},
+			{
+				"component": "CTALink",
+				"prop": "size",
+				"description": "Size naming convention updated and default changed",
+				"v1Type": "'sm' | 'md'",
+				"v2Type": "'s' | 'm'",
+				"migration": {
+					"sm": "s",
+					"md": "m"
+				},
+				"reason": "Standardized size naming. Default changed from 'md' to 's'."
+			},
+			{
+				"component": "LinkNewWindow",
+				"prop": "fontSize",
+				"description": "Size naming convention updated",
+				"v1Type": "'sm' | 'md' | 'lg'",
+				"v2Type": "'s' | 'm' | 'l'",
+				"migration": {
+					"sm": "s",
+					"md": "m",
+					"lg": "l"
+				},
+				"reason": "Standardized size naming across all components."
+			},
+			{
+				"component": "PanelList",
+				"prop": "paddingSize",
+				"description": "Size naming convention updated, two smallest sizes removed, and token mapping corrected",
+				"v1Type": "'4xs' | '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg'",
+				"v2Type": "'2xs' | 'xs' | 's' | 'm' | 'l'",
+				"migration": {
+					"4xs": "2xs",
+					"3xs": "2xs",
+					"2xs": "2xs",
+					"xs": "xs",
+					"sm": "s",
+					"md": "m",
+					"lg": "l"
+				},
+				"reason": "Standardized size naming. The '4xs' and '3xs' sizes have been removed \u2014 use '2xs' instead. Default changed from 'md' to 'm'."
+			},
+			{
+				"component": "StatusChecker",
+				"prop": "state",
+				"description": "The RefreshCheckerState enum has been replaced with the StatusCheckerState string union type",
+				"v1Type": "`${RefreshCheckerState}` (enum: RefreshCheckerState.DEFAULT | RefreshCheckerState.WORKING | RefreshCheckerState.CHECKED)",
+				"v2Type": "StatusCheckerState ('default' | 'working' | 'checked')",
+				"migration": {
+					"RefreshCheckerState.DEFAULT": "'default'",
+					"RefreshCheckerState.WORKING": "'working'",
+					"RefreshCheckerState.CHECKED": "'checked'"
+				},
+				"reason": "Enum replaced with a string union type following v2 component conventions. The string values are unchanged, so consumers already passing string literals require no updates. Only those importing and using the RefreshCheckerState enum need to migrate."
+			},
+			{
+				"component": "Tag",
+				"prop": "tagColor",
+				"oldType": "'color-1' | 'color-2' | ... | 'color-20'",
+				"newType": "'apollo' | 'iris' | 'hypnos' | 'gaia' | 'aether' | 'success' | 'warning' | 'critical' | 'info' | 'discovery' | 'amber' | 'orange' | 'lime' | 'teal' | 'sky' | 'indigo' | 'rose' | 'slate' | 'sand' | 'mint' | 'silver' | 'stone'",
+				"description": "Tag color values are now named instead of numbered. Two new colors added: silver and stone.",
+				"migration": "Replace numbered color values with their named equivalents: color-1\u2192apollo, color-2\u2192iris, color-3\u2192hypnos, color-4\u2192gaia, color-5\u2192aether, color-6\u2192success, color-7\u2192warning, color-8\u2192critical, color-9\u2192info, color-10\u2192discovery, color-11\u2192amber, color-12\u2192orange, color-13\u2192lime, color-14\u2192teal, color-15\u2192sky, color-16\u2192indigo, color-17\u2192rose, color-18\u2192slate, color-19\u2192sand, color-20\u2192mint. Two new values (silver, stone) have no v1 equivalent."
+			},
+			{
+				"component": "SidebarLayout",
+				"prop": "sidebarWidth",
+				"v1Type": "'narrow' | 'standard' | 'wide'",
+				"v2Type": "string",
+				"description": "sidebarWidth is now a percentage string instead of a preset option.",
+				"migration": "Replace preset values with percentage equivalents: 'narrow' \u2192 '25%', 'standard' \u2192 '33%', 'wide' \u2192 '42%'. Adjust as needed for your layout."
+			},
+			{
+				"component": "Table",
+				"prop": "rowData",
+				"oldType": "Array<Array<string | ReactNode>>",
+				"newType": "Array<Record<string, ReactNode>>",
+				"reason": "Row data is now keyed by column id rather than position, enabling stable column identity for sort, pagination, and loading states. Each row object key must match a column's `id` field."
+			},
+			{
+				"component": "Table",
+				"prop": "sortKey",
+				"oldType": "number",
+				"newType": "string",
+				"reason": "Sort key is now a column id string instead of a positional index. Update to pass the column's `id` value."
+			},
+			{
+				"component": "Table",
+				"prop": "defaultSortKey",
+				"oldType": "number",
+				"newType": "string",
+				"reason": "Default sort key is now a column id string instead of a positional index."
+			},
+			{
+				"component": "Table",
+				"prop": "onSort",
+				"oldType": "(key: number, order: SortOrder) => void",
+				"newType": "(key: string, order: SortOrder) => void",
+				"reason": "The sort callback now receives a column id string instead of a positional index."
+			},
+			{
+				"component": "CTALink",
+				"prop": "size",
+				"description": "Added xs size variant. The size prop now accepts xs | s | m (previously s | m).",
+				"v1Type": "'s' | 'm'",
+				"v2Type": "'xs' | 's' | 'm'",
+				"migration": {
+					"note": "Backwards compatible \u2014 existing size values are unchanged. Use size=\"xs\" when a smaller CTA link is needed."
+				},
+				"reason": "Added to support compact contexts such as the Payment Card pattern footer."
+			},
+			{
+				"component": "MenuButton",
+				"prop": "displayType",
+				"description": "Replaced with the boolean `iconOnly` prop. `displayType='icon-end'` (the default) becomes `iconOnly={false}` or simply omitting the prop. `displayType='icon-only'` becomes `iconOnly={true}`.",
+				"v1Type": "'icon-end' | 'icon-only'",
+				"v2Type": "boolean",
+				"migration": {
+					"note": "Remove `displayType='icon-end'` (no-op, it was the default). Replace `displayType='icon-only'` with `iconOnly`."
+				},
+				"reason": "The displayType prop offered only two modes and the name implied richer configurability than existed. A boolean is clearer."
+			},
+			{
+				"component": "Datepicker",
+				"prop": "presets",
+				"replacement": "Use the exported getPresetDateRange utility alongside an external SegmentedButton, Select, or other control. See the Datepicker With Presets pattern for composition examples.",
+				"reason": "Preset management has been decoupled from the Datepicker in v2 so consuming apps can use any control (SegmentedButton, Select, custom) and own their own preset state."
+			},
+			{
+				"component": "Datepicker",
+				"prop": "onInitialize",
+				"replacement": "Initialize date range state directly using getPresetDateRange in your component's useState initializer.",
+				"reason": "Removed along with the presets prop. Since preset state is now owned externally, the consuming component already knows the initial value and does not need a callback."
+			}
+		]
+	},
+	"imports": {
+		"pathChanges": [
+			{
+				"component": "Badge",
+				"from": "components/badges/IndicatorBadge/IndicatorBadge",
+				"to": "components/badges/Badge/Badge",
+				"reason": "IndicatorBadge renamed to Badge with new directory structure."
+			}
+		]
+	},
+	"cssClasses": {
+		"renames": [
+			{
+				"old": "pds-overline-text",
+				"new": "pds-overline-m",
+				"reason": "Overline text moved from foundations to typography style utilities with size-based naming. The default overline-text maps to overline-m."
+			},
+			{
+				"old": "pds-overline-text--sm",
+				"new": "pds-overline-s",
+				"reason": "Overline text size variants replaced with standalone size-based classes."
+			},
+			{
+				"old": "pds-overline-text--lg",
+				"new": "pds-overline-l",
+				"reason": "Overline text size variants replaced with standalone size-based classes."
+			}
+		],
+		"removals": [
+			{
+				"old": "pds-button--navbar",
+				"replacement": "pds-button--subtle",
+				"reason": "The navbar button variant has been removed in v2. Replace the pds-button--navbar class with pds-button--subtle anywhere it is applied directly in CSS or markup."
+			},
+			{
+				"old": "pds-color-bg-brand",
+				"replacement": "Use component-specific brand colors or custom styling",
+				"reason": "Generic brand color utilities removed in v2. The underlying token --pds-color-brand-primary-default no longer exists."
+			},
+			{
+				"old": "pds-color-fg-brand",
+				"replacement": "Use component-specific brand colors or custom styling",
+				"reason": "Generic brand color utilities removed in v2. The underlying token --pds-color-brand-primary-default no longer exists."
+			},
+			{
+				"old": "pds-ts-9xl",
+				"replacement": "Use pds-ts-8xl (new maximum size is 72px)",
+				"reason": "Typography scale updated to pragmatic hand-picked sizes. New scale includes 2XS through 8XL (10px-72px)."
+			},
+			{
+				"old": "pds-typography--product",
+				"replacement": "No class needed (product is now the default context). Use data-context=\"product\" attribute only when explicitly mixing product and marketing contexts.",
+				"reason": "Typography context system changed from CSS classes to data-context attribute. Product context is the default, so the class is no longer needed."
+			},
+			{
+				"old": "pds-lead-text",
+				"replacement": "Apply custom typography styles using design tokens (font-family: var(--pds-typography-ff-secondary), font-size: var(--pds-typography-size-2xl), line-height: var(--pds-typography-lh-m), color: var(--pds-color-fg-default-secondary))",
+				"reason": "Lead text foundation removed in v2. Use component-specific styling with design tokens instead of a global utility class."
+			},
+			{
+				"old": "pds-lead-text--sm",
+				"replacement": "Apply custom typography styles using design tokens with font-size: var(--pds-typography-size-xl)",
+				"reason": "Lead text foundation and all size variants removed in v2. Use component-specific styling with design tokens."
+			},
+			{
+				"old": "pds-quote-text",
+				"replacement": "Apply custom typography styles using design tokens (font-family: var(--pds-typography-ff-secondary), font-size: var(--pds-typography-size-2xl), font-style: italic, line-height: var(--pds-typography-lh-m))",
+				"reason": "Quote text foundation removed in v2. Use component-specific styling with design tokens instead of a global utility class."
+			},
+			{
+				"old": "pds-quote-text--sm",
+				"replacement": "Apply custom typography styles using design tokens with font-size: var(--pds-typography-size-xl)",
+				"reason": "Quote text foundation and all size variants removed in v2. Use component-specific styling with design tokens."
+			},
+			{
+				"old": "pds-quote-text--lg",
+				"replacement": "Apply custom typography styles using design tokens with font-size: var(--pds-typography-size-3xl)",
+				"reason": "Quote text foundation and all size variants removed in v2. Use component-specific styling with design tokens."
+			}
+		],
+		"additions": [
+			{
+				"new": "pds-ts-2xs",
+				"description": "New typography size utility for 10px text (smallest size in new scale)",
+				"usage": "Apply to elements needing metadata or tiny label text"
+			},
+			{
+				"new": "pds-color-border-info",
+				"description": "Border color utility for info status",
+				"usage": "Apply info status border color to elements"
+			},
+			{
+				"new": "pds-color-border-warning",
+				"description": "Border color utility for warning status",
+				"usage": "Apply warning status border color to elements"
+			},
+			{
+				"new": "pds-color-border-discovery",
+				"description": "Border color utility for discovery status",
+				"usage": "Apply discovery status border color to elements"
+			}
+		]
+	},
+	"utilities": {
+		"renames": [],
+		"removals": []
+	},
+	"behaviorChanges": [
+		{
+			"component": "TextInput, RadioGroup, FileUpload, Combobox, ComboboxMultiselect, Select, Textarea, Checkbox, Switch, TagsInput, Datepicker",
+			"prop": "inputWidth",
+			"description": "inputWidth now sets element width instead of max-width",
+			"v1Behavior": "inputWidth set maxWidth on the input wrapper. If the input's natural size was already below the value, the prop had no visible effect.",
+			"v2Behavior": "inputWidth sets width on the input wrapper, so the input is always exactly the specified size.",
+			"migration": "If you relied on inputWidth as a maximum constraint (allowing the input to be smaller than the value), review your usage. If the input should be allowed to shrink below the specified width at smaller viewports, wrap it in a container with overflow or max-width handling.",
+			"affectedAreas": ["All text-based input components", "Form layouts"]
+		},
+		{
+			"component": "Button",
+			"description": "Button loading states split into two distinct props with different behaviors",
+			"v1Behavior": "Single isLoading prop showed a spinner and disabled the button, used for all async operations.",
+			"v2Behavior": "Two separate props: isLoading (pulsing skeleton for initial loads) and isWorking (spinner for actions). Both disable the button but have different visual treatments.",
+			"migration": "Replace v1 isLoading with isWorking for action-based loading (form submissions, button actions). Use the new isLoading prop only for initial page/section load states where a skeleton loader is appropriate.",
+			"affectedAreas": ["Button component", "Loading states", "User experience"]
+		},
+		{
+			"component": "Build Configuration",
+			"description": "Build output directory renamed from `_dist` to `dist`",
+			"v1Behavior": "Package contents were output to `_dist/` directory",
+			"v2Behavior": "Package contents are now output to `dist/` directory",
+			"migration": "Update any direct references to the build output directory in your build scripts, tooling configuration, or documentation. Most users importing from the package should not be affected as the package.json exports are updated automatically.",
+			"affectedAreas": ["Build configuration", "CI/CD scripts", "Documentation"]
+		},
+		{
+			"component": "Headings (h1-h6)",
+			"description": "Typography scale system replaced with pragmatic sizing and contextual styling",
+			"v1Behavior": "Used `pds-typography--product` class with dual ratio-based scales. Product context used compact scale (14px base, 1.25 ratio) with h1 at ~40px.",
+			"v2Behavior": "Uses single pragmatic hand-picked scale with `data-context=\"product\"` (default) or `data-context=\"marketing\"` attributes. Product context: h1=28px (standard) or 36px (hero/empty states). Marketing context: h1=48px (standard).",
+			"migration": "Remove `pds-typography--product` class (no longer needed, product is default). For marketing content, add `data-context=\"marketing\"` to parent element instead. Review all heading usage as sizes have changed significantly. See heading documentation for complete size reference table.",
+			"affectedAreas": [
+				"Headings",
+				"Typography",
+				"Marketing pages",
+				"Product UIs"
+			]
+		},
+		{
+			"component": "Typography Line Heights",
+			"description": "Line height token values updated for better readability",
+			"v1Behavior": "Line heights: S=120%, M=140%",
+			"v2Behavior": "Line heights: XS=120% (new, for tight headings), S=130% (updated, for medium headings), M=150% (updated, meets WCAG AA for body text)",
+			"migration": "Visual review recommended. Body text will have slightly more generous line-height (1.5 instead of 1.4). Headings using lh-s will be slightly more open (1.3 instead of 1.2). h1 and h2 now use lh-xs (1.2) for tighter spacing.",
+			"affectedAreas": ["Typography", "Headings", "Body text", "Readability"]
+		},
+		{
+			"component": "Panel",
+			"description": "Panel simplified \u2014 status indicators removed",
+			"v1Behavior": "Panel supported hasStatusIndicator, statusType, and typeLabels props which rendered a colored bar on the left side of the panel.",
+			"v2Behavior": "Panel is now a general-purpose container with five variants: default, sunken, raised, overlay, and critical. Status indicators have been removed.",
+			"migration": "Remove hasStatusIndicator, statusType, and typeLabels props. Remove any custom CSS targeting .pds-panel__status elements.",
+			"affectedAreas": ["Panel component", "Visual design", "Status indicators"]
+		},
+		{
+			"component": "IconButton",
+			"description": "IconButton now supports an optional visible border via the hasBorder prop. In V1 the button was always borderless.",
+			"v1Behavior": "IconButton always had a 1px border and used --pds-border-radius-button (fully rounded/pill shape).",
+			"v2Behavior": "IconButton now uses --pds-border-radius-input (4px rounded rectangle) and has no visible border by default. Border is opt-in via hasBorder prop.",
+			"migration": "No code changes required. Add hasBorder={true} if you want a visible border on the button.",
+			"affectedAreas": [
+				"IconButton component",
+				"Visual design",
+				"Border radius"
+			]
+		},
+		{
+			"component": "Pagination",
+			"description": "Previous and next arrow buttons now hidden when at boundaries instead of disabled",
+			"v1Behavior": "Previous button rendered with aria-disabled and reduced opacity when on the first page. Next button rendered with aria-disabled and reduced opacity when on the last page.",
+			"v2Behavior": "Previous button is not rendered when on the first page. Next button is not rendered when on the last page.",
+			"migration": "No prop changes required. Remove any custom CSS targeting .pds-pagination__item--disabled \u2014 that class no longer exists.",
+			"affectedAreas": [
+				"Pagination component",
+				"Visual design",
+				"Accessibility"
+			]
+		},
+		{
+			"component": "TabMenu",
+			"description": "Dropdown positioning may shift slightly from V1. Custom CSS targeting fixed position values or the closed menu element should be reviewed.",
+			"v1Behavior": "TabMenuDropdown used a bespoke Floating UI implementation with hardcoded CSS positioning (position: absolute, fixed top/left values).",
+			"v2Behavior": "TabMenuDropdown now uses the shared useDropdown hook (same as Select, Combobox, etc.) with Floating UI floatingStyles for positioning.",
+			"migration": "No prop changes required. If you have custom CSS targeting .pds-tab-menu__dropdown when closed, note that it is no longer in the DOM when closed.",
+			"affectedAreas": [
+				"TabMenu component",
+				"Dropdown positioning",
+				"Consistency"
+			]
+		},
+		{
+			"component": "MenuButton",
+			"description": "Dropdown positioning may shift slightly from V1. The menu is no longer in the DOM when closed.",
+			"v1Behavior": "MenuButton used manual keyboard handling, aria-activedescendant focus management, and a custom click-outside handler. The menu element was always present in the DOM with visibility toggled via inline styles.",
+			"v2Behavior": "MenuButton now uses the shared useDropdown hook with roving tabIndex focus management (useListNavigation), built-in typeahead (useTypeahead), and automatic dismiss handling (useDismiss). The menu unmounts from the DOM when closed.",
+			"migration": "No prop changes required. If you relied on aria-activedescendant for screen readers, test with the updated component \u2014 it now uses a roving tabIndex pattern.",
+			"affectedAreas": [
+				"MenuButton component",
+				"Keyboard navigation",
+				"Accessibility",
+				"Focus management"
+			]
+		},
+		{
+			"component": "Tag",
+			"description": "Auto-assigned tag colors will change for all tags not using an explicit tagColor prop",
+			"v1Behavior": "When tagColor is omitted, a color is chosen by hashing the label text modulo 20 (the number of available colors).",
+			"v2Behavior": "When tagColor is omitted, a color is still chosen by hashing the label text, but modulo 22 (the new color count). Because both the array length and contents changed, the same label will map to a different color than it did in V1.",
+			"migration": "If consistent color identity matters for specific tags (e.g. users associate a color with a category), set tagColor explicitly on those tags rather than relying on auto-assignment.",
+			"affectedAreas": [
+				"Tag component",
+				"Auto-color assignment",
+				"Visual consistency"
+			]
+		},
+		{
+			"component": "InputGroup",
+			"description": "Buttons inside InputGroup now have consistent rounded corners on the right side, matching the input border radius regardless of button variant.",
+			"migration": "No code changes needed."
+		},
+		{
+			"component": "Skeleton",
+			"description": "Skeleton now fully supports dark mode. Colors switch automatically based on the active theme.",
+			"migration": "No code changes needed."
+		},
+		{
+			"component": "Popover",
+			"description": "Popover container now has a more defined border in both light and dark mode.",
+			"migration": "No code changes needed."
+		},
+		{
+			"component": "BranchDiff",
+			"description": "Minor visual refinements: small gap added between commit numbers and bars, and corrected bar colors in both light and dark mode.",
+			"migration": "No code changes needed."
+		},
+		{
+			"component": "FileDiff",
+			"description": "Bar colors corrected in both light and dark mode. Minor visual refinements to spacing and border radius.",
+			"migration": "BREAKING: Rename labelStrings prop to translationStrings."
+		},
+		{
+			"component": "Foundational Table Styles",
+			"description": "Bare table elements no longer receive foundational styles automatically",
+			"v1Behavior": "Foundational table styles applied to any <table> element without a class (table:not([class])) as well as table.pds-table. This caused breakage in frameworks that inject classes onto table elements.",
+			"v2Behavior": "Foundational table styles only apply to table.pds-table (explicit opt-in) and .pds-prose table (for prose/markdown content contexts). Bare tables without a class receive no foundational styles.",
+			"migration": "Add the pds-table class to any standalone <table> elements that should receive PDS foundational styles. For tables inside long-form or markdown content, wrap the content in a pds-prose container instead.",
+			"affectedAreas": [
+				"Foundational table styles",
+				"Prose content",
+				"Markdown rendering"
+			]
+		},
+		{
+			"component": "CompactEmptyState",
+			"description": "V2 style update \u2014 typography tokens and color token correction",
+			"v1Behavior": "Heading font size and weight applied via pds-ts-l and pds-fw-bold utility classes on the element. Message color used the deprecated pds-color-text-default-secondary token.",
+			"v2Behavior": "Heading font size and weight defined in component CSS using pds-typography-size-l and pds-typography-fw-bold tokens. Message color uses the correct pds-color-fg-default-secondary token.",
+			"migration": "No prop changes. Visual appearance is the same. Remove any overrides targeting pds-color-text-default-secondary on this component.",
+			"affectedAreas": [
+				"CompactEmptyState component",
+				"Typography",
+				"Color tokens"
+			]
+		},
+		{
+			"component": "VerticalEmptyState",
+			"description": "V2 style update \u2014 typography tokens and color token correction",
+			"v1Behavior": "Heading font size and weight applied via pds-ts-2xl and pds-fw-bold utility classes on the element. Root color used the deprecated pds-color-text-default token.",
+			"v2Behavior": "Heading font size and weight defined in component CSS using pds-typography-size-2xl and pds-typography-fw-bold tokens. Root color uses the correct pds-color-fg-default token.",
+			"migration": "No prop changes. Visual appearance is the same. Remove any overrides targeting pds-color-text-default on this component.",
+			"affectedAreas": [
+				"VerticalEmptyState component",
+				"Typography",
+				"Color tokens"
+			]
+		},
+		{
+			"component": "TreeNav",
+			"description": "The path property on TreeNavItem (formerly SideNavCompactItem) is now required on any item that has children (a links array). In V1, the path property existed but nested submenu expanded state did not survive re-renders regardless. In V2 this bug is fixed, and path is used to restore expanded state after re-renders. Omitting path from an expandable item will cause user-opened submenus to collapse on any re-render.",
+			"action": "Ensure all items with a links array have a unique path set, typically the route or URL path of that section (e.g. /guides/overview)."
+		}
+	],
+	"categories": [
+		{
+			"id": "components",
+			"name": "Components",
+			"description": "Component renames, removals, and deprecations"
+		},
+		{
+			"id": "props",
+			"name": "Props",
+			"description": "Component prop changes"
+		},
+		{
+			"id": "imports",
+			"name": "Import Paths",
+			"description": "Import path changes"
+		},
+		{
+			"id": "css-classes",
+			"name": "CSS Classes",
+			"description": "CSS class name changes"
+		},
+		{
+			"id": "utilities",
+			"name": "Utilities",
+			"description": "Utility function changes"
+		},
+		{
+			"id": "design-tokens",
+			"name": "Design Tokens",
+			"description": "Design token usage changes"
+		},
+		{
+			"id": "behavior",
+			"name": "Behavior Changes",
+			"description": "Breaking changes in component behavior"
+		}
+	],
+	"notes": {
+		"testing": "All components should be tested after migration to ensure expected behavior.",
+		"peerDependencies": "Ensure React version is compatible (16-19 supported).",
+		"designTokens": "This toolkit's major version must match @pantheon-systems/pds-design-tokens major version."
+	}
+}