Add an Icon API and SVG library to core.

[jenlampton]

It would be nice to have a single set of matching icons for our administrative interface. It would be even better if this set of icons were also more comprehensive than only the icons we are currently using, so that contrib could also add matching icons to their administrative interfaces.

It would be great if these icons could be used:

• In contrib modules (for developers)
• In contrib themes (for developers)
• In CSS (for developers)
• In JavaScript
• In menu items (for developers, or maybe admins with a UI in the future?)
• In content (for editors)

It would be great if the icons could be extended in the following ways:

• additional icons should be easy to add
• it should be possible to replace or override which icons are in use (in some places)

We will be improving the user experience by creating a system that will remain consistent regardless of modules used. If we create an enviornment where these icons are easy for our developers to use, they will also be improving the user experience by remaining consistent with core.

---

Original Issue

We have a handful of icons in core that are currently images. We should replace these with an icon font instead.

Up-sides of using an icon font in core:

1. A complete set of matching core icons This leads to increased consistency in the look/feel of core icons.
2. Core won't need design resources or to spend much time adding new icons when they are needed.
3. Better User eXperience due to ease of adding an icon wherever one is needed. Providing matching icons in core will make a prettier and more usable product.
4. Contrib icons could easily match core look/feel provide a standard that contrib can adopt for adding icons where needed.
5. Better Developer eXperience for all backdrop site owners. provide a built-in utility for site builders to easily add an icon where needed.
6. Contrib/Custom projects won't need design resources Contrib and custom projects also don't need design resources (or to spend time) adding new icons
7. Beautiful vector icons on all browsers. All icons on all browsers will scale beautifully.
8. Change color and resize using CSS alone. Contrib and custom projects can color and size any icon appropriately using CSS alone.
9. No messy SVG fall-back code. If we can switch to using an icon font, we won't need 2x the CSS to account for browsers that can render SVGs and those that can't.
10. Accessible icons Unlike background-image icons, HTML based icons would be accessible.

Down-sides of using an icon font in core:

1. Markup changes would be necessary for accessible icons.
2. We'd be depending on an external library
3. It's tedious to add new icons to an icon font (example: a Backdrop logo).
4. Font file size could be larger than ideal to provide maximum utility.
5. Super fancy front-enders prefer SVGs to fonts.

Icon font libraries for consideration (and their license)

• ForkAwesome (now deprecated)
• FontAwesome v4 MIT for Free Version / Proprietary for Pro Version
• Bootstrap Icons MIT
• Libricons (not updated in years)
• Google's material design icons - Apache
• Bunny Fonts - An openly-licensed, privacy-first, GDPR compliant, drop-in replacement for Google fonts
• Feathericons MIT
• Phosphor icons MIT

Current icons we can/should replace with new icon font icons

See #6548

---

Related issues:

• Add icons to the Admin Bar #1841 Add icons to the Admin Bar
• [UX] Layouts: Use icons within drop buttons on small/mobile screens #1974 Use icons within drop buttons on small/mobile screens
• [UX] Config page: Add icons to the config sections. #1178
• Seven theme's task-check.png should have transparent background #1795
• Seven: icon cleanup: replace old icons with lager font-awesome equivalents & rename. #2802

[quicksketch]

This seems like it would be a great followup to #356, where we want to replace the Admin Bar favicon with an icon.

[ghost]

First order of business would be to request the Backdrop icon gets added to the repository: http://fontawesome.io/community/#requesting-new-icons ;)

[jenlampton]

I'm not sure that needs to be the first order of business, are we even using the Backdrop icon (anywhere other than the installer) in core?

But, yes. :)

[kreynen]

It's worth pointing out that Libricons uses a GPLv2 or later compatible MIT license (https://github.com/ry5n/libricons/blob/master/license.md), while Font Awesome uses a "GPL friendly" SIL OFL license (FortAwesome/Font-Awesome#1124).

The fact that the Free Software Foundation doesn't even use GPL licensed fonts in their projects without the Font Exception clause (GPL+FE) makes my head hurt.

@jenlampton Licensing isn't fun, but it is important. Hope to see you at the BoF in PDX :)

[jenlampton]

I don't think we run into the same problems as Drupal because we are not hosting this code on drupal.org, and don't need to adhere to those same guidelines. Maybe we should add the font exception somehow to make that clear?

We can freely bundle GPL compatible (or friendly) things together, here on github, can't we? @quicksketch do we need to add anything about external libraries to our licensing page?

