stackexchange/stacks-icons

Authoring tools for Stack Overflow's shared icon set.

Icons

Including Stacks Icons in your project

Stacks Icons are delivered via NPM. It can be installed with npm i @stackoverflow/stacks-icons

Manifest

See https://icons.stackoverflow.design/ for an up-to-date list of all icons and spots.

Use in JavaScript or TypeScript

Using the library by importing a subpath (e.g. /icons) will allow for tree-shaking unused icons from your bundle.

// es6 / module syntax
import { IconFaceMindBlown } from "@stackoverflow/stacks-icons/icons";
import { SpotWave } from "@stackoverflow/stacks-icons/spots";

// both icons and spots are unescaped html strings
console.log(IconFaceMindBlown); // "<svg>...</svg>"

// require() syntax
const { Icons, Spots } = require("@stackoverflow/stacks-icons");

// `Icons` and `Spots` are objects mapped by <icon name, html string>
console.log(Icons); // { "IconAccessibility": "<svg>...</svg>", ... }

Using the CSS icons

In certain cases where adding the raw svg markup to your html would cause bloat or if you need your markup to be more portable, consider using CSS icons. Note: Not all icons are available as CSS icons.

<!-- include the required css file -->
<link
    rel="stylesheet"
    href="/path/to/@stackoverflow/stacks-icons/dist/icons.css"
/>

<!-- add the "svg-icon-bg" class in addition the desired "iconNAME" class -->
<span class="svg-icon-bg iconBold"></span>

<!-- the icon's color matches the "currentColor", so changing the "color" property will change the icon color -->
<span class="svg-icon-bg iconFire" style="color: red;"></span>

<!-- add the "native" class to get native styles; these do not respect "currentColor" changes -->
<span class="svg-icon-bg iconFaceMindBlown native"></span>

For performance / file size reasons, not all icons are available in css. You can add support for more CSS icons my editing the cssIcons value in scripts/definitions.ts.

Use in dotnet

Stacks-Icons also provides a NuGet package that targets netstandard2.0.

See the dotnet/src/README.md file for more details.

Using the front-end helper for prototyping

Note This method is not intended to be used in production

If you include the browser.umd.js within your prototype’s body element (<script src="https://unpkg.com/@stackoverflow/stacks-icons/dist/browser.umd.js"></script>) you can render Stacks Icons in the browser using only the following format:

<svg data-icon="IconFaceMindBlown" class="native"></svg>
<svg data-spot="SpotSearch"></svg>

This package looks out for elements that look like svg[data-icon]. If the icon doesn’t exist in Stacks, it will throw you an error in console. Anything in the class="" attribute will be passed to the included SVG e.g., native

Developing locally

First, you'll need a Figma personal access token. Once you have that, place it in a .env file in the root of the repo:

FIGMA_ACCESS_TOKEN="your_access_token_here"

Install the necessary dependencies:

npm i

Run the build:

npm run build

Developing the dotnet library

You'll need to first run the general package build as outlined above, as the dotnet solution pulls the generated csharp files from the build directory.

You can then build the library locally via:

npm run build:nuget

or run the unit tests with:

npm run test:nuget

Adding or updating icons/spots

All icons and spots are pulled directly from Figma via their API. The only way to add or update icons is by directly modifying the source Figma file and then publishing a new component release from within Figma.

In order to ensure that any new icons/spots in Figma are pulled into this repo, the definitions will need to be added to scripts/definitions.ts:

const figmaIconDefinitions = {
    // ...
    "Icon/IconName": "",
    // ...
};

When adding new entries, please ensure that all entries are in alphabetical order for ease of reference. The initial value is ok to leave empty. Once you run the first build process, it'll throw an error like the following:

Hash mismatch on 1 files. Expected hash values: "Icon/Accessibility": "ksqXzQjdToAghXkIQ75PE/8qRdUho8Wtux1FTo+mgug=",

Take this hash value and use it as the value for the previously added entry. Re-run the build process and verify that your new icon is added correctly and has the correct contents.

