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
• Label - Remove in favor of Badge with the color prop. Every Label color is supported by Badge and renders identically; color="outline" becomes color="neutral-outline"

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)

Badge Component

• Remove isEmphasized prop (use color="accent" instead)
• Remove isOutline prop (use color="neutral-outline" instead, or color="accent-outline" where it was combined with isEmphasized)

Unsafe Section Components

• Remove TextField.unsafe_leftSectionComponent (use elementBefore instead)
• Remove TextField.unsafe_rightSectionComponent (use elementAfter instead)
• Remove Select.unsafe_leftSectionComponent (use elementBefore instead)

elementBefore and elementAfter take the same content and render in the same places, so the migration is a rename. In Ember they can additionally be filled with an :elementBefore / :elementAfter named block, which the unsafe_ props never supported.

NumberField and Combobox pass their own controls through unsafe_rightSectionComponent internally. That internal channel needs replacing with a private prop before the props can be removed — it is deliberately kept separate from the public elementAfter slot so a consumer's trailing content and the component's own controls can coexist.

Badge Default Element

Badge will render a <span> instead of a <div> by default. A badge is text-level UI, and a <span> is valid in phrasing contexts (paragraphs, headings, links, buttons) where a <div> is not — this also matches the element the removed Label component rendered, so Labels migrated into text flow become valid again automatically.

The change is visually inert (Badge forces display: inline-flex either way), but:

• Refs and element types change from HTMLDivElement to HTMLSpanElement (React ref types and the Ember Element signature) — TypeScript will surface every affected site.
• CSS or test selectors that assume a div need updating.
• Pass as="div" to retain the previous element where it matters.

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. Replace Label with Badge: Run the label-to-badge codemod to migrate Label usage to Badge with the color prop (color="outline" becomes color="neutral-outline") and replace Badge's isEmphasized/isOutline with their color equivalents; review anything the codemod flags
10. Update Badge element assumptions: Badge renders a span instead of a div — update HTMLDivElement ref types and any div-based selectors, or pass as="div" where the previous element is required
11. 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
12. Update icons: Migrate to v2 sizing and check for deprecated icon usage
13. 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.