When using BcIcons in your project for the first time, you’ll need to include the spritesheet at a high-level, eg:

import BcIconsSpritesheetPath from '@bugcrowd/bc-flair/dist/assets/icons/bc-icons-spritesheet.svg?url'

// TODO: Document me 🙏
BcIcons.setSpritesheetPath(BcIconsSpritesheetPath)

You’ll only need to do this once, generally.

For more on the spritesheet setup, see the HTML section in this entry.

Using <BcIcons />

To include an icon into a view import it:

import { BcIcons } from '@bugcrowd/bc-elements'

Then use the name prop to pick the icon you’re after:

<BcIcons name='attach'>

<BcIcons /> props and features

The size prop’s default is N/A because left unset, <BcIcons /> will try to match the font-size of the parent block it is nested inside.

Understanding the spritesheet setup

This component draws the icon you wish from a generated SVG ‘spritesheet’ of all the icons.

The spritesheet is built by nesting SVGs with (unique) IDs for each icon so you can <use> them, literally. 🙂

You’ll want to include the spritesheet into project’s views at a high-level.

By importing the spritesheet into your project, the file will only be loaded once and will be cached.

This benefit also applies to multiple instances of the same icon: they all draw from the same single icon from the many defined in the SVG spritesheet file.

You have a variety of options to include the spritesheet in plain HTML/markup.

For React setups: see the React documentation section in this entry.

The spritesheet

We version control each icon as its own individual SVG file in Git.

We then use our spritesheet generator script, compiling them together into a single SVG spritesheet.

The assembled spritesheet looks like this:

<!-- bc-icons-spritesheet.svg -->
<svg>
  <!-- Defs structural container -->
  <defs>
    <!-- the Activity feed icon: -->
    <svg id="activity-feed" viewBox="…">
      <path fill="…" d="…" />
    </svg>
    <!-- the Android icon: -->
    <svg id="android" viewBox="…">
      <path fill="…" d="…" />
    </svg>
    <!-- the (orange) Bugcrowd icon: -->
    <svg id="bugcrowd" viewBox="…">
      <path fill="…" d="…" />
    </svg>
    <!-- the (transparent b) Bugcrowd icon: -->
    <svg id="bugcrowd-internal" viewBox="…">
      <path fill="…" d="…" />
    </svg>
    <!-- etc. -->
  </defs>
</svg>

The icon-* IDs here are auto-inserted by the spritesheet generator, using the individual icon filenames for the slugs.

The individual (source) SVGs

We store each icon as separate, individual files in Git.

Why individual icon source files? Because it gives developers flexibility and source access to individual icons. It also gives DS Maintainers fine-grained icon version control and file/code ownership.

Example individual icon source file:

<!-- bugcrowd-unfilled.svg -->
<svg viewBox="0 0 24 24">
  <path fill="currentColor" d="…" />
</svg>

All icons must have canvas viewBox dimensions of 24 by 24 (effectively pixels at 1:1 scaling).

Also notice the path element sets fill="currentColor". This allows dynamically setting icon colors via CSS, as the path’s color can now be inherited via the parent color property, relative to the location where the SVG is <use>d. 😎

Exceptions are limited and manually composed to maintain color contrast visibility across all background colors, between both the light and dark color themes.

Calling an icon and the resulting HTML

Call an icon from the spritesheet using <use>:

If you’re working in React this is simplified for you, eg. <BcIcons name='bugcrowd-unfilled' />.

That said, the markup to call an icon is fairly simple also:

<svg><use href="/host/path/to/spritesheet.svg#bugcrowd-unfilled"></use></svg>

<BcIcons /> abstracts <use> to do this and set some other properties for you.

The final resulting HTML, when rendered:

<span class="bc-icons">
  <svg
    class="bc-icons__svg"
    viewBox="0 0 24 24"
    width="100%"
    height="100%"
    focusable="false"
    role="none"
    aria-hidden="true"
  >
    <use href="./assets/bc-icons-spritesheet.svg#bugcrowd-unfilled"></use>
  </svg>
</span>

If the icon requires changing its (singular) color the component will append a BEM modifier/variant class which changes the color, which in turn is picked up by the SVG’s fill="currentColor".

For example, to color the orange Bugcrowd hexagonal logo mark, the .bc-icons--bugcrowd class sets the .bc-icons’ --local-color CSS Variable to our brand orange.

Caveats of <use>

SVGs cannot be loaded from a CDN when using <use>.

See In the case of CORS: CSS to the rescue.

Icon semantics (or lack thereof)

⚠️ These Icons are intentionally designed to be presentational-only, that is, they carry no semantic meaning.

Why are icons removed from the Accessibility Tree?

If the icon is used to carry important meaning and no text label is given, an accessible label or title needs to provided.

👉 See Accessibility section on this page.

Resources

• MDN Web Docs — SVG
• SVG 2.0 Specification

👉 See the BcIcons Storybook entry of all icons.

The following table is hardcoded and will be auto-mapped in the future.

Do’s and Don’ts using Icons

• Icons should enhance, not overwhelm content — avoid overusing them.
• Maintain a balance between iconography and textual content.
• Prefer using icons additively to text because icons by themselves can be difficult to identify.

⚠️ Note the <BcIcons /> component has no semantic value as it is removed from the Accessibility Tree via aria-hidden="true" and role='none'.

Why are icons removed from the Accessibility Tree?

Therefore when icons are used alone, in absence of any nearby labelling text string, the parent node of the icon should receive an accessible label.

For example when using an ‘icon-only button’, give the <BcButton /> a clearly titled aria-label.

For more on labels see the Labels’ Accessibility section.

See also the HTML section on this page.

Further reading: CSS Tricks’ Accessible SVGs.

We use icons as visual markers to aid visual users to signify common and familiar actions.

These icons follow our general iconography guidance.

Why are icons removed from the Accessibility Tree?

The <BcIcons /> React component set aria-hidden='true', which alongside role='none' removes the icon from the Accessibility Tree (AT).

This marks the icon as having no semantic value in the page or UI.

We decided to do this and direct developers to provide accessible labelling or titles for icon-only instances themselves, for 2 main reasons:

1. Because icons are often used inside interactive components which should be labelled, rather than a nested presentational icon.
2. It radically reduces complexity of the React component.

We thereby avoid having to spread nested props or logic to support one of the 3+ mutually exclusive ways of labelling or setting <title>s.

We experimented nested SVG <title>s which behaved inconsistently in screen reader testing. Moreover, it is hard to predictably match source file <title> strings with downstream icon use cases, resulting in misnamed icons, which automated testing is poor if not incapable of catching for us.

Why SVGs?

SVGs are awesome! The decision to use SVGs follows web development best practices, offering many benefits:

• SVGs scale better than raster graphics
  • This supports an accessibility requirement to allow users to page zoom up to 400%.
• SVGs come in XML, perfect for storing with version control (Git)
• SVGs are a web standard and widely supported by modern design tools
• SVGs have great browser support

Why in-DOM SVGs?

In-DOM SVGs are the only way to set SVG fill colors dynamically via currentColor.

For detailed specifications see our Systematic Iconography — Spec (internal).

• Iconography
• Colors
• Icon (deprecated)