[dboulet]

The fonts themselves are SIL OFL 1.1, the rest of the CSS and LESS files are licensed under MIT.

One thing to consider is file size. Font Awesome includes 479 icons—probably way more than would be necessary. Would the plan be to add them all, or to include a subset of the more useful icons in Backdrop?

[quicksketch]

Thanks @dboulet, that's very helpful. Looks like SIL OFL is compatible with GPL and can easily be bundled: http://scripts.sil.org/cms/scripts/page.php?item_id=OFL-FAQ_web#e71fabc0

Font Awesome looks like it ranges between 80KB and 300KB fully loaded, depending on which font (TTF, OTF, SVG) your browser supports. Those requirements don't seem too steep for the amount of usefulness you could get from it. On the other hand, users might want to hand-assemble a list of font icons entirely, in which case we could do the opposite extreme and only bundle the icons we need via a tool like http://fontello.com/.

And even our icon wouldn't be admitted into Font Awesome right away, there's nothing stopping us from bundling our icon into it in our distribution.

We can freely bundle GPL compatible (or friendly) things together, here on github, can't we?

Yes, Github has no license restrictions.

@quicksketch do we need to add anything about external libraries to our licensing page?

We already state that everything is GPL or a compatible license, so I think we're good:

Backdrop includes works under other copyright notices and distributed according to the terms of the GNU General Public License or a compatible license. Individual works may have specific copyright information noted within their their source code files or directories.

[kreynen]

@quicksketch While I agree that a GPLv2 or later licensed projects can include OFL licensed fonts, that does not make OFL "GPL compatible" in the strictest sense of that phrase.

I realize I'm splitting hairs here, but the term "compatible" means something very specific in regards to licenses (http://www.gnu.org/licenses/gpl-faq.html#WhatIsCompatible). This is the advice the Free Software Foundation gave the FontAwesome project regarding their GPL compatibility claim...

FortAwesome/Font-Awesome#1124 (comment)

It is OK to distribute fonts licensed under the terms of the SIL OFL 1.1 alongside a GPL
licensed work. What we mean by "alongside" is that the font and the program would be
considered "separate works" under the terms of the GNU GPL, because they aren't
combined in any way, but simply aggregated."

You are also correct that GitHub does not require specific licenses nor do they police the repositories for license violations or incompatible license combinations (like an Apache2 library in a GPLv2 project), but that doesn't mean projects using GitHub shouldn't take licensing seriously and understand how the licenses of the libraries and assets they commit to their repository and end up being distributed as part of (or with) the project play well (or poorly) together.

The GPLv2 or later compatibility requirement on Drupal.org is self imposed and something we're trying to modify to match the reality that GPL licenses aren't appropriate or popular for non-code assets... and hundreds of developers ignore the policy. OFL is popular for fonts and Creative Commons for images, but these licenses aren't technically GPLv2 or later compatible... and shouldn't be. These assets serve very different purposes than code and the communities that contribute to the creation, improvement, distribution, and reuse of those types of assets have adopted well thought out licenses that serve them well.

The example I use to illustrate how ridiculous Drupal's policies are is all documentation is licensed as CC Attribution-ShareAlike 2.0. Someone had enough foresight to add that code snippets were also GPL licensed, but the text itself is only CC. That means if I copy text from Drupal.org's documentation, paste it into a module's hook_help, and commit that I'm violating Drupal's Git Policy, the Creative Commons license on the content and/or the GPL license on the code.

Outside of Drupal, you'll find very few a modern web projects trying to jam "everything" into a GPL licensed download.

I don't know of anyone including the FSF who recommends using GPLv2 licensed fonts without the Font Exception in a project. Using an MIT licensed asset and relicensing it as GPLv2 or later the way Drupal believes all "laxed licensed" assets are when they are committed to their git repository, is problematic... unless you don't believe that the Free Software Foundation understands licensing. We just went through this when someone requested https://github.com/Automattic/Genericons be whitelisted on Drupal.org so it could be included in a distribution.

Everything is fine when using a GPL font to generate HTML, but using it to generate documents in a proprietary format like PDF is an issue.

http://www.gnu.org/licenses/gpl-faq.html#FontException
http://en.wikipedia.org/wiki/GPL_font_exception

The GNU project uses the FE in their own fonts http://www.gnu.org/software/freefont/license.html and explains the difference between web output and PDF output in their FAQ http://www.gnu.org/software/freefont/FAQ.html

