Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FLUID-6391: Updated the docs to reference Infusion-Icons #149

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

FLUID-6391: Updated the docs to reference Infusion-Icons #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
77d6977
FLUID-6391: Updating docs to include info about Infusion-Icons
jobara Aug 12, 2019
2f2a8a4
FLUID-6391: Linting
jobara Aug 12, 2019
8291b59
Merge branch 'master' into FLUID-6391
jobara Sep 15, 2020
3c630bd
FLUID-6391: Fix erroneous comment.
jobara Sep 15, 2020
5d7d314
FLUID-6391: Remove IcoMoon documentation.
jobara Sep 15, 2020
8c8c356
FLUID-6391: Refine SVG Icon information.
jobara Sep 15, 2020
b040ac6
Merge branch 'main' into FLUID-6391
jobara May 11, 2021
9e2530f
FLUID-6391: Cleanup
jobara May 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed src/documents/images/Unicode-charmap.png
View file
Open in desktop
Binary file not shown.
Binary file removed src/documents/images/mac-characters-window.png
View file
Open in desktop
Binary file not shown.
Binary file removed src/documents/images/mac-font-book.png
View file
Open in desktop
Binary file not shown.
173 changes: 80 additions & 93 deletions src/documents/tutorial-iconFonts/HowToCreateAndUseFontIcons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,22 +14,21 @@ Some of the advantages of icons include:
* Can add strokes, gradients, shadows, and etc.;
* Convert to text (with ligatures);
* Ligatures are read by screen readers;
* Changing icons to fonts is as simple as changing the font-family in CSS.
* Changing icons used is as simple as changing the font-family in CSS.

However, there are some shortcomings to keep in mind:

* Icon fonts are generally mono tone in colour.
* IE8 and IE9 do not support ligatures.
* Globally changing fonts will cause the text vs the icon to show.
* Need to use `!important` or scoping to prevent globally changing fonts from swapping out the icons.
* In situations where there is existing text accompanying an icon, specific markup containers need to be created for the
icon.
* Modifying icon fonts is as involved as generated a new icon graphic in the "traditional" way - there is no real time
saved in that regard.
* Modifying the icon font requires generating a whole new font file

## Procedure Summary

* Create the icon and save it as an SVG graphic.
* Use [IcoMoon](http://icomoon.io/) to generate a font from an SVG graphic.
* Generate a font from an SVG graphic(s).
* Add the font to your markup. Example:

```css
Expand All @@ -56,30 +55,47 @@ Use illustration software to create an SVG version of the icon you want to use a

Tips:

* The dimensions of the graphic doesn't matter since everything will be scaled by the browser's font-rendering.
* The dimensions of the graphic doesn't matter since everything will be scaled by the browser's font-rendering. However,
all of the icons should be sized and drawn in a consistent fashion.
* Work in binary (i.e. black and white) and do not apply effects such as drop-shadows or embossing.
* Sometimes the font conversion of the SVG may not work properly, so be prepared to edit your SVG file again.
* Overlapping regions of shapes may cause a subtraction when converted in IcoMoon (i.e. it will render as transparent) -
in this case you may need to build a single shape from these conflicting shapes, or ensure none of your shapes overlap.
* Overlapping regions of shapes may cause a subtraction when converted (i.e. it will render as transparent) - in this
case you may need to build a single shape from these conflicting shapes, or ensure none of your shapes overlap.

Download Example SVG file: [pencil-icon-01.svg](/images//pencil-icon-01.svg)

## Step 2. Using IcoMoon to Generate Font
Consult the [Infusion Icons Visual Style Guide](https://wiki.fluidproject.org/display/fluid/Infusion+Icons+Visual+Style+Guide)
for how icons are created for Infusion.

Steps:
## Step 2. Generating the Font

1. Go to [IcoMoon](http://icomoon.io/app) (you can also run IcoMoon in "offline" mode in Chrome browser by installing
the [IcoMoon Chrome app](http://goo.gl/we6ra))
2. Import your SVG icon - select "Import Icons" and choose your SVG file.
3. Select your icon from the list (should appear under "Your Custom Icons" section, and select the "Font ->" button at
the bottom of the screen.
4. Save the ZIP file to a known location.
* Note: selecting the "Preferences" button will give you options to name your CSS classes and files. It i
recommended you use identifiers
5. Extract the contents of the ZIP file.
* The files we are most interested in are the `./fonts/*.eot`, `./fonts/*.ttf`, and the `./index.html` files.
6. To verify that the font looks proper, open the `./index.html` file in a web browser. If the icon doesn't look right,
you may need to edit the SVG file and repeat the font generation process.
In the past we recommended [IcoMoon](http://icomoon.io/app) to generate the icon font. We are now using
[Infusion-Icons](https://www.npmjs.com/package/infusion-icons) because it provides an easier means of modifying the font
and tracking PUA codes. With the Infusion-Icons fonts can be generated from a config file.

(See: [Infusion-Icons README](https://github.com/fluid-project/infusion-icons/blob/master/README.md) for more detailed
instructions)

### Example

```json
{
"src": [
"svg/iconName.svg"
],
"options": {
"font": "CustomIcons",
"codepoints": {
"iconName": "0xE000"
}
}
}
```

```bash
# generating an Icon Font from a config file
grunt build --config="path/to/config.json"
```

## Step 3. Working with CSS and HTML

Expand All @@ -105,54 +121,42 @@ Next, add the new font to the CSS markup.

```css
@font-face {
font-family: 'CustomIcons'; /* Specify the new font */
font-family: 'CustomIcons'; /* Specify the new font */
src:
url('../fonts/CustomIcons.eot?#iefix') format('embedded-opentype'),
url(' CustomIcons.ttf'),
url(' CustomIcons.eot');
url('../fonts/CustomIcons.eot?#iefix') format('embedded-opentype'), /* IE8 fix. */
url('../fonts/CustomIcons.woff');
}

