Icons package — developer guide

Prerequisites

• Run all commands from the Stellar monorepo root.
• Figma personal access token: create one when you need it (tokens are time-limited, with a 90-day maximum). In your terminal, run export FIGMA_TOKEN=<token> for the current session, or prefix a single command with FIGMA_TOKEN=<token> ....

Default output locations for --type icon are defined in packages/icons/scripts/config.ts:

• SVG: packages/icons/data/generated/icons
• Components: packages/icons/src/generated/components

Stellar icons — generate-new

generate-new uses @figma-export from the frames you point at. Optional flags — omit --figmaNodeId1x and/or --figmaNodeIdBold if you are not exporting those frames.

pnpm --filter @snowflake/stellar-icons generate-new \
  -- \
  --type icon \
  --figmaFileId XFYuFXmNOng6nzjMQd2vgW \
  --figmaNodeId 0-1 \
  --figmaNodeId1x 270-905 \
  --figmaNodeIdBold 2453-589

Caveat: generate-new resets packages/icons/src/generated/components/index.ts from git before appending exports. Commit or stash any manual edits to that file first, or they will be lost.

Pictograms and illustrations

Pictograms

FIGMA_FILE_ID=2c8HSUHe7XW8QONUREZ96o pnpm --filter @snowflake/stellar-icons update-svg -- --type=pictogram
pnpm --filter @snowflake/stellar-icons generate-components -- --type=pictogram

Illustrations

FIGMA_FILE_ID=Q6Sg1b2wpaza7BO4ZcPf9F pnpm --filter @snowflake/stellar-icons update-svg -- --type=illustration
pnpm --filter @snowflake/stellar-icons generate-components -- --type=illustration

After you generate

1. Review the diff (new/changed SVGs, .tsx files, icon-metadata.json, index.ts).
2. Commit the generated assets. Lint-staged may run oxfmt on commit.
3. Update screenshot baselines — new or regenerated icons will cause snapshot test failures in CI.
   • Recommended: Open your PR using the Stellar generate-pull-request Cursor skill — it automatically detects changes to packages/icons/ and adds the update-snapshots label. CI will regenerate and commit the baselines for you.
   • Alternatively, add the update-snapshots label manually to your PR. CI will regenerate and commit the baselines automatically.
   • If you need to run baselines locally (e.g. to verify before pushing): use the same Docker environment as CI — running on macOS produces different font rendering and the results won't match:

     pnpm --filter site test:browser:update

     Commit the updated snapshot files this produces.
4. Open a PR. Release Stellar as usual; consumers get the new icons only after they upgrade the published icons package version.

Badge illustrations

Design source: Badge illustration export.

The scripts/config.ts only registers icon, pictogram, and illustration. There is no --type badge entry today, so badge generation is not yet supported.

Figma files (reference)

• Stellar icons: https://www.figma.com/design/XFYuFXmNOng6nzjMQd2vgW
• Badge illustrations: https://www.figma.com/design/XKmJ83LQkDEFLu93Q9FC8B/Badge-illustration-export
• Pictograms: https://www.figma.com/design/2c8HSUHe7XW8QONUREZ96o (Balto Illustrations)
• Illustrations: https://www.figma.com/design/Q6Sg1b2wpaza7BO4ZcPf9F/Illustration-Export

Custom icon packages

For generating icons into another package (custom svgDir, template, etc.), pass --svgDir, --componentDir, and --componentTemplate flags to generate-components:

pnpm --filter @snowflake/stellar-icons generate-components \
  -- \
  --type icon \
  --svgDir packages/my-icons/src/svg \
  --componentDir packages/my-icons/src/components \
  --componentTemplate packages/my-icons/config/IconWrapper.js