When updating an existing icon, just update the hash as explained in the previous section.

Publishing a new release

In order to publish a new release to npm and NuGet, you just need to tag a new release and push it to origin:

npm version [major|minor|patch]
# for prerelase candidates instead use:
# npm version prerelease --preid rc
git push --follow-tags

From there, our GitHub packages action will build the packages and push them to their respective repositories.

Afterwards, make sure you mark a new GitHub Release based on what has changed.

This project follows SemVer. Versions including breaking changes to the visual api (e.g. icon drastically changes design or is removed) or code api should be marked major. Versions including new features (such as a new or updated icon) should be marked minor. Everything else is a patch release.

stacks-icons's Issues

Natively-sized voting Q&A actions icons

If we're to replace the Q&A questions actions with SVG replacements, we'll need natively-sized icons.

Add an icon for columns

As reported by @UXPiper, we could use an icon for column sorting / editing.

Generated ESM module is missing the Icons and Spots namespaces

The generated index.esm.js file lacks namespaces and conflicts with the typescript definitions.

The distributed module contents only define the names found inside the icons and spots modules, which then are all exported as is. Because of this, you can't actually use import { IconFaceMindBlown } from "@stackoverflow/stacks-icons/icons"; as the documentation claims.

Instead, you get an error:

index.ts:1:35 - error TS2307: Cannot find module '@stackoverflow/stacks-icons/icons' or its corresponding type declarations.

1 import { IconFaceMindBlown } from "@stackoverflow/stacks-icons/icons";
                                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can't simply use import { IconFaceMindBlown } from "@stackoverflow/stacks-icons"; as the type information tells typescript that at that level only Icons and Spots are available.

To reproduce, in an empty directory create the following three files:

package.json

{
  "name": "mcve",
  "dependencies": { "@stackoverflow/stacks-icons": "^5.3.1" },
  "devDependencies": { "typescript": "^4.9.5" },
  "scripts": { "build": "npx tsc" }
}

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "node",
    "target": "ES2020"
  },
  "files": ["index.ts"]
}

index.ts

import { IconFaceMindBlown } from "@stackoverflow/stacks-icons/icons";
export { IconFaceMindBlown }

then run

npm install && npm build

New icon: download

