feat: Replace icon-size() with tokens

[aaronccasanova]

WHY are these changes introduced?

Closes #4923

WHAT is this pull request doing?

This PR replaces the icon-size() SCSS function with a Polaris custom property:

• Added --p-icon-size-small and --p-icon-size-medium tokens
• Replaced existing --p-icon-size tokens with --p-icon-size-small
• Removed the icon-size() SCSS function
• Replaced icon-size() usage with the --p-icon-size-medium token

How to 🎩

🖥 Local development instructions
🗒 General tophatting guidelines
📄 Changelog guidelines

Copy-paste this code in playground/Playground.tsx:

import React from 'react';
import {PlusMinor} from '@shopify/polaris-icons';

import {Page, Button} from '../src';

export function Playground() {
  return (
    <Page title="Playground">
      <Button plain icon={PlusMinor} />
    </Page>
  );
}

Notice the plain icon button now uses the --p-icon-size-medium token:

🎩 checklist

• Tested on mobile
• Tested on multiple browsers
• Tested for accessibility
• Updated the component's README.md with documentation changes
• Tophatted documentation changes in the style guide
• For visual design changes, ping @ sarahill to update the Polaris UI kit

[github-actions]

size-limit report

Path	Size
cjs	158.26 KB (+0.01% 🔺)
esm	90.87 KB (+0.02% 🔺)
esnext	139.85 KB (+0.02% 🔺)
css	36.3 KB (+0.04% 🔺)

[aveline]

I would be inclined to move these out of legacy-tokens and into \tokens.

[alex-page]

This is tough. Long term I would prefer these to use values from the spacing tokens. However that would affect all the icons designs. I don't mind it staying in legacy as a follow up. It doesn't feel like a token we want to scale.

We also should move away from small medium and large as it makes adding or removing values awkward.

I would prefer icon-10 and icon-20 for now in legacy. Happy for other decisions though 🤷‍♂️

[aaronccasanova]

I would be inclined to move these out of legacy-tokens and into \tokens

I agree, but couldn't decide the appropriate/existing token group to add it to or if I should create a new one. Was hoping to iron that out here in the PR. Any name suggestions? I considered token-groups/sizes.json, but think that may be more appropriate for a token scale. Another option is token-groups/icons.json.

[alex-page]

I would leave it in legacy as it feels like something we want to adjust long term. Otherwise I would put it into a layout.json file for fixed element sizes.

[aaronccasanova]

We also should move away from small medium and large as it makes adding or removing values awkward.
I would prefer icon-10 and icon-20 for now in legacy. Happy for other decisions though 🤷‍♂️

I'm actually not opposed to small, medium, large, etc. sizes for icons, buttons, badges, etc.
That convention obviously doesn't work for token scales for the reason you've outlined (makes adding or removing values awkward), but makes perfect sense in the context of theming and limiting the variance on a page.

Design system references:

Primer

MUI

Spectrum

[alex-page]

It also adds a layer of abstraction. As a user I don't know if small is 8px 10px 12px 14px. I have to either read documentation or go into code.

[aaronccasanova]

Isn't that the same level of abstraction as using the spacing tokens? A user doesn't know 'spacing-10' = 40px without going into the code or reading the documentation and seeing we currently use multiples of 4px. I think being so literal with the token values ('icon-10' = 10px and 'icon-20' = 20px) is guaranteeing a future breaking change requiring updates for each usage. Also, I would expect designers to define the desired icon sizes in Figma files without requiring developers to know the underlying pixel value. I'm happy to change these tokens to get this PR shipped, but think we should continue this discussion with the team to better understand our token naming and application biases.

[alex-page]

This system should in the future have a consistent grid. Elements should snap to a 4px value. My concerns:

• Having values like 10px and 20px instantly breaks this rule
• We have to document and make sure users understand multiple tokens (spacing system, element widths)
• There should be one approach to sizes/spacing/layout
• sm md lg abstracts the values and makes it harder to understand without reading documentation or inspecting code

The reality is that the system doesn't do this. Now is the wrong time to do this work but it's important to make sure we aren't making this harder in the future. For this PR I would recommend shipping sm md and removing lg. This allows us to change the values and iterate towards a consolidated system for layout.