@pantheon-systems/pds-toolkit-react 2.0.0-alpha.7 → 2.0.0-alpha.70

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

@@ -0,0 +1,1787 @@
+{
+	"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 — 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."
+			},
+			{
+				"component": "Navbar",
+				"prop": "hideLogo",
+				"reason": "Removed in V2. The logo is now passed via the logo slot. Omit the slot to show no logo.",
+				"replacement": "Remove this prop. To hide the logo, simply omit the logo slot."
+			},
+			{
+				"component": "Navbar",
+				"prop": "logoDisplayType",
+				"reason": "Removed in V2. Logo display type is now controlled by the PantheonLogo component's displayType prop, passed directly into the logo slot.",
+				"replacement": "Pass <PantheonLogo displayType='...' slot='logo' /> into the Navbar children."
+			},
+			{
+				"component": "Navbar",
+				"prop": "logoLinkContent",
+				"reason": "Removed in V2. Logo link is now passed via the PantheonLogo component in the logo slot.",
+				"replacement": "Pass <PantheonLogo linkContent={<a href='...'>...</a>} slot='logo' /> into the Navbar children."
+			},
+			{
+				"component": "Navbar",
+				"prop": "logoSrc",
+				"reason": "Removed in V2. Custom logo images should be placed directly in the logo slot.",
+				"replacement": "Place your logo image element directly in the logo slot: <img src='...' slot='logo' />."
+			},
+			{
+				"component": "Navbar",
+				"prop": "logoSubBrand",
+				"reason": "Removed in V2 along with sub-brand logo support.",
+				"replacement": "Remove this prop. Sub-brand display is no longer supported in Navbar."
+			},
+			{
+				"component": "PantheonLogo",
+				"prop": "subBrand",
+				"reason": "Removed in V2. Sub-brand display has been removed from the PantheonLogo component.",
+				"replacement": "Remove this prop. Compose your own sub-brand treatment using a separator and text element alongside PantheonLogo."
+			},
+			{
+				"component": "PantheonLogo",
+				"prop": "displayType",
+				"reason": "The sub-brand and sub-brand-small values have been removed in V2.",
+				"replacement": "Use 'full', 'icon', or 'wordmark' instead. Remove any usage of displayType='sub-brand' or displayType='sub-brand-small'."
+			},
+			{
+				"component": "WorkspaceSelector",
+				"prop": "planTier (on WorkspaceSelectorItem)",
+				"reason": "Removed in V2. Plan tier badges are no longer displayed in the workspace selector trigger button.",
+				"replacement": "Remove the planTier field from WorkspaceSelectorItem objects."
+			}
+		],
+		"additions": [
+			{
+				"component": "ThemeContextProvider",
+				"description": "New for V2. A context provider that owns the color-mode preference (light, dark, or system), applies the resolved theme to the data-theme attribute, and persists it to localStorage. Exposes the useTheme hook and a controlled mode for app-managed persistence. Enable via GlobalWrapper's enableThemeSwitching prop or render it directly.",
+				"usage": "Use to add light/dark/system theme switching to an app. Pair with the ThemeSwitcher component and consume state with useTheme."
+			},
+			{
+				"component": "PaginationChapter",
+				"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."
+			},
+			{
+				"component": "Navbar",
+				"prop": "logo slot",
+				"description": "New logo named slot renders the logo in both the desktop bar and the mobile top bar. Replaces the logoLinkContent, logoSrc, logoDisplayType, logoSubBrand, and hideLogo props.",
+				"usage": "Pass <PantheonLogo linkContent={<a href='...'>...</a>} slot='logo' /> as a child of Navbar."
+			},
+			{
+				"component": "Navbar",
+				"prop": "items-center slot",
+				"description": "New items-center named slot renders content in the center of the desktop navbar, truly centered using CSS grid. On mobile, the slot content collapses into the slide-out panel alongside items-left and items-right.",
+				"usage": "Pass content with slot='items-center' to place it in the center of the navbar (e.g. a search input)."
+			},
+			{
+				"component": "PantheonLogo",
+				"prop": "size",
+				"description": "New size prop controls logo scale. The wordmark height is the sizing basis and maps to PDS typography size tokens: s = --pds-typography-size-s, m = --pds-typography-size-m, l = --pds-typography-size-l. The full and icon variants scale proportionally so the fist matches the wordmark height.",
+				"usage": "Use size='s' for compact contexts (e.g. navbar), size='m' for default, size='l' for hero or marketing use."
+			},
+			{
+				"component": "AppLayout",
+				"prop": "header slot",
+				"description": "New header named slot renders a full-width region (typically a Navbar) above the sidebar and main content. When present, AppLayout stacks the header on top and positions the sidebar directly below it, so consumers no longer need an external flex-column wrapper to combine a Navbar with AppLayout.",
+				"usage": "Pass a component such as <Navbar slot='header'>...</Navbar> as a child of AppLayout."
+			},
+			{
+				"component": "AppLayout",
+				"prop": "footer slot",
+				"description": "New footer named slot renders a region (typically a SiteFooter) below the main content and aligned with it, while the sidebar spans the full height alongside the main + footer column. Gives the footer its own landmark instead of nesting it inside the main element.",
+				"usage": "Pass a component such as <SiteFooter as='footer' slot='footer' /> as a child of AppLayout."
+			},
+			{
+				"component": "Navbar",
+				"prop": "inlinePadding",
+				"description": "New inlinePadding prop overrides the desktop bar's horizontal (inline) padding with any CSS length, applied symmetrically. Defaults to the Container's standard gutter, so existing navbars are unaffected.",
+				"usage": "Set inlinePadding (e.g. 'var(--pds-spacing-m)') to align the navbar content with an adjacent app shell, such as the AppLayout sidebar when the navbar is in a header slot."
+			}
+		],
+		"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>. The v1 secondaryMenuItems/secondaryMenuLabel props have no direct equivalent; instead, add the secondary group to the single menuItems array, preceded by a separator ({ isSeparator: true }) and a section heading ({ isHeading: true, label: '…' }). 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 — 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 — 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 default ('l') is unchanged, but the 'xs' (10px) value has been removed (see props.typeChanges) — use 's' instead."
+			},
+			{
+				"component": "CloseButton",
+				"from": "iconSize",
+				"to": "size",
+				"reason": "The iconSize prop has been renamed to size for consistency with other button components. Size values have also been standardized to 's', 'm', 'l' (see props.typeChanges)."
+			},
+			{
+				"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 — 'xs', 's', 'm', 'l', 'xl', '2xl', '3xl' — replacing the previous 1.2× 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": "Panel",
+				"prop": "variant",
+				"description": "variant added four semantic values — 'info', 'warning', 'success', and 'discovery' — alongside the existing 'critical', bringing Panel to nine variants total. Semantic variants tint the whole panel and are the v2 replacement for the removed hasStatusIndicator + statusType status bar.",
+				"usage": "Use a semantic variant (e.g. variant='warning') to give a panel a status appearance. When migrating a v1 status panel, map statusType to the same-named variant (neutral → default)."
+			},
+			{
+				"component": "ButtonLink",
+				"prop": "variant",
+				"description": "ButtonLink now supports the full Button variant set, including the new 'link' variant (a text-link appearance on a real anchor). Previously the 'inline' variant was excluded.",
+				"usage": "Use variant=\"link\" for an anchor styled as an inline text link — e.g. the account-tier links in a dashboard workspace header."
+			},
+			{
+				"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": "CardSelect",
+				"prop": "padding",
+				"description": "New padding prop controls each card's content padding: 'condensed' | 'standard' (default) | 'spacious', matching Card and ActionCard.",
+				"usage": "Use padding='condensed' for denser card grids such as the site selection cards."
+			},
+			{
+				"component": "Card",
+				"prop": "background",
+				"description": "background gained a 'secondary' option, alongside the existing 'default' and 'transparent'. It fills the card with the secondary surface token (--pds-color-surface-default-secondary).",
+				"usage": "Use background='secondary' to set a card apart from default-surface cards on the same page."
+			},
+			{
+				"component": "ActionCard",
+				"prop": "background",
+				"description": "background gained a 'secondary' option, alongside the existing 'default' and 'transparent'. It fills the card with the secondary surface token (--pds-color-surface-default-secondary).",
+				"usage": "Use background='secondary' to set a card apart from default-surface cards on the same page."
+			},
+			{
+				"component": "CardSelect",
+				"prop": "background",
+				"description": "New background prop ('default' | 'secondary' | 'transparent') sets each card's surface fill, matching Card and ActionCard.",
+				"usage": "Use background='secondary' or 'transparent' when the cards sit on a surface that needs contrast from the default card background."
+			},
+			{
+				"component": "CardSelect",
+				"prop": "showCardLabels",
+				"description": "New showCardLabels prop (boolean, default true) controls the per-card label text. When false, each card's label is visually hidden but stays in the DOM as the accessible name for its radio input (still required) — for cards that compose their own visible titles. labelDisplay now controls only the group legend.",
+				"usage": "Set showCardLabels={false} when each card provides its own visible title, as in the Site Selection Cards pattern."
+			},
+			{
+				"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": "SegmentedButton",
+				"prop": "size",
+				"description": "New size prop adds three self-contained height/font-size variants, independent of the button size scale: 's' (20px), 'm' (24px, default), and 'l' (32px). The icon scales with the size (s → 12px, m → 14px, l → 16px).",
+				"usage": "Use size='m' (default) for standard usage, size='s' for dense or space-constrained layouts, size='l' for a more prominent control."
+			},
+			{
+				"component": "SegmentedButton",
+				"prop": "border",
+				"description": "New boolean prop that draws a border around the track. Defaults to false — the track has no border.",
+				"usage": "Set border to add a visible border around the control."
+			},
+			{
+				"component": "SegmentedButton",
+				"prop": "iconOnly",
+				"description": "New boolean prop that renders each option as a square, icon-only segment with a circular selected pill. Defaults to false. Each option must include an iconName; its label is used as the visually hidden accessible name and shown in a tooltip on hover. Works at any size; the icon and pill scale with the size prop.",
+				"usage": "Set iconOnly for compact, icon-only controls (for example, a theme toggle)."
+			},
+			{
+				"component": "ButtonNav",
+				"prop": "border",
+				"description": "New boolean prop that draws a border around the track, matching the SegmentedButton component. Defaults to false — the track has no border.",
+				"usage": "Set border to add a visible border around the navigation track."
+			},
+			{
+				"component": "UserMenu",
+				"prop": "theme",
+				"description": "New prop for the currently active theme ('light' | 'dark' | 'system'). When provided together with onThemeChange, a theme switcher row (ThemeSwitcher 'toggle' variant) renders at the top of the menu.",
+				"usage": "Provide theme and onThemeChange to surface theme switching directly in the user menu."
+			},
+			{
+				"component": "UserMenu",
+				"prop": "onThemeChange",
+				"description": "New callback fired with the newly selected theme. Provide together with theme to render the theme switcher row. Optional themeLabel and themeLabelStrings props localize the row.",
+				"usage": "Use to update and persist your application's theme state when the user changes it from the menu."
+			},
+			{
+				"component": "StatusIndicator",
+				"prop": "linkContent",
+				"description": "New optional prop that makes the status indicator a link. Pass a fully-formed, router-agnostic link element (for example, an anchor or your router's link component); the indicator's dot and label render as its children, so the whole indicator becomes clickable.",
+				"usage": "Provide linkContent to link the status indicator, following the same router-agnostic link pattern used across the toolkit."
+			},
+			{
+				"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": "Table",
+				"prop": "isRowSelectable",
+				"description": "Predicate (row, rowId) => boolean that returns false to disable selection for specific rows. When omitted, all rows are selectable. Non-selectable rows render a disabled checkbox and are excluded from the select-all checkbox's state and toggle.",
+				"usage": "isRowSelectable={(row) => row.status !== 'locked'}"
+			},
+			{
+				"component": "Table",
+				"prop": "getRowSelectDisabledReason",
+				"description": "Returns the reason a row's selection checkbox is disabled. Only called for rows where isRowSelectable returns false. The reason is appended to the checkbox's accessible label (so screen readers announce why) and set as a native title tooltip. A disabled checkbox is not focusable, so a focus/hover-only tooltip would be missed — embedding the reason in the accessible name ensures it is conveyed.",
+				"usage": "getRowSelectDisabledReason={() => 'Locked sites cannot be selected'}"
+			},
+			{
+				"component": "Table",
+				"prop": "paginationLabels",
+				"description": "Translatable labels for the built-in pagination controls: the previous/next buttons, the page selector, and the page-count separator ('of'). Forwarded to the internal PaginationCompact. When omitted, English defaults are used.",
+				"usage": "paginationLabels={{ previous: 'Página anterior', next: 'Página siguiente', pageSelect: 'Ir a la página', of: 'de' }}"
+			},
+			{
+				"component": "Table",
+				"prop": "pageSizeSelectLabel",
+				"description": "Accessible label for the rows-per-page selector. Defaults to 'Rows per page'.",
+				"usage": "Override for translation, e.g. pageSizeSelectLabel='Filas por página'."
+			},
+			{
+				"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 — 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."
+			},
+			{
+				"component": "GlobalWrapper",
+				"prop": "enableThemeSwitching",
+				"description": "New opt-in prop that wraps children in a ThemeContextProvider, which owns the color-mode preference and applies the resolved theme to the data-theme attribute. Defaults to false. Configure the provider via the themeProps prop (defaultTheme, storageKey, controlled theme/onThemeChange, nodeRef).",
+				"usage": "Set enableThemeSwitching to add color-mode theme switching to an app, then consume the value with the useTheme hook (for example, to drive a ThemeSwitcher)."
+			},
+			{
+				"component": "HorizontalEmptyState",
+				"prop": "hasIndentedContent",
+				"description": "New opt-in prop that adds inline-start padding to the content block so its text aligns with the content of cards placed below it. Defaults to false. The image/video stays flush with the container edge either way.",
+				"usage": "Set hasIndentedContent={true} when this empty state sits directly above a row of cards (see the Horizontal Empty State pattern). Omit it when the component is used on its own."
+			},
+			{
+				"component": "Datepicker",
+				"prop": "allowCustomRange",
+				"description": "New opt-out prop that removes the 'Custom' entry (and the divider above it) from the built-in presets list, leaving only the fixed presets. Defaults to true, so existing preset lists are unchanged.",
+				"usage": "Set allowCustomRange={false} when the surface can only serve a known set of windows and an arbitrary range would be a dead end. On its own it only removes the entry; pair it with showPresetCalendar={false} for a popover that is nothing but the preset list."
+			},
+			{
+				"component": "Datepicker",
+				"prop": "allowDateRangeSelection",
+				"description": "New prop controlling whether range mode may select a span of days. Defaults to true (unchanged two-click behavior). Set to false to constrain the calendar to a single day per selection: one click picks that day as both the start and the end. The emitted value stays a DateRange, covering the whole day when showTime is set.",
+				"usage": "Set allowDateRangeSelection={false} on a mode='range' picker where a multi-day span is meaningless or unsupported. It composes with presets (whose entries still compute their own multi-day ranges) and has no effect in single mode."
+			}
+		],
+		"removals": [
+			{
+				"component": "MenuButton",
+				"prop": "menuPosition",
+				"replacement": "Remove the prop. The menu always opens start-aligned to the trigger. Remove any menuPosition='start' (redundant) or menuPosition='end' usage.",
+				"reason": "The menuPosition prop ('start' | 'end') has been removed in v2. The 'end' alignment never positioned correctly and was unused; the menu now always aligns to the start of the trigger. A right-aligned option may be reintroduced later if a need arises."
+			},
+			{
+				"component": "Spinner",
+				"prop": "colorType",
+				"replacement": "Replace with the `color` prop — pass any CSS color string or `var(--token)` reference. Use `'var(--pds-color-foreground-reverse)'` in place of `'monochromatic-reverse'`, and omit the prop entirely in place of `'monochromatic'` or `'full-color'` (the default is now foreground default).",
+				"reason": "The colorType prop ('full-color' | 'monochromatic' | 'monochromatic-reverse') has been removed in v2. The spinner now accepts a single `color` prop; the track ring renders at 30% opacity of the same color automatically. The default color is now the foreground default token."
+			},
+			{
+				"component": "CodeBlock",
+				"prop": "colorType",
+				"replacement": "Remove the prop. CodeBlock now renders in a single unified style.",
+				"reason": "The colorType prop ('dark' | 'light') has been removed in v2. CodeBlock now renders in one consistent style that works across both page themes."
+			},
+			{
+				"component": "SiteMenu",
+				"prop": "colorType",
+				"replacement": "No direct replacement — consult design for a different approach. The reverse color scheme is not being carried forward in v2; remove any colorType='reverse' usage (the default light-background rendering is unchanged).",
+				"reason": "The colorType prop ('default' | 'reverse') has been removed in v2. The reverse color scheme has been dropped and there is no replacement — reach out to design if you need a dark-background treatment."
+			},
+			{
+				"component": "Tabs",
+				"prop": "size",
+				"replacement": "Remove the prop. Tabs now render at a single size equivalent to the former size='m'.",
+				"reason": "The size prop has been removed in v2. The component now renders at one size only. Remove any size='s' or size='m' usage."
+			},
+			{
+				"component": "TabMenu",
+				"prop": "size",
+				"replacement": "Remove the prop. TabMenu now renders at a single size equivalent to the former size='m'.",
+				"reason": "The size prop has been removed in v2. The component now renders at one size only. Remove any size='s' or size='m' usage."
+			},
+			{
+				"component": "ButtonNav",
+				"prop": "size",
+				"replacement": "Remove the prop. ButtonNav now renders at a single size equivalent to the former size='s'.",
+				"reason": "The size prop and the medium size have been removed in v2. The component now renders at one size only. Remove any size='s' or size='m' usage. A smaller size may be reintroduced later if a need arises."
+			},
+			{
+				"component": "StatusIndicator",
+				"prop": "size",
+				"replacement": "Remove the prop. StatusIndicator now renders at a single size (equivalent to the former size='s' / v1 'md').",
+				"reason": "The size prop has been removed in v2. StatusIndicator renders at one size only; the small ('xs') size is no longer available. Remove any size prop usage."
+			},
+			{
+				"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', 'secondary', 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 — replace with subtle."
+			},
+			{
+				"component": "Button",
+				"prop": "variant",
+				"oldValue": "inline",
+				"replacement": "Use variant=\"link\"",
+				"reason": "The 'inline' button variant has been renamed to 'link' to describe its appearance (a text link) rather than its placement, and is no longer treated as legacy."
+			},
+			{
+				"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. Where you showed a status indicator, use the matching semantic variant instead (see statusType).",
+				"reason": "The standalone status-indicator bar was removed. To keep a status appearance, use the matching semantic `variant` (e.g. variant='warning'), which tints the whole panel — see the `statusType` mapping."
+			},
+			{
+				"component": "Panel",
+				"prop": "statusType",
+				"replacement": "Replace with the equivalent semantic variant: critical→variant='critical', warning→variant='warning', success→variant='success', info→variant='info', neutral→variant='default'.",
+				"reason": "Status is now expressed through `variant` rather than a separate status bar. Map the old value to the equivalent semantic variant: `critical`→`variant='critical'`, `warning`→`variant='warning'`, `success`→`variant='success'`, `info`→`variant='info'`, and `neutral`→`variant='default'` (there is no neutral variant)."
+			},
+			{
+				"component": "Panel",
+				"prop": "typeLabels",
+				"replacement": "Remove this prop. Status indicators have been removed from Panel in v2.",
+				"reason": "The status-indicator bar and its screen-reader labels no longer exist, so per-status labels are unnecessary. Semantic `variant` styling is decorative — convey status in the panel content where assistive tech needs it."
+			},
+			{
+				"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": "MenuButton",
+				"prop": "withinNavbar",
+				"reason": "Removed in V2. The dropdown no longer adjusts its border radius based on navbar context — 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": "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."
+			},
+			{
+				"component": "HorizontalEmptyState",
+				"prop": "isWithinPanel",
+				"reason": "Removed in V2 per design direction — HorizontalEmptyState is no longer scaled down for use inside a Panel.",
+				"replacement": "Remove this prop. If a special case still requires panel-scaled sizing, apply the styling manually via className rather than a component 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."
+			},
+			{
+				"component": "HorizontalEmptyState",
+				"prop": "maxWidth",
+				"v1Default": "'1200px'",
+				"v2Default": "'100%'",
+				"reason": "The component now fills its container by default rather than imposing its own width cap. It's always used inside the dashboard's AppLayout, which already constrains page content width — the old 1200px default was a leftover from the V1 standalone-page convention and fought the outer layout's own max-width.",
+				"migration": "If you relied on the 1200px cap (e.g. a true standalone full-page usage with no other width constraint), pass maxWidth='1200px' explicitly."
+			}
+		],
+		"typeChanges": [
+			{
+				"component": "Icon",
+				"prop": "size",
+				"description": "The 'xs' size value has been removed",
+				"v1Type": "'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl'",
+				"v2Type": "'s' | 'm' | 'l' | 'xl' | '2xl' | '3xl'",
+				"migration": {
+					"xs": "s (removed, use 's' instead)"
+				},
+				"reason": "The 10px 'xs' icon size has been removed in v2. It had a single internal usage (the TagsInput remove button, now 's'/12px) and is superseded by 's'. Use size='s' instead."
+			},
+			{
+				"component": "FlexContainer",
+				"prop": "gap",
+				"description": "The named gap scale was replaced by the numbered spacing scale (`GapScale`). Fixed at all breakpoints; use `mobileGap` to change the gap on small screens.",
+				"v1Type": "'minimal' | 'narrow' | 'standard' | 'wide' | 'none'",
+				"v2Type": "'none' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"migration": {
+					"minimal": "s",
+					"narrow": "m",
+					"standard": "xl",
+					"wide": "3xl"
+				},
+				"reason": "Unifies gap onto one predictable, fixed spacing scale across FlexContainer, Grid, and the layout components."
+			},
+			{
+				"component": "FlexContainer",
+				"prop": "mobileGap",
+				"description": "The named gap scale was replaced by the numbered spacing scale (`GapScale`).",
+				"v1Type": "'minimal' | 'narrow' | 'standard' | 'wide' | 'none'",
+				"v2Type": "'none' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"migration": {
+					"minimal": "s",
+					"narrow": "m",
+					"standard": "xl",
+					"wide": "3xl"
+				},
+				"reason": "Unifies gap onto one predictable, fixed spacing scale across FlexContainer, Grid, and the layout components."
+			},
+			{
+				"component": "SidebarLayout",
+				"prop": "gridGap",
+				"description": "The named gap scale was replaced by the numbered spacing scale (`GapScale`).",
+				"v1Type": "'narrow' | 'standard' | 'wide' | 'none'",
+				"v2Type": "'none' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"migration": {
+					"narrow": "m",
+					"standard": "xl",
+					"wide": "3xl"
+				},
+				"reason": "Unifies gap onto one predictable, fixed spacing scale across FlexContainer, Grid, and the layout components."
+			},
+			{
+				"component": "TwoItemLayout",
+				"prop": "gridGap",
+				"description": "The named gap scale was replaced by the numbered spacing scale (`GapScale`).",
+				"v1Type": "'narrow' | 'standard' | 'wide' | 'none'",
+				"v2Type": "'none' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"migration": {
+					"narrow": "m",
+					"standard": "xl",
+					"wide": "3xl"
+				},
+				"reason": "Unifies gap onto one predictable, fixed spacing scale across FlexContainer, Grid, and the layout components."
+			},
+			{
+				"component": "ThreeItemLayout",
+				"prop": "gridGap",
+				"description": "The named gap scale was replaced by the numbered spacing scale (`GapScale`).",
+				"v1Type": "'narrow' | 'standard' | 'wide' | 'none'",
+				"v2Type": "'none' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl'",
+				"migration": {
+					"narrow": "m",
+					"standard": "xl",
+					"wide": "3xl"
+				},
+				"reason": "Unifies gap onto one predictable, fixed spacing scale across FlexContainer, Grid, and the layout components."
+			},
+			{
+				"component": "Panel",
+				"prop": "padding",
+				"description": "The padding prop moved from the shared GridGapOptions scale to a dedicated, curated PaddingScale. Values were renamed: narrow → condensed, wide → spacious. standard and none are unchanged. The underlying spacing values are preserved.",
+				"v1Type": "'wide' | 'standard' | 'narrow' | 'none'",
+				"v2Type": "'none' | 'condensed' | 'standard' | 'spacious'",
+				"migration": {
+					"narrow": "condensed",
+					"wide": "spacious"
+				},
+				"reason": "Padding is a container-internal concern with its own curated semantic scale, separated from the numbered gap scale used for layout spacing."
+			},
+			{
+				"component": "Card",
+				"prop": "padding",
+				"description": "The padding prop moved from the shared GridGapOptions scale to a dedicated, curated PaddingScale. Values were renamed: narrow → condensed, wide → spacious. standard and none are unchanged. The underlying spacing values are preserved.",
+				"v1Type": "'wide' | 'standard' | 'narrow' | 'none'",
+				"v2Type": "'none' | 'condensed' | 'standard' | 'spacious'",
+				"migration": {
+					"narrow": "condensed",
+					"wide": "spacious"
+				},
+				"reason": "Padding is a container-internal concern with its own curated semantic scale, separated from the numbered gap scale used for layout spacing."
+			},
+			{
+				"component": "ActionCard",
+				"prop": "padding",
+				"description": "The padding prop moved from the shared GridGapOptions scale to a dedicated, curated PaddingScale. Values were renamed: narrow → condensed, wide → spacious. standard and none are unchanged. The underlying spacing values are preserved.",
+				"v1Type": "'wide' | 'standard' | 'narrow' | 'none'",
+				"v2Type": "'none' | 'condensed' | 'standard' | 'spacious'",
+				"migration": {
+					"narrow": "condensed",
+					"wide": "spacious"
+				},
+				"reason": "Padding is a container-internal concern with its own curated semantic scale, separated from the numbered gap scale used for layout spacing."
+			},
+			{
+				"component": "UtilityBar",
+				"prop": "padding",
+				"description": "The padding prop moved from the shared GridGapOptions scale to a dedicated, curated PaddingScale. Values were renamed: narrow → condensed, wide → spacious. standard and none are unchanged. The underlying spacing values are preserved.",
+				"v1Type": "'wide' | 'standard' | 'narrow' | 'none'",
+				"v2Type": "'none' | 'condensed' | 'standard' | 'spacious'",
+				"migration": {
+					"narrow": "condensed",
+					"wide": "spacious"
+				},
+				"reason": "Padding is a container-internal concern with its own curated semantic scale, separated from the numbered gap scale used for layout spacing."
+			},
+			{
+				"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 — { header: string | ReactNode, content?: string | ReactNode }."
+				},
+				"reason": "Renamed alongside the FlowSteps → 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 — 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": "Modal",
+				"prop": "size",
+				"description": "Size naming convention updated to match standardized naming",
+				"v1Type": "'sm' | 'md' | 'lg' | 'xl'",
+				"v2Type": "'s' | 'm' | 'l' | 'xl'",
+				"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. The 'xl' size is unchanged in both label and appearance."
+			},
+			{
+				"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 standardized to s/m/l",
+				"v1Type": "'md' | 'lg' | 'xl' (on iconSize prop)",
+				"v2Type": "'s' | 'm' | 'l' (on size prop)",
+				"migration": {
+					"md": "s",
+					"lg": "m",
+					"xl": "l"
+				},
+				"reason": "Prop renamed from iconSize to size for consistency with other button components. Size values standardized to the single-letter s/m/l scale used across V2 (smallest rung is now 's'); pixel sizes are unchanged, only the labels shifted (md→s, lg→m, xl→l)."
+			},
+			{
+				"component": "Icon",
+				"prop": "iconName",
+				"description": "Several icon names have been removed or shortened. Removed 'Outline'/'Line' suffixed names now render as the default style; other verbose names were shortened for clarity.",
+				"migration": {
+					"circlePlusOutline": "circlePlus",
+					"circleMinusOutline": "circleMinus",
+					"globeLine": "globe",
+					"arrowDownLeftAndArrowUpRightToCenter": "collapseToCenter",
+					"arrowsUpDownLeftRight": "move",
+					"linkSimple": "link",
+					"linkSimpleSlash": "unlink"
+				},
+				"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. Other verbose names were shortened for brevity and clarity: 'arrowDownLeftAndArrowUpRightToCenter' → 'collapseToCenter' (pairs with 'expandFromCenter'), 'arrowsUpDownLeftRight' → 'move', 'linkSimple' → 'link', 'linkSimpleSlash' → 'unlink'. Run the icon-name-updates codemod to migrate."
+			},
+			{
+				"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": "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 (sm → s, md → m), default changed from 'md' to 's', and an 'xs' variant added. v2 accepts 'xs' | 's' | 'm'.",
+				"v1Type": "'sm' | 'md'",
+				"v2Type": "'xs' | 's' | 'm'",
+				"migration": {
+					"sm": "s",
+					"md": "m"
+				},
+				"reason": "Standardized size naming and added 'xs' to support compact contexts such as the Payment Card pattern footer."
+			},
+			{
+				"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 — 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→apollo, color-2→iris, color-3→hypnos, color-4→gaia, color-5→aether, color-6→success, color-7→warning, color-8→critical, color-9→info, color-10→discovery, color-11→amber, color-12→orange, color-13→lime, color-14→teal, color-15→sky, color-16→indigo, color-17→rose, color-18→slate, color-19→sand, color-20→mint. 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' → '25%', 'standard' → '33%', 'wide' → '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": "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-grid--narrow",
+				"new": "pds-grid--gap-m",
+				"reason": "The grid gap moved to the numbered spacing scale. The old responsive `narrow` gutter maps to a fixed `m` (16px) gap."
+			},
+			{
+				"old": "pds-grid--wide",
+				"new": "pds-grid--gap-3xl",
+				"reason": "The grid gap moved to the numbered spacing scale. The old responsive `wide` gutter maps to a fixed `3xl` (40px) gap."
+			},
+			{
+				"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."
+			},
+			{
+				"old": "pds-color-bg-default",
+				"new": "pds-color-surface-default",
+				"reason": "Background utility classes renamed to the surface naming convention. Mirrors the CSS custom property rename of the same name."
+			},
+			{
+				"old": "pds-color-bg-default-secondary",
+				"new": "pds-color-surface-default-secondary",
+				"reason": "Background utility classes renamed to the surface naming convention. Mirrors the CSS custom property rename of the same name."
+			},
+			{
+				"old": "pds-color-bg-reverse",
+				"new": "pds-color-surface-reverse",
+				"reason": "Background utility classes renamed to the surface naming convention. Mirrors the CSS custom property rename of the same name."
+			},
+			{
+				"old": "pds-color-bg-transparent",
+				"new": "pds-color-surface-transparent",
+				"reason": "Background utility classes renamed to the surface naming convention."
+			},
+			{
+				"old": "pds-color-bg-info",
+				"new": "pds-color-surface-info",
+				"reason": "Status background utility classes renamed to the surface naming convention."
+			},
+			{
+				"old": "pds-color-bg-success",
+				"new": "pds-color-surface-success",
+				"reason": "Status background utility classes renamed to the surface naming convention."
+			},
+			{
+				"old": "pds-color-bg-warning",
+				"new": "pds-color-surface-warning",
+				"reason": "Status background utility classes renamed to the surface naming convention."
+			},
+			{
+				"old": "pds-color-bg-critical",
+				"new": "pds-color-surface-critical",
+				"reason": "Status background utility classes renamed to the surface naming convention."
+			},
+			{
+				"old": "pds-color-bg-discovery",
+				"new": "pds-color-surface-discovery",
+				"reason": "Status background utility classes renamed to the surface naming convention."
+			},
+			{
+				"old": "pds-color-fg-default",
+				"new": "pds-color-foreground-default",
+				"reason": "Foreground utility classes renamed to the foreground naming convention. Mirrors the CSS custom property rename of the same name."
+			},
+			{
+				"old": "pds-color-fg-default-secondary",
+				"new": "pds-color-foreground-default-secondary",
+				"reason": "Foreground utility classes renamed to the foreground naming convention. Mirrors the CSS custom property rename of the same name."
+			},
+			{
+				"old": "pds-color-fg-reverse",
+				"new": "pds-color-foreground-reverse",
+				"reason": "Foreground utility classes renamed to the foreground naming convention. Mirrors the CSS custom property rename of the same name."
+			},
+			{
+				"old": "pds-color-fg-info",
+				"new": "pds-color-foreground-info",
+				"reason": "Status foreground utility classes renamed to the foreground naming convention."
+			},
+			{
+				"old": "pds-color-fg-success",
+				"new": "pds-color-foreground-success",
+				"reason": "Status foreground utility classes renamed to the foreground naming convention."
+			},
+			{
+				"old": "pds-color-fg-warning",
+				"new": "pds-color-foreground-warning",
+				"reason": "Status foreground utility classes renamed to the foreground naming convention."
+			},
+			{
+				"old": "pds-color-fg-critical",
+				"new": "pds-color-foreground-critical",
+				"reason": "Status foreground utility classes renamed to the foreground naming convention."
+			},
+			{
+				"old": "pds-color-fg-discovery",
+				"new": "pds-color-foreground-discovery",
+				"reason": "Status foreground utility classes renamed to the foreground naming convention."
+			}
+		],
+		"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": [
+			{
+				"from": "useKeyPress",
+				"to": "useKeyboardShortcut"
+			}
+		],
+		"removals": []
+	},
+	"behaviorChanges": [
+		{
+			"component": "Container",
+			"prop": "full width",
+			"description": "The 'full' container width is now edge-to-edge with no inline padding.",
+			"v1Behavior": "containerWidth='full' (class pds-container--full) removed the max-width but kept the standard 2xl inline padding, so full-width sections still had a gutter.",
+			"v2Behavior": "The 'full' width now has no inline padding (padding-inline: 0), so content spans edge-to-edge. Add your own padding for full-width sections that need a gutter.",
+			"migration": "If you used containerWidth='full' (or the pds-container--full class) and relied on its inline padding, add the padding yourself (e.g. a spacing utility or wrapper).",
+			"affectedAreas": [
+				"Container",
+				"Any full-width sections using pds-container--full"
+			]
+		},
+		{
+			"component": "SiteFooter",
+			"prop": "containerWidth",
+			"description": "Default containerWidth changed from 'standard' to 'full'; the footer no longer applies its own inline padding or max-width by default.",
+			"v1Behavior": "SiteFooter wrapped its content in a standard Container, applying a max-width and inline padding (gutter) by default, plus 2xl vertical padding.",
+			"v2Behavior": "SiteFooter defaults to containerWidth='full', which is now edge-to-edge (no max-width, no inline padding); the containing layout or app provides the gutter. Vertical padding is reduced to xl.",
+			"migration": "If you relied on the footer's built-in gutter or max-width, set containerWidth explicitly (e.g. 'x-wide') or wrap the footer in your layout's container. When placing SiteFooter in AppLayout's footer slot, the region provides the inline padding.",
+			"affectedAreas": ["SiteFooter", "Footers in app and docs layouts"]
+		},
+		{
+			"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 status indicators removed; status is now expressed through semantic variants",
+			"v1Behavior": "Panel supported hasStatusIndicator, statusType, and typeLabels props which rendered a colored bar on the left side of the panel.",
+			"v2Behavior": "Panel now has nine variants: four structural (default, sunken, raised, overlay) and five semantic (critical, info, warning, success, discovery). The standalone status-indicator bar has been removed — the semantic variants tint the whole panel instead.",
+			"migration": "Remove the hasStatusIndicator, statusType, and typeLabels props, plus any custom CSS targeting .pds-panel__status elements. Where you previously showed a status indicator, use the matching semantic variant instead: statusType 'critical' → variant='critical', 'warning' → variant='warning', 'success' → variant='success', 'info' → variant='info', and 'neutral' → variant='default' (or omit variant, as there is no neutral variant).",
+			"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 — 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 — 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 — 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 — 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)."
+		},
+		{
+			"component": "Datepicker",
+			"prop": "showTime",
+			"description": "In range mode with showTime, the start and end time fields now render as soon as the calendar opens and default to 00:00 and 23:59, so a range committed without editing them spans whole days rather than midnight to midnight. Pressing Done with only one day clicked also now commits that day as a single-day range instead of discarding the selection. Single mode and pickers without showTime are unaffected.",
+			"action": "Review any range-mode consumer that read the end of an emitted range: a value that previously arrived as midnight on the last day now arrives as 23:59 unless the end time field was edited. If your query or display depends on an exclusive end bound, adjust it to expect the end of the day."
+		},
+		{
+			"component": "Datepicker",
+			"prop": "timeZone",
+			"description": "The trigger text, the calendar's own highlight, and screen-reader announcements now resolve the selected day in the configured timeZone rather than the browser's own zone. Previously a picker pinned to a different zone (e.g. timeZone=\"UTC\") displayed and highlighted the neighbouring calendar day to any viewer whose local zone was behind it - selecting a single day appeared to select two - even though the emitted value was correct.",
+			"action": "No action needed when timeZone is unset, which is the default and formats in the browser's zone exactly as before. If you worked around the old behaviour by shifting dates before display, remove that adjustment."
+		}
+	],
+	"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."
+	}
+}