On Stack for Business, we have a billing page that has action items to download the invoice and receipt. I think this might be an opportunity for us to add a download icon to go alongside download links (or replace if we're very tight on space).

I found these two icons on Google Material design and Flaticon but thinking we might want to simplify it to a down arrow with the line underneath?

More editor-related icons

Hi, I want to based my editor on Stacks-Editor but the number of icons is kinda limited. Is there anyone who can create "missing" icons (like for example H1 to H6 icons, alignment icons and many more) or I would have to do them by myself?

@Svg.Tada isn't fully greyscale

When @Svg.Tada is rendered without the native class, there's a little orange (and maybe blue?) shooting out of it.

New Icon: TrendingNone

We have @Svg.TrendingDown and @Svg.TrendingUp, but what if a metric isn't trending in a meaningful way and it's the same compared to the last time point? It would be nice to have an icon representing no change in trend.

This a common icon used in the sports world to show when teams are moving up, down, or staying in the same place in a league's standings / table. I'm open to suggestion here, though.

Deliver as a nuget package

Our icons should be delivered as a nuget package for other solutions to consume. We should include all the icons and spots, while generating a helper.cs file that provides definitions.

Deliver icons as backgrounds for high-traffic situations

Went for a long drive today and may have accidentally come up with a solution allowing for the same flexibility in our icon set that SVG allows, only for PNG.

Proposal

1. Either export from Figma, or build PNGs from our optimized SVG set @2x and #000.
2. In a .css file, export something like .png-icon.iconLink with background-image: url(../path/to/Link.png)
3. Build atomic coloring classes for .png-icon that's based on CSS filters using this tool. eg. .png-icon.iconLink.fc-orange-400. These classes will also have their dark mode equivalents.
4. Provide a PNG helper in the same way we do SVG. eg. @Png.Link.With("fc-orange-400")
5. Profit.

Any thoughts before I hack together a proof of concept?

Things to solve / discover:

1. General path issues. How do we keep this self-contained as a straight dependency, and integrate into Stack Overflow
2. Inheritance. If we have <div class="fc-orange-400"><div class="png-icon"></div></div>, we'll probably want that icon to be orange.
3. Will just delivering the retina version of these be enough, or will scaling a 2x image on 1x screens be good enough?
4. ???

Guide for usage in Markdown

I would like to use the StackOverflow icon within my Markdown as an image link like so:

[![alt text](logo) Link to SO tag](https://stackoverflow.com/questions/tagged/my-tag)

Is it possible to consume these icons in this way?

I was surprised not to see them available on https://icongr.am/

Add diff icons

We could use some icons to represent rendered markdown, markdown source, and diffs.

Spot Illustrations

Let's include spot illustrations in our icon set.

TODO:

• Create spot illustrations from 32px, 64px, 128px, and 256px
• Create build script to ingest Illustrator SVG
• Talk to production folks about how we deliver these via helper since the file size will be much larger
• Find a way to include aliases for shapes. A single icon should be able to have any number of names.

SVG Files are missing XMLNS, thus failing to load

The <svg> tag in most icons (e.g., LogoEnterprise.svg) is missing the xmlns="http://www.w3.org/2000/svg" attribute. This causes them not to load as images in Chrome, Firefox or Internet Explorer. GitHub also shows an invalid file error: https://github.com/StackExchange/Stacks-Icons/blob/master/build/lib/LogoEnterprise.svg

This is already the case in the build/lib folder, so it's not a problem of the Gruntfile/Build process.

Correction: This IS a problem with the build process, the original icons are in src/export and are good: https://github.com/StackExchange/Stacks-Icons/blob/master/src/export/LogoEnterprise.svg

Support a wider range of emotions

In surveys, we should be able to include a wider range of emotions. Beyond Happy, Sad and Neutral.

TrashSm

For when you're trash, but also smol.

Needed to accompany PencilSm.

Figma integration

Our icons should be available to us in Figma now that we have a team license.

1. Each icon should be a component in a shared library
2. Our final icon code should be generated by a shared Figma document

New icon: Jira

Can we get an icon for Jira? They're available on Atlassian's design system, though I'm not sure which one we want:

Update Enterprise logo. Add Teams, Talent, Engagement

Update the Enterprise logo icons with "For Enterprise" version. Add "For Teams" logo, as well as SO Talent and Engagement logos.

Include phone and laptop

In our documentation site, we include phone and laptops directly in the markup. We should consider adding these to our icon set.

Conflicting gradient IDs are causing strange coloring

When Instagram and Jira, two icons that each have gradient fills, are used on the same page, their gradient IDs compete, causing unpredictable coloring.

Export PNG versions of the icon set

• Find the canonical color for icons and render them
• Allow them to be downloadable in our docs

Define a richer aesthetic

Given the following technical constraints:

1. Icons can have native coloring like that bulb at the lower right. That's the native colors we can show if the engineer decides they want to.
2. Icons can be re-colored using 1 color as shown in a stock grayscale version.
3. Icons can be re-colored on the fly using a pop / selected color. This can be a Team's themed color, or perhaps a selected state.

We're going to find a richer aesthetic that works at:

1. 18px / 16px
2. Offers decent legibility
3. Allows for rich colors that can be re-colored
4. Feels like Stack Overflow

For example, these are rendered too large to satisfy legibility at 18px / 16px, but satisfy technical constraints:

Add a preview of the final icon output

We should also build a simple html index of the final output for smoke and visual regression testing. I've been trolled too many times by fill rules filling in icons entirely.

New Icon: Tiny up and down arrows

It'd be nice to have the 16x16 up and down arrows in the image below available in Stacks and in the Core/svg.helper

Add an icon for Discord

Similar to the Slack and MSTeams icons already in Stacks, please add an icon for Discord. Icons can be found at https://discord.com/branding