Here are some pros/cons and trade-offs with WVUI's current icon system as I see them:

Pros:

• Using an inline <svg> tag allows arbitrary icon colors; allows icon colors to be controlled with CSS; and avoids the need to ship multiple, differently-colored versions of the same icon
• Automatic RTL flipping is useful, and applies to the vast majority of icons

Cons:

• Storing all SVG paths in one single file and requiring them to be single paths makes it harder to work on them (T260815).
• Needing to import icons in JS and pass them through to the template via data() is annoying

Trade-offs:

• Bundling icons with the code that uses them means that only icons that will be used are loaded (unlike with icon bundles, which wastefully load unused icons), but it also means that popular icons are duplicated in each module that uses them (unlike with icon bundles, which load each icon only once). Overall, I think this trade-off is probably worth it, but it requires either a build step. For non-build-step consumers, we'd need to split up the big bundle of icons, or add support for bundling individual icons in ResourceLoader.
• Loading an icon in WVUI always loads all versions of the icon (both directionalities, all languages). This is somewhat heavy for icons that have distinct LTR and RTL versions, and particularly heavy for letter-based icons that have many versions. However, this only affects a small number of icons: out of 209 icons, only 16 have multiple versions, and only two have more than 3 versions (bold has 16, italic has 12). Loading this extra information allows us to display icons in a language or directionality that's different from the interface language/directionality, but that's rarely needed.

Issues:

• Automatic RTL flipping uses a combination of the computed direction property and the [dir="rtl"] selector, which is inconsistent and leads to problems when LTR content is nested inside RTL content
• According to caniuse.com, some browsers (including IE 11 and Edge 12-16) don't support applying CSS transforms to SVG elements, so automatic RTL flipping wouldn't work in those browsers. We may be able to work around this by using the transform attribute instead.

I'd be curious to hear what other people's experiences are with these icon systems or others, what suggestions they have for what our icon system should look like, and what other factors they think we should consider in the architecture of our icon system.

Thanks Roan, I think you have covered most of the points. In general, I think it is important to make an early decision on whether consumers of wvui require a build system or not. The requirement of treeshaking(and hence the build step) or not is crucial to answer the design questions here.

Along with the design of the icon system, we need to think from the perspective of a potential developer using this system and optimize towards that. Whether this design saves time and make their development workflow easier and happier. Let me share some point from my experience of using @mdi/js with vuetify and using the above mentioned icon system in Section Translation.

1. The strong binding of available icons to javascript helps you to use quickly discover and pick an icon through autocompletion features of popular IDEs.
2. A build step or even real time checks by IDE make sure you are not refering an icon that does not exist. This is better than a loose dependency like CSS classnames

Needing to import icons in JS and pass them through to the template via data() is annoying

I would say this is positive. It is kind of "strong typing" for icons :-).

Storing all SVG paths in one single file and requiring them to be single paths makes it harder to work on them (T260815).

WVUI need to maintain the actual SVGs(full svg images) and then have some documented method to update the javascript file containing icon paths(not necessarily fully atuomated, considering the low frequency of changing icons). We can refer how this is done in popular icon system like material design icons.

An alternate to Javascript file with icon names holding paths is SASS SVG Icon approach outlined here. It has two variants: background-image: url(path to svg) and background-image: url(inline svg). Developers need to use CSS classnames with a defined pattern to get the icons then. This is not discoverable at the time of development compared to Javascript and prone to human errors undetected, leading to missing icons in UI. This approach also has some degree of treeshaking challenges depending on the usage of postcss and build system.

I'd be curious to hear what other people's experiences are with these icon systems or others, what suggestions they have for what our icon system should look like, and what other factors they think we should consider in the architecture of our icon system.G

TBH It's useful having the icons inside wvui and the approach with ResourceLoaderImageModule has not been perfect - it requires a lot of explaining (institutional knowledge) and leads to lots of modules in the repo (Minerva has about 8 of them). T244558 and T248912 remain open. Assuming we are going to get server side rendering, it feels like the right approach to move away from it and to allow icon rendering only inside Vue.js.

Trade-offs:

The duplication trade off is probably not a big deal - I think that is already happening. For example many of the same icons in Minerva desktop are also loaded inside VisualEditor.

Loading an icon in WVUI always loads all versions of the icon (both directionalities, all languages)

This actually sounds like a good thing. In future with an API driven frontend we'd be able to switch the UI in JavaScript from LTR to RTL. We're already shipping multiple icons for colors, so that trade off might counter-act this one.

Storing all SVG paths in one single file and requiring them to be single paths makes it harder to work on them (T260815).

I think a build step could take care of this con. It feels like it would be trivial to parse SVGs to grab the path and then generate an asset exporting those.

