bitwarden/clients
1
0
Fork 0
mirror of https://github.com/bitwarden/clients.git synced 2026-04-10 01:36:46 -05:00
Code Issues Packages Projects Releases 434 Wiki Activity
Files
main
clients/scripts/material-icons
History

README.md

Icon Font Management

This directory contains scripts and resources for managing the Bitwarden icon font (BWI).

Overview

The icon system uses Figma-exported SVG files that are converted into a web font using Fantasticon. SVG filenames directly become CSS class names (with the bwi- prefix added automatically), making the workflow simple and straightforward.

Adding a New Icon

Follow these steps to add a new icon to the icon font:

1. Export the Icon from Figma

  1. Open the Figma icon file
  2. Select the icon you want to export
  3. Export as SVG with these settings:
    • Outline stroke: Enabled
    • Include "id" attribute: Disabled
    • Simplify stroke: Enabled
  4. Name the file using kebab-case (e.g., help.svg, star-filled.svg, add-circle.svg)
  5. Save the SVG file to libs/assets/src/material-icons/

Important: The SVG filename directly becomes the CSS class name. For example, help.svg will generate the class bwi-help, and star-filled.svg will generate bwi-star-filled. Choose your filename carefully as it determines how developers will use the icon.

2. Generate the Icon Font

Run the build script:

npm run icons:build

This script will:

  1. ✅ Generate the icon font files from all SVGs (woff2, woff, ttf, svg)
  2. ✅ Update the SCSS with the new icon mappings
  3. ✅ Automatically update libs/components/src/shared/icon.ts with the new icon
  4. ✅ Clean up temporary build artifacts

Output files:

  • libs/angular/src/scss/bwicons/fonts/bwi-font.* - Font files
  • libs/angular/src/scss/bwicons/styles/style.scss - Updated with new icon
  • libs/components/src/shared/icon.ts - Auto-generated TypeScript icon list (do not edit manually)

Note: The TypeScript icon array is now auto-generated during the build process. You no longer need to manually add icons to icon.ts.

3. Add to Storybook Documentation

Add your icon to the appropriate category in libs/components/src/stories/icons/icon-data.ts:

// Choose the appropriate category:
// - statusIndicators
// - bitwardenObjects
// - actions
// - directionalMenuIndicators
// - miscObjects
// - platformsAndLogos

const actions = [
  // ... existing icons ...
  {
    id: "bwi-your-new-icon",
    usage: "Detailed description of when and how to use this icon.",
  },
];

Usage description guidelines:

  • Start with what the icon indicates or does
  • Include context-specific guidance (mobile, desktop, toggle states, etc.)
  • Mention any variants or related icons
  • Note any accessibility considerations

4. Test Your Icon

  1. Visual verification: Run Storybook to see your icon

    npm run storybook

    Navigate to "Documentation / Icons" to verify your icon appears correctly

  2. Type checking: Ensure TypeScript compiles without errors

    npm run test:types

  3. Usage test: Try using the icon in a component

    <bit-icon icon="bwi-your-new-icon"></bit-icon>

Migrating Icon Names

Use the migration script when you need to rename icon references across the entire codebase. This is different from adding a new icon—it's for bulk-renaming existing icon class names.

When to Use Migration

  • You're standardizing icon names to match new Figma conventions
  • You're replacing a legacy icon name with a new one
  • You need to update icon references in dozens or hundreds of files

Important: This is NOT for adding new icons. Use the "Adding a New Icon" workflow above for that.

How to Migrate Icon Names

1. Add the mapping to migration-map.ts

Open scripts/material-icons/migration-map.ts and add your mapping to the BWI_TO_FIGMA object:

export const BWI_TO_FIGMA: Record<string, string> = {
  // ... existing mappings ...

  // Add your migration here
  "old-icon-name": "new-icon-name",
};

Example:

// Rename bwi-question-circle to bwi-help
"question-circle": "help",

// Rename bwi-spinner to bwi-loading
"spinner": "loading",

Note: Do not include the bwi- prefix—the script adds it automatically.

2. Preview the changes (recommended)

Run the migration script in dry-run mode to see what will be changed:

npm run icons:migrate -- --dry-run

This shows you all files and occurrences that will be updated without actually modifying anything.

3. Run the migration

Once you've verified the preview, run the actual migration:

npm run icons:migrate

4. Review the migration report

After migration completes, check scripts/material-icons/migration-report.json for a detailed report of all changes:

[
  {
    "file": "apps/web/src/app/components/icon.component.html",
    "oldName": "bwi-question-circle",
    "newName": "bwi-help",
    "occurrences": 3
  }
  // ... more entries
]

What Gets Updated

The migration script searches and replaces icon names in:

  • TypeScript files (.ts)
  • HTML templates (.html)
  • SCSS/CSS files (.scss, .css)
  • Markdown documentation (.md, .mdx)

