Components: Logistics for transitioning to new sizes

[mirka]

Now that we have a good direction for the new sizing scheme (#46734), we need to start thinking about the logistics to make that happen.

New transitional props

__next40pxDefaultSize

• Behavior: Will trigger the 40px default size automatically when size="default".
• Deprecation notice: After all internal usages have been migrated, add a deprecated() for any usages that don't have the __next40pxDefaultSize prop enabled.
• API removal: When the deprecation grace period is over. Once the API is removed, keep it in the TypeScript prop type definitions indefinitely, but mark as @deprecated and suppressed (with @ignore) from the docs.

What happens to the props we have now?

__next36pxDefaultSize

• Behavior: Will trigger the 40px default size automatically.
• Deprecation notice: None
• API removal: When the __next40pxDefaultSize API is removed. Once the API is removed, keep it in the TypeScript prop type definitions indefinitely, but mark as @deprecated and suppressed (with @ignore) from the docs.
• Code removal: Immediate

I think we can get away with this automatic 4px upsizing because the 4px difference is pretty minor. And judging from publicly available GitHub repos, adoption of the __next36pxDefaultSize prop is still low.

size="small"

• Behavior: Will continue to work.
• Deprecation notice: Add a deprecated() notice with no explicit deprecation version. (This is more of a recommendation for UI consistency, not code removal.)
• API removal: Not planned yet
• Code removal: Not planned yet, since maintenance cost is low

size="__unstable-large"

• Behavior: Will continue to work, although the recommended syntax will be <Component __next40pxDefaultSize /> (instead of <Component size="__unstable-large" />).
• Deprecation notice: Not planned yet, but maybe when the __next40pxDefaultSize API is removed, so devs can clean up the now unnecessary size prop.
• API removal: When the __next40pxDefaultSize API is removed. (Removing the __unstable-large API will not be disruptive because it will just fallback to the default size which will be 40px at that point.)
• Code removal: None

Remaining tasks

• Add repo-wide eslint rules to prevent usage without the __next40pxDefaultSize prop Components: Add eslint rules to prevent usage without __next40pxDefaultSize prop #63871
• Start logging deprecation warnings
• Clean up usage of $button-size SCSS variable and CONFIG.controlHeight CSS-in-JS variable

---

cc @ciampo

✍️ Dev note

UI components across the editor (input fields, buttons, etc) are currently rendering in a range of heights between 30px and 40px. In order to add consistency and visual polish to the editor's UI, we started working on standardizing components toward having a default height of 40px.

To ensure a smooth transition to the new default sizes, we have started to introduce a new, temporary __next40pxDefaultSize prop on selected components around the codebase, which will allow consumers to start opting into the new default size. Sometime after that, the temporary prop will be deprecated and ultimately removed, causing all instances of the components to switch to the default 40px size out of the box.

To start opting into the new 40px default height, set the __next40pxDefaultSize prop to true

[jasmussen]

Nice to see a focus on this, thank you! Just to clarify one piece, "small" was a term to describe the smaller size, but it doesn't necessarily need to be the prop name. Something like "compact" could also work. I've no opinion there, to be honest, and will trust you on choosing what works well there. And CC @mtias for awareness.