Icons are not separated into bundles like they are in OOUI, they're all in one big file.

I agree that this is a big challenge - some kind of build step definitely needed. I wonder if async components could be used in some way to handle this?

I would say this is positive. It is kind of "strong typing" for icons :-).

+ 1

In T282625#7081261, @santhosh wrote:

1. The strong binding of available icons to javascript helps you to use quickly discover and pick an icon through autocompletion features of popular IDEs.
2. A build step or even real time checks by IDE make sure you are not refering an icon that does not exist. This is better than a loose dependency like CSS classnames

Needing to import icons in JS and pass them through to the template via data() is annoying

I would say this is positive. It is kind of "strong typing" for icons :-).

This is a good point, and I had forgotten to say: the little extra annoyance is probably worth it for performance reasons (so that tree shaking works), and I also like your framing here as "strong typing for icons", that's exactly what it is. It's also worth noting that, in cases where logic is needed to choose which icon is displayed, you need a computed function anyway, and at that point returning an Icon object instead of a string isn't any extra work.

In T282625#7082536, @Jdlrobson wrote:

Trade-offs:

The duplication trade off is probably not a big deal - I think that is already happening. For example many of the same icons in Minerva desktop are also loaded inside VisualEditor.

It is already happening, but only for extensions/skins that chose to use custom icon bundles rather than using the standard OOUI ones, and I think Minerva (and Echo, to a lesser extent) are the only ones using custom bundles to load core icons. Most other code use the OOUI modules, which doesn't result in the same icon being loaded twice, but does result in lots of unused icons being loaded. The WVUI system is basically equivalent to everyone doing what Minerva does. I agree it's probably worth it, since the bandwidth wasted by loading some icons twice is probably much less than the bandwidth wasted when loading an entire icon pack just to use one icon. Loading multiple features on the same page that are both heavy icon users is also not common, and most of those cases are probably going to be things like skins, with most of the duplicated icons being in a small set of popular ones. If we really wanted to, we could do a later optimization where popular icons are always loaded when WVUI is loaded, and are no longer bundled with individual modules.

Loading an icon in WVUI always loads all versions of the icon (both directionalities, all languages)

This actually sounds like a good thing. In future with an API driven frontend we'd be able to switch the UI in JavaScript from LTR to RTL. We're already shipping multiple icons for colors, so that trade off might counter-act this one.

Yes, it's certainly true that shipping 2-4 versions of every icon because of colors is much more wasteful than shipping multiple versions of a handful of icons because of RTL and language versions (after gzip, the former may be less wasteful, sure, but it applies to all 200+ icons rather than only 16 of them).

Storing all SVG paths in one single file and requiring them to be single paths makes it harder to work on them (T260815).

I think a build step could take care of this con. It feels like it would be trivial to parse SVGs to grab the path and then generate an asset exporting those.

Yes, we could definitely build the icons.ts file based on a JSON definition and a set of files. I would also like to investigate if we can use some Rollup trickery to make something like this work:

export const wvuiIconImageAdd: IconVariedByDir = {
	rtl: require( './icons/image-add-rtl.svg' ),
	default: require( './icons/image-add-ltr.svg' )
};

Icons are not separated into bundles like they are in OOUI, they're all in one big file.

I agree that this is a big challenge - some kind of build step definitely needed. I wonder if async components could be used in some way to handle this?

If we wanted icon bundles, it'd be easy enough to make them: we could add e.g. src/entries/icons-media.ts that contains something like import { WvuiIconCamera, WvuiIconChart, ... } from '../themes/icons'; export { WvuiIconCamera, WvuiIconChart, ... };, and configure our build to produce a separate file in the dist/ directory for that. In general though, I don't think the lack of bundles is much of a problem, since the system is designed to load and bundle individual icons instead. Related to that:

In T282625#7081261, @santhosh wrote:

In general, I think it is important to make an early decision on whether consumers of wvui require a build system or not. The requirement of treeshaking(and hence the build step) or not is crucial to answer the design questions here.

