User talk:Zorato/Icon Project

Proposal: Refactor Template:Icon.

Template:Icon has a lot of issues. Another template named Template:ILink appears to have tried to either compliment or outright replace the former, but that one has even more problems. So, I developed a replacement that doesn't get in its own way to simply render an icon. No clumsy customfile or type parameters. No coupling of icons and labels requiring two overrides to tame. I propose to completely refactor the current code in Template:Icon with an implementation that is flexible and simple to use.

Let's say I want to render the Comet icon. I would type: {{Icon|Icon ARC Comet.png}} which produces .

Already you can see the template is self-documenting; the requirement to type the '.png' suffix tells editors the first positional parameter is where the icon filename goes. Also, this completely sidesteps one of the issues the aforementioned templates have. Let's say we upload an '.svg' version of that same icon. This is what you have to type in the current version of Template:Icon:

{{Icon|customfile=Icon ARC Comet.svg}}

What if I want to give the Comet icon a label? This is the syntax for my version:

{{Icon|Icon ARC Comet.png|Comet}}

Comet

The current version of Template:Icon doesn't have support for labels, but Template:ILink does. In fact, you can't separate the labels from it. What do I need to type to display a '.svg' icon with it?

{{ILink|Comet|Comet|22|Icon ARC Comet|type=svg}}

This is for a '.png' icon:

{{ILink|Comet|Comet|22|Icon ARC Comet}}

Comet

This was but one issue I've covered. I could type a lot more, but I'd rather open the discussion. Please check out User:Zorato/Icon Project for more details and bring me any comments or criticism you may have. Zorato (talk) 22:49, 21 May 2026 (UTC)

Interesting, though, what's the advantage over using a module than just changing the ILink template to something like