#contact_form {
background: url("../images/envelope.png"); /* existing image that will be replaced by icon */
font-family: 'CustomIcons'; /* the new font icon */
font-family: 'CustomIcons'; /* the new font icon */
}
```

Finally, add the new icon into the BEFORE pseudo class and delete any references to the old icon image.

```css
@font-face {
font-family: 'CustomIcons'; /* Specify the new font */
font-family: 'CustomIcons'; /* Specify the new font */
src:
url('../fonts/CustomIcons.eot?#iefix') format('embedded-opentype'),
url(' CustomIcons.ttf'),
url(' CustomIcons.eot');
url('../fonts/CustomIcons.eot?#iefix') format('embedded-opentype'), /* IE8 fix. */
url('../fonts/CustomIcons.woff');
}

#contact_form {
/* old icon image has been removed. */
font-family: 'CustomIcons'; /* the new font icon */
font-family: 'CustomIcons'; /* the new font icon */
}

#contact_form::before {
content: "\e000"; /* the custom Unicode (aka. PUA) for the icon. */
content: "\e000"; /* the custom Unicode (aka. PUA) for the icon. */
}
```

This is all that is needed to add the new icon to your markup. You will notice there is a line specific to IE8 - for
more information on this, please see
[http://www.fontspring.com/blog/the-new-bulletproof-font-face-syntax](http://www.fontspring.com/blog/the-new-bulletproof-font-face-syntax).

## Unicode for font

_The Unicode (or "PUA code") for the custom font can be found in the HTML and CSS file generated by Ico Moon. If the
HTML and CSS files are unavailable, you can retrieve the Unicode using one of the methods listed under the section
"[Dealing with the TTF Unicode](HowToCreateAndUseFontIcons.md#dealing-with-the-ttf-unicode)" below._

**However, there is a problem** - the new icon font will replace the existing font of its container and all child
*elements and therefore removing any font styling you may have wanted to preserve. The next section will outline common
*issues and how to fix them and some best practices.

## Common Issues

### Preserving Existing Fonts
Expand All @@ -174,9 +178,7 @@ contents within the `<a>`, which means "Contact us" will no longer be Comic Sans
```css
@font-face {
font-family: 'CustomIcons';
src:
url('../fonts/CustomIcons.ttf'),
url('../fonts/CustomIcons.eot');
src: url('../fonts/CustomIcons.woff');
}