I agree that consumers using a build step makes it easier for them to tree-shake out only the icons they need, and bundle those with their code (the WVUI library itself would not be bundled, it'd be loaded separately). But it's not required: it wouldn't be too difficult to provide ResourceLoader support for bundling icons into an existing module, as an alternative for code that doesn't want to have to use a build step just to be able to use icons. This would require writing sort of a next-generation ResourceLoaderImageModule but for the WVUI system, which I don't think would be hard to do, and I'm hoping to write a proof of concept for that soon. (What I'm thinking of so far is having WVUI generate a JSON blob with all icon data as a build product, then putting a somewhat generic "embed this JSON file but only a subset of its keys" feature in ResourceLoader.)

In T282625#7082536, @Jdlrobson wrote:

TBH It's useful having the icons inside wvui and the approach with ResourceLoaderImageModule has not been perfect - it requires a lot of explaining (institutional knowledge) and leads to lots of modules in the repo (Minerva has about 8 of them). T244558 and T248912 remain open. Assuming we are going to get server side rendering, it feels like the right approach to move away from it and to allow icon rendering only inside Vue.js.

...and of course that proof of concept would need to address these pain points too.

In T282625#7081261, @santhosh wrote:

1. The strong binding of available icons to javascript helps you to use quickly discover and pick an icon through autocompletion features of popular IDEs.
2. A build step or even real time checks by IDE make sure you are not refering an icon that does not exist. This is better than a loose dependency like CSS classnames

Pretty much every time we've introduced a UI component with an icon we've spent time checking through the available icons to decide on the most appropriate one so having an autocomplete list seems of very limited use other than preventing a typo (which should be obvious with cursory testing).

If we get this functionality with our chosen system then great, but I wouldn't weight it as an important factor when choosing.

Hi @Catrope - I recently captured some ways we would like to ideally extend the icons set usage on T280666:

• Colours - being able to easily implement icons in different colours within the Wikimedia palette.

• Adding icons as part of content - example when used in explanatory text or instructions.
  
  

In T282625#7087847, @RHo wrote:

Hi @Catrope - I recently captured some ways we would like to ideally extend the icons set usage on T280666:

Thanks!

• Colours - being able to easily implement icons in different colours within the Wikimedia palette.

This is doable only with obscure workarounds in OOUI's icon system. Now that T280934 is done, this is easy in WVUI's icon system, because icons' colors can be styled in CSS as if they were text (with the color property). As you point out on the task you linked, guidance should be added to the Design Style Guide for when to use colored icons and what colors to use.

*Sizing - guidance or extended guidelines for smaller or larger sized icon sizes in certain contexts (e.g., when used in smaller text labels, used larger in header text)

There is some talk of this on T260617. Right now, WVUI's icon system always displays icons at 20x20px, whereas OOUI scales icons according to the font size of the surrounding text. I think we could do the same in WVUI by setting the width and height of the icon's <svg> element to something relative to the font size (e.g. 1.42857em, which is 20px when the surrounding font size is 14px).

• Adding icons as part of content - example when used in explanatory text or instructions.
  
  

This is something that I'd like for us to support, but we'll have to think about how it will work, and how we can make it easy to use. We would probably want the icon to be a message parameter like it is currently (so the i18n message looks like Click on the "Link" button $1, and select...), and we'd have to provide an easy way for the code that uses this message to generate the right thing to pass in as the value of $1.

Not only, but also from a future theming and theme-independence perspective, it's not crystal clear to me that WVUI itself needs to or should store the icons. This could be done in an external library, similar to what WikimediaUI Base is for the variables definition to provide a clearer separation.
The single-path expectation is a not small hurdle, specifically if it were that we can't automate it properly and need to rely on non-FLOSS software like Adobe Illustrator.

Another point I've made in today's front-end dev standards meeting on this topic:
Currently we're providing the “WikimediaUI” theme icons for extensions via OOUI lib through ResourceLoaderOOUIIconPackModule without needing to load OOUI itself.
From design systems perspective we also need to include an ability to provide such replacement as well even though not necessary as part of WVUI itself.

Please also keep T275914: Using WVUI via ResourceLoader should expose icons in mind - OOUI lets end users say new OO.ui.ButtonWidget( { icon: 'alert' } ); without needing to worry about what the SVG for the 'alert' icon will be, but WVUI requires users and developers to copy the icon definitions to then pass back as a parameter.

T286955 is another example where the single-path versus normal multi-path SVGs has cost valuable time and originated in an otherwise simpler avoided mistake.

From the strawman poll today, where we discussed two options:

Decision from Designer Workshop meeting from vast majority of designers without objection:
Move forward with the WVUI way and choose more freedom path.

In T282625#7089110, @Catrope wrote:

In T282625#7087847, @RHo wrote:

• Adding icons as part of content - example when used in explanatory text or instructions.
  
  

This is something that I'd like for us to support, but we'll have to think about how it will work, and how we can make it easy to use. We would probably want the icon to be a message parameter like it is currently (so the i18n message looks like Click on the "Link" button $1, and select...), and we'd have to provide an easy way for the code that uses this message to generate the right thing to pass in as the value of $1.

You'd also have to consider screenreaders. When icons are used, they are often decorative and coupled with a titled function (button, header etc). But when used in this way, you will have to provide alternative text to screenreaders, using the alt property of the img element or something.