Can I use GNU FreeFont in my non-GPL PDF document?
Yes. This is precisely what the special exception is for in the license.

So without the FE, you cannot legally output a GPL font as a PDF. By saying a font is GPLv2 and giving people the option of generating a PDF with it, you are essentially enabling/encouraging them to violate the GPL.

I'm sure we will get into how other projects like WordPress and Joomla handle this at the PNWDS Licensing BoF. They have been far less restrictive than Drupal, but I'm not sure that was actually a good thing.

So go ahead and package FontAwesome, but please start a LICENSE-EXCEPTIONS.txt or something like that to the GPLv2 LICENSE.txt to track anything that is in the project that isn't strictly GPL and please stop saying that everything in Backdrop is GPL or a compatible license.

[quicksketch]

and please stop saying that everything in Backdrop is GPL or a compatible license.

Can you suggest a different phrasing that we could use on our licensing page/README? We currently have:

Backdrop includes works under other copyright notices and distributed according to the terms of the GNU General Public License or a compatible license. Individual works may have specific copyright information noted within their their source code files or directories.

[kreynen]

On http://fortawesome.github.io/Font-Awesome/license/ @davegandy went with "GPL Friendly". On http://fortawesome.github.io/Font-Awesome/ they are now very specific about which licenses the different assets of the project use.

I think it makes sense to include something like...

Backdrop includes code and functional assets that include copyright notices and are distributed according to the terms of the GNU General Public License or a compatible license. Backdrop also includes other, non-code assets (fonts, images, etc) that are licensed with GPL friendly licenses that allow them to be packaged and distributed with the larger GPL licensed project.

Even that is probably too wordy and confusing. If you find a project that spells this more clearly, please let me know. These are the type of things some of the people pushing for the Drupal LWG will be talking about at PNWDS.

[quicksketch]

The wording around generic non-GPL licenses seems like it could be tough to follow. Let's try to be explicit in any non-GPL items and just list them specifically in the README and license page. Like this:

Backdrop includes code and functional assets that include copyright notices and are distributed according to the terms of the GNU General Public License or a compatible license. Backdrop also includes other, non-code assets (fonts, images, etc.) that are licensed with GPL friendly licenses. These non-GPL works include:

• Font Awesome: SIL OFL 1.1

[jenlampton]

I like this suggested wording, and would like to include that change in this PR, along with the icon font.

As far as how much / which font to use, even if core only uses 15 icons, people using backdrop are likely to use more - social media icons being the most common. Should they have to add an additional library (or the same one - a second time) to get more icons? I think the payoff of anyone being able to use icons from font-awesome is huge. Is the downside worth loosing that? If not, let's add em all :)

[dgoutam]

If we consider font awesome as community decision how should we include it? CDN or bundle the fa.min.css or src? My recommendation is to include fa.min.css.

[jenlampton]

CDN is not a great idea because I'd like it to be able to work "offline" so to speak. I also like using fa.min.css. Let's put it in core/misc.

[quicksketch]

I connected with the front-end Lullabots (where I work) on this. 5 of 5 front-end 'bots agree that icon fonts are "not cool". With front-end technology changing so quickly and icon fonts being kind of a hack in the first place, I'm not too surprised. Apparently the time for SVGs has finally arrived, and that is the preferred approach at Lullabot at least.

I like the general idea of an icon font (easily reusable icons), but we be jumping in on an approach that is already on the way out. I'll need more evidence to back this up, but for now I think let's just look at the alternatives and evaluate if we have any better options, namely SVG backgrounds. Here's a few references:

http://caniuse.com/#feat=svg-css
http://css-tricks.com/using-svg/

We still support IE8, so that makes the problem a little more challenging for us than it did D8, which adopted SVGs and may not have had to worry about fallbacks.

[jenlampton]

Though it may be possible for us (core) to create SVGs for every icon that we need to use, but the same is not true for people who use our software.

With an icon font adding icons for anything (social media? style for the search box?) is as easy as adding a few HTML tags with specific classes. Without it, people need to hire a designer to build SVGs or go through the painful process of selecting and adding their own library of icons. Using an icon font not only solves our problem of needing icons, but also solves that problem for all our users. It's win-win.

It's important to keep in mind that our primary target audience isn't Lullabots, or even the folks that can hire the Lullabots. Not everyone can afford to hire someone to build and design them a stellar site. If they can, then sure, create custom SVGs for everything. But let's start by solving the problem for the lowest common denominator :)

