Breaking changes

This document outlines all planned breaking changes for the next major version of Pluma. These changes are designed to improve consistency, maintainability, and the overall developer experience.

Summary

Codemods are a "—" today for most of these — see the Pluma CLI codemods for what's available. Additional codemods for the remaining migrations are planned; as new ones land, this table will be updated.

Prop Name Changes

Remove Long Hand Size Names

Long hand size prop values will be removed in favor of shorter, more consistent alternatives:

• medium → md
• small → sm
• large → lg

Affected Components:

• Button - size prop
• ButtonGroup - size prop
• ProgressBar - size prop
• SegmentedControl - size prop
• Select - size prop
• TextField - size prop
• Toggle - size prop

Remove Short Hand Token Names

Short hand token names will be removed to improve clarity:

• s → sm

Component Changes

Rename *Primitive Components to Plain*

All components with the *Primitive suffix will be renamed to use the Plain* prefix for better clarity:

• PopoverPrimitive → PlainPopover
• ModalPrimitive → PlainModal

This affects all related subcomponents and utilities as well.

Component Removal

The following components will be removed entirely:

• ToggleButton - Remove without replacement
• LabelIcon - Remove in favor of Coin

Button Variant Consolidation

Button variants will be consolidated from four to three. The current secondary variant is removed; the remaining variants shift down a tier so the visual styles each variant produces stay continuous:

A codemod and two intermediate flags are available so consumer apps can complete this migration ahead of the major release without any visual regressions:

1. Preview the change. Set unsafe_withSoftDeprecatedSecondaryVariant on PlumaProvider's componentConfig.PlumaButton (or per-button). Every variant="secondary" button then renders with the current tertiary styles — the look the new secondary will have post-major.
2. Migrate source. Switch to the broader unsafe_withMigratedButtonVariants flag (also on PlumaProvider or per-button), then run the button-variant-rename codemod. The codemod renames tertiary → secondary and subtle → tertiary across .tsx/.jsx (jscodeshift) and .gts/.gjs/.hbs (Glimmer AST) files. With the flag on, the renamed source renders identically to before — no visual regressions.
3. Drop the flag once the major release ships. Your migrated source already uses the new names natively.

See the codemod README for the full migration order, running instructions, and limitations.

Event Handler Changes

Standardize Event Handler Names

Several components will migrate to more consistent event handler naming:

Change onChange to onCheckedChange:

• OptionCard.onChange → OptionCard.onCheckedChange
• Radio.onChange → Radio.onCheckedChange
• Checkbox.onChange → Checkbox.onCheckedChange

Deprecated Props Removal

Button Component

• Remove isError prop (use isDanger instead)

Snackbar Component

• Remove isError prop (use variant="error" instead)

Banner Component

• Remove warning variant (use caution instead)

Popover Component

• Remove ariaLabel prop (use description instead)

DataTable Component

• Remove deprecated { id, desc } object form for sorting
• Remove onSortingChange prop (use onChange in the sorting object instead)

Legacy Compatibility Styles

Remove Legacy Compatibility Styles

Early in the Pluma rollout, several components shipped an opt-in "legacy" style override so they could visually match their old Fly counterparts while apps migrated incrementally. These overrides will be removed in the next major version — components will only render in their current (default) Pluma styles.

unsafe_isLegacy prop removed from:

• Button
• DatePicker
• Link
• Select
• TextArea
• TextField
• ToggleButton

PlumaProvider componentFlags removed:

• unsafe_useLegacyButton
• unsafe_useLegacyTextField
• unsafe_useLegacyTextArea
• unsafe_useLegacySelect
• unsafe_useLegacyLink

Remove these props and flags from your app; the affected components already render in the target style by default.

Icon Changes

Icon Sizing

• Remove v1 icon sizing (migrate to v2 sizing)
• Deprecated icons will be removed without replacement
• Some icons will be renamed or merged with others

Specific Icon Changes

Various individual icons have been deprecated and will either be:

• Removed without replacement
• Renamed to new names
• Merged with existing icons

Test Helper Changes

Remove get function

When using PlumaTestHelpers, developers should not use the get function anymore. Instead they should use extract and find.

For more information, please visit the Test Helpers docs.

Migration Guide

To prepare for these changes:

1. Update size props: Replace medium, small, large with md, sm, lg
2. Update token names: Replace s with sm
3. Rename primitive components: Update imports and usage from *Primitive to Plain*
4. Update event handlers: Change onChange to onCheckedChange where applicable
5. Remove deprecated props: Replace with recommended alternatives
6. Remove legacy compatibility styles: Drop unsafe_isLegacy props and unsafe_useLegacy* PlumaProvider flags — components already render in the target style by default
7. Remove ToggleButton: Migrate to alternative components
8. Replace LabelIcon with Coin: Migrate LabelIcon usage to the Coin component
9. Migrate Button variants: Set unsafe_withMigratedButtonVariants on PlumaProvider, then run the button-variant-rename codemod to rename tertiary → secondary and subtle → tertiary in your source
10. Update icons: Migrate to v2 sizing and check for deprecated icon usage
11. Switch Test Helpers functions: Replace get with extract or find

We recommend updating these incrementally and testing thoroughly. The old APIs will continue to work until the next major version is released.