Jedd Icons

Adding icons

Drop an SVG, add metadata, run one command.

Jedd Icons is built from source-of-truth SVGs in the repo. Adding an icon is easy and involves just three steps: drop the SVG, add metadata, run the build.

Drop the SVG

Save your file at icons/stroke/<name>.svg using kebab-case. Icons must fit inside a 24×24 viewBox and use strokes only (no fills on child elements). The canonical root attributes are:

<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"
     fill="none" stroke="currentColor" stroke-width="2"
     stroke-linecap="butt" stroke-linejoin="miter">
  <!-- geometry only: <path>, <circle>, <rect>, <line>, <polygon>, <polyline> -->
</svg>

Child elements should contain geometry attributes only (d, cx, r, points, …) — not presentation attributes like stroke or fill. Those are set on the root <svg> and inherited at render time so the color and strokeWidth props work.

If your SVGs have inline presentation attributes on child elements (common with design-tool exports), pnpm icons:clean strips them automatically and normalizes the root attributes.

Design rules

  • Stay inside the 24×24 viewBox with ~1px padding on each side.
  • Stroke-only — no fill on child elements.
  • Keep geometry flat: no <g> groups, <defs>, or <mask>. The parser is intentionally simple.
  • Keep the parts separate: export each part of the icon (e.g. a bookmark and the check inside it) as its own <path>, and don't merge them into one. Keep each continuous stroke in one path, though; splitting it would break its corners. The build merges paths when it generates the packages, so this only affects the source files.
  • Export without layer names (Figma's "Include 'id' attribute" off); pnpm icons:clean strips any ids anyway.
  • Export final coordinates: no rotated shapes (reset the rotation or flatten with ⌘E), no Repeat groups (they export as <use>), and no dash patterns (draw dashes as separate strokes). pnpm icons:check flags each of these.

Add metadata

Create icons/stroke/<name>.json next to the SVG. The required fields are $schema, contributors, tags, and categories:

{
  "$schema": "../../icon.schema.json",
  "contributors": ["yourname"],
  "tags": ["search-keyword-1", "search-keyword-2"],
  "categories": ["shapes"]
}

The full set of fields lives in icon.schema.json at the repo root. Useful optional fields:

{
  "aliases": [{ "name": "older-name" }],
  "deprecated": true,
  "deprecationReason": "Use new-name instead"
}

categories is an enum — valid values are listed in icon.schema.json.

Build everything

pnpm icons

This single command runs the full pipeline:

  1. icons:clean — normalizes root <svg> attributes and strips inline presentation attributes from child elements. It refuses to clean an icon whose group rotation or dash pattern it would drop, and names the layer to fix in the design tool.
  2. icons:check — checks the normalized SVGs and their metadata without changing them, and stops on problems such as transforms, dots too short for Safari, geometry outside the 1px margin, or metadata that doesn't match icon.schema.json.
  3. build — builds @jedd-icons/shared, generates the per-icon TS files, then builds @jedd-icons/core and @jedd-icons/react.
pnpm --filter www-docs dev

Open the gallery, search for your icon by name, and use the sliders to confirm the size / strokeWidth / color / absoluteStrokeWidth props behave.

Re-exporting existing icons

When you re-export icons that are already in the repo, check that the shipped geometry didn't move by accident:

pnpm icons:compare                 # every icon SVG changed since HEAD
pnpm icons:compare --ref main      # …or since another git ref
pnpm icons:compare --from ~/export # every SVG in an export folder

Each icon gets a verdict: identical (same bytes shipped), same geometry (reordered, reversed, or a <circle> instead of a path), restructured (same segments, split into strokes differently), or CHANGED, which lists the segments that moved and by how much.

Individual commands

CommandWhat it does
pnpm iconsFull pipeline: clean + check SVGs, then build all packages
pnpm icons:cleanNormalize source SVGs (strip inline attrs, set root defaults)
pnpm icons:checkCheck source SVGs without changing them; exits 1 on errors
pnpm icons:compareCompare re-exported SVGs with the committed icons
pnpm buildBuild all packages via Turbo
pnpm --filter @jedd-icons/react genRegenerate icon TS files only
pnpm --filter @jedd-icons/react buildBuild the React package
pnpm --filter @jedd-icons/react devWatch & rebuild on changes
pnpm --filter www-docs devRun the gallery / docs site
pnpm lintLint and format-check with Ultracite (Biome)
pnpm formatApply Ultracite lint and format fixes
pnpm testRun the Vitest suites
pnpm typecheckType-check every package
pnpm knipFind unused files, exports, and dependencies (run after a build)

Before opening a PR, pnpm icons:check, pnpm lint, pnpm test, pnpm typecheck, and pnpm knip should all pass — CI runs the same checks.

Changesets

If your change touches a published package (@jedd-icons/react or @jedd-icons/core), add a changeset so it lands in the changelog:

pnpm changeset

Pick the package(s), choose a bump level, and write a one-line summary — that summary becomes the public changelog line. Docs-only, chore, and internal-package changes don't need one.

While the project is on 0.x, breaking changes ride on a minor bump: patch for fixes (including redrawn icons), minor for new icons, features or breaking changes, major reserved for 1.0.0.