Name convention for icons in the XWiki icon set

Development
#1

Hello!
I’ve been spending a bit of time improving and cleaning up our documentation for icons. You can see the current version of this document in the front end developer resources: https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/Icons/ . Feel free to update and/or fix it with info I might have missed so far.

In this context, I realized that we never chose a name convention for icons. At the moment, there are a few disparities in icon names, and I’d like to avoid those in the future. It will make it easier to maintain, but also easier to use. Hereafter is my proposal for an icon name convention:

Icon name convention :

  • Use kebab-case.
  • For composite names, the main noun is the first in the name. Examples:
    • ‘file-add’ and not ‘add-file’ because the main noun is ‘file’ here ‘add’ is the action
    • ‘pdf-export’ and not ‘export-pdf’ because the main noun is ‘pdf’ and ‘export’ is the action.
    • ‘bullet-black’ and not ‘black-bullet’ because the main noun is ‘bullet’ and ‘black’ is an adjective
    • ‘emoticon-smile’ and not ‘smile-emoticon’ because the main noun is ‘emoticon’ and ‘smile’ is a complementary noun.
    • ‘fast-forward’ is one noun with an hyphen.
    • ‘file-pdf’ and not ‘pdf-file’ because in the meaning of this icon, the main meaning is ‘file’, while ‘pdf’ only helps to refine the meaning. On the contrary, ‘pdf-file’ would mean that we want a ‘file’ variation on the main concept of ‘pdf’.

Justifications:

What do you think of this name convention for the icons in the XWiki Icon Set? Is there an additional rule that would make sense to define? Is there some additional examples we should include to make this convention as simple to understand as possible?

Thank you for your interest!
Lucas C.

#2

Sounds good to me. I guess the naming conversion will apply to new icons we add. What about the existing icons that don’t follow the convention? Should we deprecate those and introduce new icon names that follow the naming scheme?

Thanks,
Marius

#3

I think we can still keep the old names in the icon themes, but move them to a deprecated category. We already have a bunch of deprecated icon names for all Silk icons so IMO it’s okay to move a few more in there. I’ll probably take the opportunity to organize deprecated icon names by version, just like what we do for translations, so that it’s easier to keep track of.

Lucas.

1 Like
#4

+1

#5

+1 thanks

Also, +1 to make the ‘invalid’ names deprecated, and to reintroduce them with ‘valid’ names.

#6

Globally sounds good to me, thanks.

One alternative is to not make exceptions as in:

And instead remove the hyphen in this case since it’s not following the general rule, i.e use “fastforward” instead.

Another example: use icontheme-silk instead of icon-theme-silk, and file-whatsnew instead of `file-whats-new``

ie to keep the dash as being always the kebab separator.

I don’t have a strong opinion though.

Thanks

#7

Makes sense to me :+1:

So I’ll be adding to the set of rules:

  • Remove hyphens from compound nouns.

Thanks!
Lucas.

#8

Awesome, Lucas thank you for working on these docs. It will really help with the work of revamping the interface.

+1 on the proposed conventions

One question, for the icons that currently are not mapped from Font Awesome could we create an 1:1 mapping? Like, from “fa-landmark” to “landmark”. It is unavailable in the mapping but featured in Font Awesome. Of course, it would not have a default mapping to Glyphicons for example, but the “slot” would be available for anyone that wants to customize and release an icon theme.

Including these icons would really help @amilica and me with the proposals that we are making.

Thank you!

#9

Hi!

Unfortunately, I don’t think that’s something we should do. Adding an icon to the icon set means being able to support it with most themes (on paper, all of them). If we don’t make sure that the icon meaning is normal enough to fit most icon themes, we’ll eventually end up in the same situation as the one we’re in now when trying to move away from FA 4. Right now, we use icons from Silk that are not mappable to other icon themes, such as textfield_add and it makes it difficult to find a correct alternative to these and move away definitely from Silk.

So IMO if you want to add icons to the theme, you can open a proposal so that we make sure that every icon has a correct mapping :slight_smile:

See Proposal: add icons to the XWiki Icon Set , I need to close it someday but that’s the idea.

Thanks for your feedback!

I’ll add the naming conventions to the Icon documentation.

Lucas

#10

I think it would be good to have all best practices in one place, so you could put it where you suggested but I think it would be good to link it from https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices somewhere. Or the other way around, as you wish.

Thanks!

1 Like