As for chasing the latest and greatest, that's a tenant of working with Drupal, but not as important for Backdrop. Let's stick with the tried-and-true (and more importantly, easy) for Backdrop 1.x. We can reevaluate moving to SVG for 2.x if that's really what wins.

[ghost]

Let's stick with the tried-and-true (and more importantly, easy) for Backdrop 1.x. We can reevaluate moving to SVG for 2.x if that's really what wins.

I agree.

[quicksketch]

I started trying to figure out what this would look like from an implementation stand-point. My first thought was that it would be registered as a library in system.module, like jQuery UI:

  $libraries['font-awesome'] = array(
    'title' => 'Font Awesome',
    'website' => 'http://fortawesome.github.io/Font-Awesome/',
    'version' => 4.2.0,
    'css' => array(
      'core/misc/font-awesome/css/font-awesome.css' => array(),
    ),
  );

Then other libraries that used icons would declare Font Awesome as a dependency. However, after looking at the list of icons in the issue summary, we'd almost certainly make things like system.theme.css dependent upon Font Awesome. Unfortunately, icons like the Tabledrag arrows considered functional requirements, so system.css itself would be dependent upon Font Awesome. That pretty much means that every site on every page would always have Font Awesome required. The only way to disable it would be to use a contrib/custom module to provide CSS replacements for all the icons used by core, but even then once contrib modules start using other icons on the front-end, it'd be pretty much impossible for a theme or module to try and selectively provide icons for what is needed. You'd have to use the full Font Awesome set all the time because you don't know what contrib modules are using which icons. Only a custom-built theme with a lot of elbow-grease would be able to effectively limit the display of Font Awesome on the front-end.

If we were to put Font Awesome into core, there'd be little benefit to making it a library for the purposes of dependencies, because enough markup would be dependent upon it that you'd end up with it on the page nearly all the time.

[dgoutam]

there'd be little benefit to making it a library +1

• To take advantage of font-awesome we need to change markups everywhere in core to replace image tags with span tag so making it a library might not give us more of a benefit
• In my opinion just put it under css\vendors for ease of version management and use it in different core modules
• Other option could be to put this under admin theme and override all the core module templates under it

[quicksketch]

To take advantage of font-awesome we need to change markups everywhere in core to replace image tags with span tag so making it a library might not give us more of a benefit

Modifying the markup everywhere is one of my chief concerns with an icon font. We're basically going to be locking ourselves into supporting Font Awesome for at least a major release cycle.

Overall, I'm still not keen on the idea of an icon font in the first place. I've been looking into alternatives to see if we could reach some kind of compromise. The explanation for why we want an icon font in the first place isn't entirely clear. Are we doing this for high-resolution displays? Because we don't like the current icons? Because we don't have design resources? Inconsistency? Or for the convenience in contrib reusing the same icons provided by a font?

My primary concerns are around high resolution displays, which are uncommon on PCs, becoming ubiquitous on Macs, and already on every new mobile/tablet device. PNGs just look terrible compared to their vector counterparts.

I looked again at SVG options and perhaps maybe we could compromise and use the icons from Font Awesome but leverage them as SVGs instead of a font. A potential process:

• Use a tool like https://icomoon.io/ to select the icons you want from Font Awesome.
• Export as SVG/PNG images at the desired color.
• Adjust size/color/margin as needed in Inkscape or Illustrator.
• Compress using svgo or some other tool to remove unnecessary cruft.
• Add to CSS as background image using the SVG fallback method from http://css-tricks.com/svg-fallbacks/

This is clearly more work than tacking on a class and then adjusting the font size, but it has it's share of advantages. Here's a pro/con list:

Pros

• No markup changes required and no API to support in the future.
• Used only where we need it, easy to disable or override (just modify the CSS).
• We can still use all the icons from Font Awesome (or any other font, license allowing).
• No external library to maintain.
• Supports more than one color where needed.

Cons

• Tedious to add new icons.
• Color is part of the SVG and cannot be changed with CSS (yet)
• IE8 requires a PNG fallback.
• Requires a CSS hack for the PNG fallback (see the code).
• Only adds the icons needed by core, so it wouldn't provide as much utility to contrib.

Here's what it looks like in code (converting just the 2 icons in Admin Bar): https://github.com/quicksketch/backdrop/compare/364/admin_menu_icons?expand=1

And at a 2x display of the admin bar home icon (PNG):

And as SVG:

