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

table

Change	Affected	Codemod
Long-hand size names removed	size prop on Button, ButtonGroup, ProgressBar, SegmentedControl, Select, TextField, Toggle	—
Short-hand token names removed	s token	—
*Primitive → Plain* rename	PopoverPrimitive, ModalPrimitive	—
Component removals	ToggleButton, LabelIcon	—
Button variant consolidation	variant prop on Button, ButtonGroup	button-variant-rename
Event handler standardization	onChange → onCheckedChange on OptionCard, Radio, Checkbox	—
Deprecated props removed	Button.isError, Snackbar.isError, Banner warning variant, Popover.ariaLabel, DataTable sorting APIs	—
Icon sizing + deprecations	All icon usage	—
Test helper get removed	PlumaTestHelpers	—

Codemods are a "—" today for most of these — see codemods/ for what ships alongside this repo. 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:

table

Current variant	After the major
primary	primary (unchanged)
secondary	removed
tertiary	secondary (now the default-looking, less-prominent button)
subtle	tertiary (now the most muted variant)

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)

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 ToggleButton: Migrate to alternative components
7. Replace LabelIcon with Coin: Migrate LabelIcon usage to the Coin component
8. 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
9. Update icons: Migrate to v2 sizing and check for deprecated icon usage
10. 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.

If you have any questions about these changes or need help with migration, feel free to reach out in the #pluma channel on Slack.