Page MenuHomePhabricator

Codex guidelines: update the format of the icon names
Open, Needs TriagePublic

Description

Background

At the moment, the icon names are included in different ways in the Codex documentation:

Captura de pantalla 2024-05-08 a las 11.19.06.png (336×1 px, 78 KB)
In some pages, the names of icons are included using cdxIconLinkExternal and using code snippets. E.g. in the "Using links and buttons" guidelines
Captura de pantalla 2024-05-08 a las 11.21.19.png (528×1 px, 87 KB)
In other cases, icon names are included within quotation marks (e.g. 'success' icon) and without code snippets. E.g. in the components guidelines.

We need to decide the best approach to include the names of icons in Codex and update the guidelines accordingly to be consistent.

Acceptance criteria (or Done)

  • Decide the best approach for the icon names in the Codex doc site
  • Update the Codex pages accordingly

Event Timeline

@bmartinezcalvo can you provide some examples of where we're not doing this?

@bmartinezcalvo can you provide some examples of where we're not doing this?

@CCiufo-WMF I've included some examples in the description.

As much as we should unify terminology, I'm torn between unifying and negatively impacting readability of names beyond just technical terminology. Reading
“These external links must use the external link icon, cdxIconLinkExternal, in addition to the text to denote a destination outside of the current domain.” vs
“These external links must use the external link icon 'linkExternal', in addition to the text to denote a destination outside of the current domain.”
I prefer latter.
An alternative would be to have another column in “All icons” to include a name and then a code column.

I agree with the simpler, easy to read, latter approach in Volker's comment.

I also agree with the simpler name for icons, either within the Codex Guidelines or the List of all icons. So if possible I would rename the first columns in the List of all icons to be with the simpler name ('linkExternal'), explaining in that page that all icons will include the "cdxIcon" at the beginning of the name in code.