Thoughts on the approach? I'd like to see what the motivation is for an icon font in the first place. If it's just the icons themselves, we can get them in ways that don't require changing our markup or locking us into a library.

[jenlampton]

For me, adding an icon font solves lots of problems for Backdrop:

1. icons look better on high-resolution displays
2. moving away from the current icons separates our identity from Drupal 7
3. increased consistency in the look/feel of core icons
4. core won't need design resources (or to spend much time) adding new icons
5. provide icons that are easy to style (size, color) with CSS alone.
6. provide a built-in utility for site builders to easily add an icon where needed
7. provide a standard that contrib can adopt for adding icons where needed
8. contrib/users also don't need design resources (or to spend time) adding new icons
9. increased consistency in the look/feel of contrib/user inserted icons (that also match core)

If we added the icons from font-awesome but not the actual font, we'll only be solving items 1 - 3 on this punchlist. It's still an improvement over where we are now, but if we can also solve items 4 - 9, that would be the real win.

[tjdjours]

I avoided the use of icon fonts for quite a while, thinking they'd soon be replaced completely by svgs.

But when I started using svgs myself, I realized they demand the same sort of spriting as pngs/jpgs/gifs. And even with sass churning out the css on those svg sprites, I found sizing/placement to be problematic with background-* and the stuff noted 5) of Jen's list, above. What a hassle. And where svgs are the source of icon fonts, I've come to view icon fonts as flexible spriting of svgs.

2cents.

[jenlampton]

What I'm hearing is that SVG's just aren't a suitable replacement for an icon font yet, though they can be used as stand-alone background images (as long as we have an alternate fallback for IE8).

If we can get on the same page about adding an icon font to core, I might be convinced that we could use an incomplete version of font-awesome (via fontelo or similar). That would cover items 1 - 5, but still leaves 6 - 9 unresolved. :(

[dariusgarza]

Why do people create icon fonts?

I've been using them for a while but now I realize that it's just as easy to copy and paste the svg code into an html document as it is to add hacky icon font markup.

The noun project has thousands of svgs ready to go. Here's another
repository of awesome svg's

I'm not sure if this is best practice, but I cooked up this fiddle to see if using svg's was as easy as font awesome, and it was!

@quicksketch Mentioned that CSS styling was not possible yet with SVG's, but it seems to work? So now I'm confused.

The biggest obstacle seems to be png fallbacks with IE8, but otherwise I think using svg's is the way to go. Is there anything else you think I've overlooked? @jenlampton

[quicksketch]

Mentioned that CSS styling was not possible yet with SVG's, but it seems to work? So now I'm confused.

You can only use CSS styling on inline SVGs (embedded into the markup). An external SVG can't be styled with CSS currently, unless you us a JS library to copy external SVGs into the contents of the page.

I think @tjdjours's feedback was great regarding custom fonts: they're essentially sprited vectors. That's good for performance and compatibility. I could go either way on this.

[quicksketch]

Thanks @herbdool! I'll leave this at least until tomorrow to let anyone else raise any concerns.

[indigoxela]

I think we've got far enough to mark it RTBC.

Agreed. The changeset is pretty big and we seem to have entered the phase of design tweak and polish, which IMO could get handled in a follow-up. That would make it easier for people to contribute, I guess. Currently even applying the patch locally is a challenge. 😉

[quicksketch]

I merged backdrop/backdrop#4688 into 1.x to allow for more iteration. Wow, this is pretty exciting!

backdrop/backdrop@95ebf3d by @quicksketch, @herbdool, @indigoxela, @jenlampton, @stpaultim, @wesruv, @klonos, @stpaultim, @hosef, @olafgrabienski, @bugfolder, @dariusgarza, @BWPanda, @kreynen, @dgoutam, @dboulet, @davegandy, and @tjdjours. Phew! Thank you to everyone that contributed to this issue since 2014!!

[klonos]

Reopening, to keep the task of adding a change record in our radar.

[quicksketch]

Change record filed here: https://docs.backdropcms.org/change-records/new-icon-api

Additionally we have the new documentation page detailing most of the new capabilities of Icon API here: https://docs.backdropcms.org/documentation/icon-api

[quicksketch]

Adding the change record surfaced that we missed adding @since lines to the newly added functions and hooks. I filed a follow-up PR for adding missing documentation here: backdrop/backdrop#4755

[quicksketch]

With the change record and docblocks update, this issue is now finally closed. 🎉