In the following directories:

  • apps/
  • libs/
  • bitwarden_license/

Excluding build/cache directories like node_modules, dist, .git, etc.

Migration Workflow Example

Complete workflow for renaming an icon:

# 1. Add mapping to migration-map.ts
# "spinner": "loading"

# 2. Preview changes
npm run icons:migrate -- --dry-run

# 3. Run migration
npm run icons:migrate

# 4. Review migration-report.json

# 5. Commit the changes
git add .
git commit -m "Migrate bwi-spinner to bwi-loading"

File Structure

scripts/material-icons/
├── build-with-bwi-names.ts          # Main build script
├── migrate-icon-names.ts            # Migration script for bulk renames
├── migration-map.ts                 # Configuration for migration
├── migration-report.json            # Generated migration report
└── README.md                        # This file

libs/assets/src/material-icons/
├── help.svg                         # Figma-exported SVG files
├── star-filled.svg
└── ... (all source SVG files)

libs/angular/src/scss/bwicons/
├── fonts/
│   ├── bwi-font.woff2              # Generated font files
│   ├── bwi-font.woff
│   ├── bwi-font.ttf
│   └── bwi-font.svg
└── styles/
    └── style.scss                   # Generated SCSS with icon mappings

libs/components/src/
├── shared/
│   └── icon.ts                      # TypeScript icon types
└── stories/icons/
    └── icon-data.ts                 # Storybook documentation

Icon Naming Conventions

The icon system uses a direct naming approach: the SVG filename becomes the CSS class name (with bwi- prefix added automatically).

Naming Guidelines

  • Use kebab-case: star-filled.svg, not starFilled.svg or star_filled.svg
  • Be descriptive: Choose names that clearly indicate the icon's purpose
  • Follow Figma: Use names from the Figma design system when possible
  • Consider usage: The filename determines how developers reference the icon

Examples

SVG Filename Generated CSS Class Usage Example
help.svg .bwi-help Help/question icons
star-filled.svg .bwi-star-filled Filled star for favorites
add-circle.svg .bwi-add-circle Add button with circle background
arrow-filled-down.svg .bwi-arrow-filled-down Dropdown indicators
visibility-off.svg .bwi-visibility-off Hide password toggle

Legacy Mappings

Some icons have legacy mappings documented in migration-map.ts for historical reference. For example:

  • bwi-question-circle was migrated to bwi-help
  • bwi-spinner was migrated to bwi-loading
  • bwi-plus was migrated to bwi-add

These mappings are only relevant if you're running migrations. New icons don't need any mappings.

Troubleshooting

Icon not appearing after build

  • Verify the SVG file is in libs/assets/src/material-icons/
  • Check that your SVG filename uses kebab-case and has the .svg extension
  • Run npm run icons:build again
  • Clear browser cache

Wrong icon displaying

  • Verify the SVG filename matches what you expect (it becomes the CSS class)
  • Ensure you're using the correct bwi- class name in your component
  • Check for duplicate SVG files with similar names

Font not updating

  • Delete the generated font files and rebuild: 
    rm libs/angular/src/scss/bwicons/fonts/bwi-font.*
npm run icons:build

TypeScript errors

  • Ensure you added the icon to libs/components/src/shared/icon.ts
  • Check that the icon name format matches: bwi-icon-name

Advanced Usage

Icon Sizing Classes

Available utility classes (defined in style.scss):

  • .bwi - Base class (required)
  • .bwi-sm - Small (0.875em)
  • .bwi-lg - Large (~1.33em)
  • .bwi-2x - 2x size
  • .bwi-3x - 3x size
  • .bwi-4x - 4x size
  • .bwi-fw - Fixed width (~1.3em)

Rotation & Animation

  • .bwi-rotate-270 - Rotate 270 degrees
  • .bwi-spin - Animated spinning (for loading spinners)

Example Usage

<!-- Basic icon -->
<i class="bwi bwi-help"></i>

<!-- Large icon -->
<i class="bwi bwi-help bwi-lg"></i>

<!-- Fixed width icon (useful in lists) -->
<i class="bwi bwi-help bwi-fw"></i>

<!-- Spinning icon -->
<i class="bwi bwi-loading bwi-spin"></i>

Best Practices

  1. Icon Consistency: Follow the existing Figma design system naming
  2. Semantic Naming: Use descriptive filenames that clearly indicate the icon's purpose
  3. Documentation: Always add usage guidelines to Storybook
  4. Accessibility: Include proper ARIA labels when using icons without text
  5. SVG Optimization: Export from Figma with strokes outlined
  6. Testing: Verify icons in Storybook before committing

Resources

Support

For questions or issues:

  • Check the troubleshooting section above
  • Review existing icons in libs/assets/src/material-icons/
  • Consult the design team for icon naming conventions
Reference in New Issue View Git Blame Copy Permalink