body {
Expand Down Expand Up @@ -206,8 +208,7 @@ contained within. The CSS file is then updated to reference this new markup stru
@font-face {
font-family: 'CustomIcons';
src:
url('../fonts/CustomIcons.ttf'),
url('../fonts/CustomIcons.eot');
url('../fonts/CustomIcons.woff');
}

body {
Expand All @@ -228,23 +229,22 @@ body {
It's common for images to be used in functional ways such as acting as a button within an anchor tag. For example:

```html
<a href="download.html><img src="./images/download.png" alt="Download our latest stuff!"></a>
<a href="download.html"><img src="./images/download.png" alt="Download our latest stuff!"></a>
```

The problem here is if we replace the image in the anchor with an icon font, any text descriptions (the alt text) will
be removed as well - causing a possible usability and accessibility issue.
However if we replace the image in the anchor with an icon font, any text descriptions (the alt text of the original
image) will be removed as well; potentially causing usability and accessibility issues.

```html
/* The alt text is now gone, causing a usability and accessibility problem. */
/* The alt text is now gone, causing a usability and accessibility issue. */
<a href="download.html"></a>
```

```css
@font-face {
font-family: 'CustomIcons';
src:
url('../fonts/CustomIcons.ttf'),
url('../fonts/CustomIcons.eot');
url('../fonts/CustomIcons.woff');
}

a {
Expand All @@ -265,14 +265,15 @@ To bring back some semantics and to help improve accessibility, we use "aria-lab

### Cross-Browser Oddities

Icon fonts can appear different across browsers and across operating systems. For example, the following icon is
rendered differently in Firefox in Mac OS X and in Windows despite being the same icon and the same browser.
Icon fonts can appear different across browsers and operating systems. For example, the following icon is rendered
differently in Firefox in Mac OS X and in Windows despite being the same icon and the same browser.

![a partially displayed font icon on firefox, Mac system](/images//Icon-FF-OSX.png)
![a partially displayed font icon on firefox, Windows system](/images//Icon-FF-windows.png)

To avoid these rendering problems, when creating the SVG images avoid using fine details - not only does this help
eliminate details in the icon font being lost during rendering, it also helps improve usability through clearer icons.
eliminate details in the icon font being lost during rendering, it also helps improve usability through clearer
icons.

### IE8 Compatibility

Expand All @@ -281,53 +282,39 @@ format('embedded-opentype')` to your CSS. For example:

```css
@font-face {
font-family: 'CustomIcons'; /* Specify the new font */
font-family: 'CustomIcons'; /* Specify the new font */
src:
url('../fonts/CustomIcons.eot?#iefix') format('embedded-opentype'),
url(' CustomIcons.ttf'),
url(' CustomIcons.eot');
url('CustomIcons.woff');
}
```

The IE8 fix needs to be the first URL in the list of sources otherwise the font will not appear.

Reference: [http://www.fontspring.com/blog/the-new-bulletproof-font-face-syntax](http://www.fontspring.com/blog/the-new-bulletproof-font-face-syntax)

### Dealing with the TTF Unicode

Ico Moon conveniently generates an HTML and CSS file for custom fonts which contain the Unicode to be used in your
markup. However, in the scenario the original CSS or HTML files are unavailable, here are two ways to obtain the Unicode
on Windows and Mac OS X 10.6+.

#### Obtaining Unicode in Windows

1. Install the custom TTF font to the OS (usually a right-click then select "Install" from the context menu).
2. Run Character Map (done by searching the Start menu, or by typing Win+R then "charmap").
3. Select the custom font from the Font drop-down menu. The glyphs in the custom font should now appear in the window.
4. Select a character in the window. The Unicode will appear in the bottom-left corner in the status bar.

![Unicode character map](/images//Unicode-charmap.png)

#### Obtaining Unicode in Mac OS X 10.6 or Later
## What about SVG Icons

1. Enable Special Characters support as documented in this Apple Knowledge Base article:
[OS X Lion: Enter special characters and symbols](http://support.apple.com/kb/ph3871)
2. Install the custom TTF font to the OS (usually double-click, then "Install").
3. Launch the Font Book application.
4. Also launch the Notes application.
5. In Font Book, locate the custom font under Collection > All Fonts. Select it. The custom font should now appear in
the window.
6. In Font Book, select / highlight the characters from the custom font. Select Copy (Command+C or right-click -> Copy).
7. In Notes, Paste the text (Command+V or right-click -> Paste). The custom font should appear in Notepad.
8. In Notes, select the pasted text. Then open the "Edit" menu an select "Special Characters".
9. Now a "Characters" window appears with "Search" results containing each character selected in the previous step.
10. Select an icon in the "Character" panel. The Unicode will appear in the right column.
SVG icons can be used as an alternative to icons supplied through an icon font. Below is a quick summary of the pros and
cons of SVG Icons. For more information on SVG Icons see the
[Research SVG Icons](https://wiki.fluidproject.org/display/fluid/Research+SVG+Icons) wiki page.

![Mac OS X Font Book](/images//mac-font-book.png)
### Benefits of SVG Icons

Above: An image showing the Mac OS X Font Book application with the custom characters highlighted.
* Can use multiple colours
* Can support complex icons including multiple colours
* See: [Styling SVG <use> Content with CSS](https://tympanus.net/codrops/2015/07/16/styling-svg-use-content-css/) for
a detailed explanation on styling SVGs with CSS.
* Don't have to compile into a font

![Mac OS X Characters window](/images//mac-characters-window.png)
### Drawbacks of SVG Icons

Above: An image showing the Mac OS X Characters window. The Unicode value for a custom character appears in the right
most column.
* Less browser support, although modern browsers should handle most features.
* See: [caniuse](https://caniuse.com/?search=svg) for more details on supported features.
* Many different ways to add to a page, but only those that allow access to the SVG markup will permit styling via CSS
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May need to elaborate this point. Perhaps stating that embedding the SVG is the markup is the standard practice for styling SVGs with CSS.

* Embedding SVG markup directly into the page markup
* may make reading page markup harder
* Depending on how SVGs are added to the page, may increase transfer size due to lack of caching.
* `<use>` to import SVG into page markup
* Allows for styling and caching by referencing external SVGs
* Not supported in older browsers such as IE 11