<includeonly>[[File:{{{icon|{{{1}}}}}}|{{{size|{{{4|22}}}}}}px|link={{{imagelink|}}}]]{{#if:{{{text|{{{2|}}}}}}|<span class="icon-text">{{#if:{{{link|{{{3|}}}}}}|[[{{{link|{{{3}}}}}}}|{{{text|{{{2}}}}}}]]|{{{text|{{{2}}}}}}}</span>}}</includeonly> which in the end would be easier to maintain and modify for other editors?

I assume this proposal is just for Template:Icon and not the others that are linked within your page? If not then I'd like to also add, for things like Template:Currency and even more so your Template:Weight, it seems it's just adding unnecessary complexity involving a module into it when it's basically just one/two lines in a template for that type of template. Albeit Price template uses a switch function but still simpler. Luke (talk) 23:19, 21 May 2026 (UTC)

You're correct that the individual problems with Template:Icon can be patched in wikitext, but that's not what the proposal is about. The proposal is about replacing a patchwork of templates with a organized system where those problems don't arise in the first place. This pattern of slapping quick fixes onto templates and kicking the figurative can down the road is what this proposal is meant to break, and the alternative you shared actually demonstrates it.

The code you shared introduces an undocumented imagelink parameter that doesn't exist in the current template and wasn't discussed in your reply. There's also a brace counting error in the link parameter, so any call using positional parameter 3 would produce [[Page}|Text]], a broken link with a literal closing brace appended. This is exactly the kind of issue that's easy to miss in nested parser function syntax and difficult to catch until someone reports a broken link. That's the pattern: a quick fix that quietly introduces new problems.

Two modules and a family of wrapper templates are not a complex system. Module:Icon renders. Module:IconData looks up. The wrapper templates adapt the interface for editors. Three responsibilities, three places. That's not unnecessary complexity, that's clean separation of concerns. The "unnecessary" framing measures lines of code rather than what the system can do and how safely it can change. A wikitext template that does the same job in fewer lines but breaks silently when modified isn't simpler by any useful measure.

I'd encourage you to take a closer look at Module:Icon/doc and Module:IconData/doc, which cover how the system is structured and why the pieces are separated the way they are. The User:Zorato/Icon Project page also gives a full picture of everything involved.

I'm happy to continue the discussion once you've had a chance to look things over. Zorato (talk) 00:55, 22 May 2026 (UTC)

I have looked at the docs and gone through the code and history.

Fair play on catching the error within that template, that's why we always preview/test changes before making them, it's just I made that on a wim without testing to show it's possible with wikitext. The reason I shared it was to provide a quick example of something that can be done entirely in wikitext without a module, specifically because you mentioned the old parameters were clumsy. I wanted to show an easy, streamlined fix within the template itself.

In terms of "This pattern of slapping quick fixes onto templates and kicking the figurative can down the road is what this proposal is meant to break, and the alternative you shared actually demonstrates it."...I don't think we've touched ILink, Icon and Weight in months minus Dread adding the invert on light mode param today to ILink. I don’t think those templates have really shown the maintenance problems being described. The only reason I sent that template snippet was to show it was completely possible to handle the logic in pure wikitext (even if it contained a slight error), since you are proposing to change how the template works anyway.

Errors happen just as easily in modules when things get changed. However, saying “that’s the pattern: a quick fix that quietly introduces new problems” can really apply to any system, whether it uses modules, templates, or parser functions. In practice, most issues get caught because people generally preview and test their work before saving changes, so the likelihood of “quietly introducing new problems” is fairly low, especially on smaller utility templates.

For example, the ItemGrid module was modified last month which introduced a visual rarity arc issue, so I don’t think silent failures are unique to templates. In the end, bugs can happen regardless of being a template with parser functions or a module, the important part is testing changes properly beforehand.

Finally, you never really answered if it's just for Template:Icon or everything on your project page. Either way, it's not complex in the sense that the code is hard to understand, it's complex in the sense that when a template only really requires one-two lines. For very small utility templates, introducing multiple modules can feel unnecessary compared to a simple template. I'm mainly just trying to say, in terms of editors, if they wanted to make a simple change or fix something that breaks for some reason then it's less editor friendly especially for a template that could just be like Template:Weight <includeonly><div class="template-weight">[[File:Icon Weight.png|link=|{{{iconsize|22px}}}]]<span>{{{1}}}</span></div></includeonly>

I'd say keeping simple utility templates as wikitext template is a safer, lighter, and far more accessible strategy for a community-driven wiki.

Luke (talk) 02:36, 22 May 2026 (UTC)

The Icon Project is a unified system. The proposal covers it in full.

Before continuing, the standalone Weight template you offered is worth examining. It has several issues that should be addressed before it is used as a rebuttal, because it does not accurately represent the approach it is meant to defend.

1. The <div> wrapper breaks inline rendering by default.
2. Calling {{Weight}} with no argument renders the literal text {{{1}}} on the page.
3. The default {{{iconsize|22px}}} produces invalid file syntax for valid inputs.
4. There is no link parameter, so adding one requires nested parser functions.
5. The <span> has no class, leaving no consistent hook for styling.
6. The parameter is named iconsize, which adds no information given the context.
7. The template references a per-template stylesheet.
   

Both code examples offered as rebuttals to this proposal contained errors. The first had a brace counting mistake that would have produced broken links on every call with a link; the second had seven distinct issues. Nested parser function syntax makes these errors easy to introduce and difficult to catch. That is the problem this proposal exists to solve.

Here is a version that addresses all of the above:

<includeonly><templatestyles src="Template:Weight/styles.css" /><!--
::::-->[[File:Icon Weight.png|link=|{{{size|{{{3|22}}}}}}px]]<!--
::::-->{{#if:{{{text|{{{1|}}}}}}|<span class="weight-text"><!--
::::-->{{#if:{{{link|{{{2|}}}}}}|[[{{{link|{{{2}}}}}}|{{{text|{{{1}}}}}}]]|{{{text|{{{1}}}}}}}}</span>}}</includeonly>

The claim was that the logic of Module:Icon and Module:IconData is achievable in a simple wikitext template. No wikitext implementation can normalize inputs, validate required fields, or raise a named error when something goes wrong. Those are not edge cases. They are the core of what makes the system reliable. That the code submitted to prove this point was broken in the ways described above is a secondary issue, though notable given the earlier claim that editors generally preview and test before saving.

With a corrected template in mind, let's discuss your claims that "simple utility templates" are "safer, lighter, and far more accessible":

"Safety": The fixed wikitext still cannot enforce that an icon file exists, and still degrades silently when an editor calls it incorrectly. The system I developed is explicit about failure. For dataset-driven templates like {{Ammo}} and {{Condition}}, a typo in the key silently produces nothing. No icon, no label, no indication that anything went wrong. Module:IconData catches this explicitly, naming the dataset and the supplied key in the error message. That distinction matters on a wiki where template failures often go unnoticed until someone reports something broken a month or two later. If the priority is genuinely safer templates, it is worth asking why the issues with the current Template:Icon went unaddressed until this proposal raised them. The answer, as noted in this thread, is that these templates went untouched for months. Months of inattention are not stability. It is an unexamined system, and an unexamined system is not a safe one. The Icon system is demonstrably safer than your alternatives.

"Light": The modules I wrote are lightweight with few moving parts. This is clear from a cursory examination. Line count and module involvement are the wrong measures of template quality. Brevity is not a goal of its own. A template that omits necessary work is not lean. It is incomplete. The "complexity" at issue is required to make the system safe.

"More accessible": accessible to whom? Scribunto-driven icon systems are common practice across wikis, and many wikis using this approach have far fewer icons than this one. Wikipedia itself uses this exact architecture: wikipedia:Module:Icon backed by wikipedia:Module:Icon/data. Framing this as inaccessible conflates what editors touch in practice with what they could theoretically open. It is simply untrue.

The Icon Project was designed from the ground up with editors in mind. Every decision in the system reflects that: errors are caught loudly, inputs are normalized predictably, icons are kept in small per-family databases that anyone can extend with a single line, styling is centralized in one stylesheet, and the same call pattern works across every template in the family. Template:Weight is the simplest template in the family. It has one hardcoded icon and no lookup. The strengths of this approach are most visible in the templates not being discussed: {{Ammo}}, {{Condition}}, and {{ARC}}, where keys resolve to one of many icons and a typo produces a named error rather than silence. This system is easier to maintain, safer to extend, and more accessible to a community of editors than wikitext templates that each carry their own assumptions and failure modes. The approach you are defending looks simple. It is not simple to extend, not simple to maintain, and not simple to troubleshoot. A community-driven wiki is exactly where that difference matters most. Zorato (talk) 20:16, 22 May 2026 (UTC)

In terms of the Weight template, it was built mainly for infoboxes which always has values, it was never really made with the mind of making it to work in inline text. However, the joys of templates is that it would have been easy to change if someone wanted to use it for inline reasons as shown with your code. Though I'm not sure why you'd want to link the weight text, if you could give examples of why your linking wrapping would be useful for such a template like weight, that would give more insight.

When you say, "The fixed wikitext still cannot enforce that an icon file exists," which wikitext are you referring to? The first one I posted would display a standard missing file error on the page, which your current Template:Icon does anyway. As for the Weight one, that uses a single, fixed icon filename, so the file is guaranteed to exist.

"If the priority is genuinely safer templates, it is worth asking why the issues with the current Template:Icon went unaddressed until this proposal raised them" We can't address things that were never brought up in the past.

"accessible to whom?" You can't deny that Lua modules are less accessible than wikitext templates, which is why going Lua is usually a thing you do when things become to heavy to do in templates which imo, Icons aren't really "heavy" to do in wikitext

"Months of inattention are not stability. It is an unexamined system, and an unexamined system is not a safe one." If people report issues with the template then they would get fixed. However, no one has reported such issues. In the end, if it works as intended then it is technically 'stable'.

"Scribunto-driven icon systems are common practice across wikis, and many wikis using this approach have far fewer icons than this one." So are template icon systems, it just depends on the wiki.

Though onto more about the module(s):

You mentioned that you introduced error handling. If someone was to make a mistake and misspell something when doing like {{Ammo|mmag}} and doesn't notice the error for whatever reason, I assume readers would just see a massive, bright red script error right on the live page, right? Is there a tracking category that you are keeping track of these errors with so we can catch them behind the scenes?

In terms of light mode users, how does your module currently deal with it? considering white icons on a white background is bad UX

In terms of the icon to text alignment, I see that some of the text is not aligned correctly with the icon like 2,000,000. Is this something you are planning to fix within your css/module?Luke (talk) 23:46, 22 May 2026 (UTC)

In your previous reply, you mentioned that Dread added an invert filter to {{ILink}}. I see he also added the same filter to {{Icon}} two months ago. Unfortunately, the method chosen to apply the filter means, going forward, we will need to add invert = yes as a parameter to every white icon we apply. This is what's called "technical debt", which is the future cost required to solve suboptimal code written to quickly ship a product. The correct solution is to move inversion out of the call site entirely. That way when we inevitably find a better-designed method for inverting icons that doesn't impose a tax on editors, we won't need to hunt down every icon with the parameter to remove it. Other examples inside Template:Icon include file and customfile. We are both now of the opinion that the customfile parameter was a clumsy solution to an issue the template imposed on itself, but unfortunately this means we will need to work backwards and append '.png' or '.svg' to the end of every filename in every instance the template is used.

What I'm trying to say is that invert was just one more unnecessary parameter added to templates that already accumulate parameters to work around their own design. You and Dread are admins. I'm confused as to why anyone needed to "report" these issues when they were already visible to the admin team. No redesign was considered because they were not seen as problems. In your own words, "if it works as intended then it is technically 'stable'." Under that definition, every workaround that ships is by definition stable, because shipping the workaround was the intent. That definition of stability describes a system that grows a new parameter for every case it did not anticipate instead of producing a forward-thinking design that gracefully allows the template to handle the case in the first place. A system that works as long as nobody examines it too closely is not the same as a system that is robust to change. The status quo you defend is not what I would call "safe", "light", and "accessible".

The case for the module-based approach has been made and stands. The Icon Project is a system that has the backing of an actual scripting language which completely avoids these issues. The advantages are documented: consistent normalization, explicit error handling, centralized styling, and a call pattern that scales without per-template cost. To return to a point left unanswered, Wikipedia itself uses this exact architecture. A system like this is a common sight on wikis with far fewer icons than this one. So, the only substantive pushback remaining is that icons are not "heavy" enough to warrant a module. That is a preference, not an argument. It does not address normalization. It does not address error handling. It does not address the maintenance history of the existing templates. It does not address the question of whether Module:Icon and Module:IconData improve this wiki. The question is not whether icons are "heavy" enough for a module. The question is whether the module approach would improve this community-driven wiki, and the evidence answers that clearly.

Now, I will address your concerns:

Icon alignment. This has been fixed. The module now passes middle as a vertical alignment parameter in the image wikitext, which applies vertical-align: middle via the mw-valign-middle class on the image wrapper. The fix has been tested across multiple browsers and the alignment is consistent.

Light mode. Inversion is handled at the dataset level, not at the call site. When a dataset entry carries invert = true, Module:Icon wraps the image in a <span class="invert-on-light">, which applies the inversion filter in light mode. An editor calling {{Ammo|light}} does not write an invert parameter. The module reads the flag from the dataset and handles it transparently. This is the design described above: inversion moved out of the call site entirely. Such is the joy of modules.

Error handling. The error you showed is what an uncaught Lua error looks like. Both Module:Icon and Module:IconData use pcall in their entry points, which catches errors before they reach the page. When an error occurs, the module outputs a styled inline <span class="error"> with the error message, and the page is added to Category:Pages with icon errors for maintenance tracking. Readers see a small inline error rather than the full Lua error block you showed, and editors can find affected pages through the tracking category. Zorato (talk) 01:39, 24 May 2026 (UTC)

"Unfortunately this means we will need to work backwards and append '.png' or '.svg' to the end of every filename in every instance the template is used." the only usage of SVG I can see is condition timer svgs, quest objective things and the wikipedia icon but those don't use the Icon template, so easy enough to just use mediawiki tools should as ReplaceText to automatically append .png to text that is using the Icon template if this proposal was to go through.

You point out how our current {{Icon}} and {{ILink}} uses an invert param and how that is technical debt as you explained. However, if you were to say use your Icon template like your example here {{User:Zorato/Template:Icon|Icon Gift.png|Box of chocolates}} wouldn't that require an invert param considering it's not within a dataset and it's a white icon? What is the plan for icons that are not within a dataset and are called with your Icon template but also need to be inverted?

"You and Dread are admins. I'm confused as to why anyone needed to "report" these issues" We don't really spend our free time actively auditing lines of working code for theoretical perfection. If anyone raised an issue with said template, it would be dealt with, if they wanted to rework it then they could (now contributors need to make proposals these days for reworking content infra but back then they could just rework stuff). Wikis run on community usage; if a template works as intended and editors find it intuitive, it is stable. If everyone is happy using said templates, then they work. I'm not saying the templates couldn't have used some love, but anyone was able to do it including you in the past.

In terms of your icon alignment, it still seems to not be aligned correctly. 2,000,000

I see you have now improved the error message by removing the redundant bit of "Lua error in Module:IconData at line 45: " and just left "Module:IconData: no entry "mmag" in dataset "Ammo"" Though I still think that error could be improved slightly to make it less in your face to readers when they see it, if an error does happen.

I see you also added the light mode improvements I raised, glad you were able to implement it for datasets.

Also, you never gave examples for why the Weight template would need text link wrapping in the first place when it's only going to show like "1.0, 2.0, 0.4, etc etc", which would still give me some more insight on how it improves that template. Luke (talk) 03:56, 24 May 2026 (UTC)

Icons that are not within a dataset and require inversion will be moved into their own datasets, where the invert field handles inversion automatically. I have a few ideas in mind for how to approach this, and as has been the case throughout the development of this system, best practices will continue to guide those decisions.

The link parameter in Template:Weight is available for cases where it is needed and was included to keep the call pattern consistent across the template family. That said, the usefulness of this parameter was already a consideration during development. The use case for linking a weight label is likely uncommon, and removing the parameter with a note in the documentation directing editors to use standard link brackets, which accomplish the same thing, would be a straightforward and reasonable alternative.

The icon alignment fix has been tested across multiple browsers and reads as correctly aligned. Since browsers may render alignment slightly differently, I want to make sure the fix holds across every commonly-used browser, and there are a few other methods I can try if needed. Could you let me know which browser you are seeing the issue on so I can investigate further?

You conceded the templates that require parameters like customfile to handle SVGs "could have used some love". These templates also impose an invert tax on all editors adding white icons. However, in the same reply, the definition of stability has once again shifted: first it was "no one has reported issues," and now it is "editors find it intuitive.” That isn't a consistent position to have given that Module:Icon and Module:IconData lift the burden off every editor on this wiki that is required to use the aforementioned templates to add icons, but I'm glad we were finally able to see eye-to-eye on the matter.

The outstanding questions have been answered. The system is ready for integration. In the next few days, I will iron the wrinkles out and then ship the changes Zorato (talk) 22:21, 24 May 2026 (UTC)

"Icons that are not within a dataset and require inversion will be moved into their own datasets, where the invert field handles inversion automatically. " Isn't this now just a burden that you were trying to fix? Forcing a casual contributor to create or edit a backend Lua dataset for said icons just to use a one-off white icon completely destroys editor accessibility for simple page formatting.

"The icon alignment fix has been tested across multiple browsers and reads as correctly aligned." If you take a look at this image: https://i.postimg.cc/RVDfxPF6/image.png it shows the alignment problem (more so with the gift). The bottom bit of that image is how it currently works with the current Weight and Price template which looks a lot nicer imo. I am seeing this on both Firefox and Chromium-based browsers. Also, in your other response, you mentioned how you added mw-valign-middle; however, if I understand correctly, MediaWiki already applies vertical alignment to images by default.

Regarding stability, my position hasn't shifted, those two things I mentioned are connected. Editors find the templates easy enough to use, therefore they use them without issue, therefore no one reported problems. In reality, minor technical debt in wikitext is a trade-off worth making to keep the wiki accessible to casual contributors. If the templates genuinely needed improvement, contributors always had the opportunity to iterate on them over time, yet there was never much indication that editors found them difficult to work with.

Lastly, to clarify your closing statement, I assume by "shipping the changes" you mean finalizing the code within your own user sandbox and not actually pushing the change to the whole wiki? Luke (talk) 01:47, 25 May 2026 (UTC)

Two concrete points from your last reply before the rest.

Regarding icon alignment: The fix is live in Template:Icon/styles.css. The stylesheet applies a -1px vertical adjustment via transform: translateY(-1px) on icon images, which is a similar approach used in Template:Price/styles.css. If you still see misalignment on Firefox or Chromium, let me know which icon and which template, and I will investigate further.

Regarding inverted icons: An editor with a recurring white icon may add a two lines to the relevant dataset, which benefits every future use of that icon for every editor. Editors may type [[File:Icon Ammo Light.png|22px|class=invert-on-light]] directly if they do not want to type {{Ammo|light}}.

We don't force anyone to understand how to create templates, nor do we force anyone to understand how to edit them. May you describe a wiki where casual contributors are required to understand Lua module structure for normal page editing?

You agreed earlier that the templates "could have used some love," which acknowledges the current parameters are not without cost to editors. You also said the current system's technical debt is a trade-off worth making to keep the wiki accessible to casual contributors. Are casual contributors the people the current system protects, or the people the proposed system burdens?

"Easy enough to use" and "intuitive" are not the same standard. A template that requires editors to learn the distinction between file and customfile, or to remember to add invert for white icons, may be usable, but it is not intuitive by any definition. The bar has shifted from "intuitive" to "easy enough," which is clearly itself an acknowledgement that the system imposes an unintuitive cost on editors.

"Shipping the changes" means pushing them to the wiki. The proposal has been discussed at length, every concern raised has been addressed, and the case for the system has been made and documented. Under the wiki's own definition of consensus, that is the end result of productive discussion. I will iron out any remaining wrinkles in the next few days and then ship. If you have further concerns, please raise them before then Zorato (talk) 03:09, 26 May 2026 (UTC)

"We don't force anyone to understand how to create templates, nor do we force anyone to understand how to edit them." Your argument misses the fundamental difference between wikitext and Lua. Templates built with standard wikitext are more accessible because once an editor makes a few basic page edits, they naturally begin to understand the markup. It invites them to learn and contribute. A casual editor can easily look at a wikitext template and understand how to add a basic parameter to some degree.

"May you describe a wiki where casual contributors are required to understand Lua module structure for normal page editing?" In the general case, no, but that is not the point of concern being raised. You stated that icons requiring inversion will be moved into their own datasets. This means if a contributor wants to upload and use a one-off white icon within a normal page, the system leaves two practical fallback options: either navigate and edit a background Lua dataset, or use file markup with the class parameter while knowing which class to use. Neither option provides the same level of accessibility as a documented template parameter within the icon interface.

"Editors may type [[File:Icon Ammo Light.png|22px|class=invert-on-light]]" isn't this just worse than an invert parameter and introduces the "technical debt" you said you were "solving"? considering now if that class ever gets renamed, you will need to edit multiple articles with icons that use the class=invert-on-light minus just one template/module that has the invert param. Most editors would reasonably expect {{Icon}} to handle icons consistently, but the current proposal effectively says 'use {{Icon}} for some icons, but raw file syntax and CSS classes for others.' Basically this system isn't simpler or more accessible to editors.

" Are casual contributors the people the current system protects, or the people the proposed system burdens?" The current system protects casual contributors. A system can have technical debt and still be the more accessible choice if that debt is kept inside a stable template, rather than pushed outward into a backend structure. It is completely different from making contributors try to guess whether {{Icon}} supports a specific icon because it needs to be inverted, whether they need to fall back to file markup for said icon and use inline CSS classes like class=invert-on-light, or whether a simple one-off formatting case now requires editing a backend Lua dataset.

My recommendation is to add an invert parameter to the Icon template. It keeps things simple for editors who don’t want to deal with Lua datasets or raw CSS classes, and avoids the need to fall back to file markup for single-use inverted icons. It also means that if the underlying class ever changes, it can be updated in one place rather than across multiple articles.

To be completely clear, consensus on a community wiki does not mean "discussion has gone on long enough, so changes are implemented." It requires discussion to produce a broadly supported agreement on the best approach, as reflected in the Consensus section: "the end result of productive discussion and debate regarding the best practices for the wiki." Luke (talk) 09:08, 26 May 2026 (UTC)