SVG Icons and currentColor

Icons were hex six b seven two eight zero in the sprite. Body text used a muted text token. Rebrand changed the token. Text updated everywhere. Icons stayed gray from twenty nineteen because someone exported the sprite with hard-coded fills and nobody owned the asset pipeline. The design system documentation said icons inherit typography. Production proved otherwise every time a stakeholder opened settings on a dark theme and saw chrome that lagged the rest of the interface by one full identity refresh.

SVG icons are not miniature illustrations in a token-driven interface. They are glyphs. They inherit typographic color the way letters do. That inheritance path is currentColor, a CSS keyword that resolves to the computed color value on the element. Wire icons to currentColor, connect color to design tokens, and one variable update moves labels, captions, and icons together. Hard-code fill with a literal hex and you have created a second palette parallel to typography, guaranteed to drift the moment marketing warms neutrals or shifts accent hue. The maintenance cost shows up as grep archaeology and one-line overrides in product code that masked the drift for years.

How currentColor binds icons to typography

currentColor is a stand-in for the color property on the same element, or inherited from a parent if color is not set on the SVG itself. Set fill to currentColor on paths, set color on the interactive parent, and hover changes one property while icon and label move together. No fill-hover token. No duplicate state blocks targeting svg path.

<button class="btn-icon">
  <svg viewBox="0 0 24 24" aria-hidden="true">
    <path fill="currentColor" d="M12 4l8 8h-5v8H9v-8H4z"/>
  </svg>
  Upload
</button>

.btn-icon {
  color: var(--text-muted);
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
}
.btn-icon:hover {
  color: var(--accent);
}
.btn-icon:focus-visible {
  color: var(--accent);
  outline: 2px solid var(--focus-ring);
}

Three valid patterns recur in production codebases. Fill currentColor on each path works in sprites when use clones paths with inherited presentation attributes. Fill currentColor in CSS targeting svg or path centralizes control and eases per-variant overrides. Color on the SVG with fill currentColor on children helps when button text and icon need different colors, which should stay rare. Avoid setting currentColor on the root svg while hard-coding hex on child paths, because children win and you have only moved the hard-coding one level down.

Line icons from Heroicons outline, Feather, Phosphor regular, and similar sets use stroke, not fill. The clean pattern is fill none on the root, stroke currentColor on paths, with stroke-width and line caps set once in CSS. Some exports include both stroke and fill on the same path for anti-aliasing. Audit the source SVG rather than patching per icon in production stylesheets. If the export includes fill currentColor on a closed path that should be outline-only, fix the export script. Sprites magnify small mistakes into every instance.

Icons align with text cap height when sized in em. Width and height at one point two five em on the svg, flex-shrink zero, slight negative vertical-align, lets token-driven font-size on the parent scale icon and label together. Avoid fixed width twenty-four on production svg tags unless the icon stands alone without adjacent text.

Semantic tokens, variants, and theme behavior

Icons should consume semantic tokens, not primitive palette steps. Default UI chrome maps to muted text. Primary content maps to default text. Interactive accent maps to hover and focus on primary actions. Destructive, success, and disabled states map to their respective semantic roles. Component variants set color once. SVG internals stay dumb.

.icon-button {
  color: var(--text-muted);
}
.icon-button:hover:not(:disabled) {
  color: var(--text);
}
.icon-button--primary {
  color: var(--accent);
}
.icon-button--danger {
  color: var(--danger);
}
.icon-button:disabled {
  color: var(--text-disabled);
  cursor: not-allowed;
}

This matches how text color tokens propagate through typography. Icons are part of the type stack, not a separate illustration system. When tokens swap under data-theme dark or prefers-color-scheme, icons follow automatically if they use currentColor. Verify muted text on default surface still meets contrast for sixteen by sixteen pixel icons. WCAG treats essential icons like text. Sub-three to one muted grays on dark cards fail even when body copy passes at a larger size.

If your stack uses Tailwind v4 theme color variables, icon buttons become text-muted and hover:text-accent utilities. No parallel fill-gray-500 classes. The utility sets color. SVG paths use currentColor. One system, one review surface, one dark-mode matrix.

Semantic exceptions stay short and documented. An error alert may set color to danger on the warning icon wrapper while body copy stays on default text. A success toast may show a green check while message text remains neutral. A live recording dot must not inherit muted toolbar color. Pattern: wrapper sets semantic color, icon inside uses currentColor. Every semantic icon color is a token pair you contrast-test. If more than a dozen icons need fixed hues, your semantic token set is incomplete, not your icon library.

Multi-tone marks, sprites, and build discipline

Not every icon should be monochrome. Product logos, file-type badges, payment method marks, and status illustrations carry brand or semantic hues independent of text color. Mixing them into the currentColor sprite corrupts both systems. Maintain two libraries. UI icons are monochrome, currentColor, token-driven: navigation, actions, form controls. Brand and semantic illustrations use fixed palette or multi-stop fills. Load payment marks via img or inline SVG without color inheritance from parents. Do not use multi-tone symbols from the same sprite as UI icons unless each path group uses hard-coded fills and you accept no theme override.

Advanced cases can define fills as var references inside a single complex icon, useful for rating stars where empty and filled states share geometry. Keep that list short. Every custom variable inside SVG is a token you document and test in dark mode. Duotone sets like Phosphor use opacity layers where primary fill runs at full strength and secondary runs at twenty percent of currentColor. One token tints both layers. Verify contrast on surface when the secondary layer drops to near-invisible on dark backgrounds. Bump secondary opacity in dark mode if needed.

Sprite sheets reduce HTTP requests and guarantee consistency. Color discipline matters more at scale because one wrong fill poisons every instance. Inline sprites with use resolve currentColor on paths inside symbol against the using element’s computed color, the button, not the hidden sprite container. Set color on the interactive parent. External sprites historically had cross-origin and currentColor inheritance bugs in older browsers. Modern Chromium, Firefox, and Safari handle currentColor in external sprites when fills are set on symbol paths. Test your target browser matrix. If external sprites fail, inline the sprite in the app shell.

Automate icon ingestion so humans never hand-edit fills. SVGO or equivalent should convert black fills and strokes to currentColor. Reject icons that contain more than one distinct hex from the UI sprite pipeline and route them to brand assets. Normalize viewBox and strip width and height from source files so CSS controls size. Strip inline style attributes that set fill or stroke. Document the rule in the design system: designers export monochrome SVGs in black, the build converts to currentColor. Figma outline exports that use charcoal gray still convert. Any single hex becomes inherit.

Case study: the sprite that survived three rebrands

A mid-size SaaS company maintained a single SVG sprite with four hundred twelve UI icons, loaded once in the application shell and referenced across navigation, data tables, settings, and empty states. The sprite dated to a bootstrap era when a contractor exported from Sketch with fills baked to hex six b seven two eight zero because that was the gray in the style guide PDF. Components set color on buttons and links. Icons ignored it. Text tokens rebranded twice, from cool gray to warm gray to blue-tinted neutral. Accent shifted from cobalt to teal. Icons remained six b seven two eight zero because the sprite was treated as binary asset, not code.

The first symptom was subtle. Dark mode launch exposed icons that looked lighter than adjacent muted labels on charcoal cards, not because currentColor failed, but because hard-coded mid-gray sat wrong on every surface token. The second symptom was expensive. A accessibility audit flagged toolbar icon buttons that failed three to one against elevated surfaces. Body text on the same toolbar passed because it used updated tokens. Icons failed in silence until audit because nobody contrast-tested glyph fills separately from labels.

Engineering proposed a find-and-replace on the sprite file. Design proposed re-exporting from Figma manually. Both plans ignored multi-tone payment icons and file-type badges that had been mixed into the same directory because the repository had one icons folder and no pipeline gate. A week-long audit found thirty-seven multi-color assets in the UI sprite, fourteen icons with per-component CSS overrides like svg path fill important, and nine product screens that set icon color correctly on the parent but lost the cascade because child paths hard-coded fills with higher specificity.

The remediation split libraries first. UI sprite retained only monochrome geometry. Brand and payment marks moved to a separate static directory with explicit fills, loaded via img where theme inheritance was undesirable. SVGO batch conversion ran on the UI set with convertColors to currentColor and removal of stray attrs. A CI grep rejected new hex values in the UI sprite path. Component CSS that targeted svg path fill with literals was deleted in favor of parent color var tokens.

Visual regression covered navigation, forms, and empty states in light and dark themes. The diff was boring in the best way. Icons tracked labels on hover and focus without duplicate rules. The third rebrand, six months later, changed only token values in the root block. Icons updated automatically. Support tickets about inconsistent settings chrome dropped to zero. The team documented fewer than ten semantic exceptions: danger, success, live indicator, and a handful of marketing illustrations outside the product shell.

The lesson was organizational as much as technical. Icons are text you drew. Treating them as illustration assets exempt from token discipline creates a shadow palette that survives rebrands visually unchanged, which looks like stability but is actually debt. currentColor default plus automated ingestion plus a hard CI gate costs less than one emergency sprite rewrite per identity refresh.

Accessibility, migration, and what good looks like

Decorative icons paired with visible text should use aria-hidden true on the svg. When the icon is the only control label, provide aria-label or visually hidden text. Do not rely on color alone for icon meaning. Pair danger iconography with Delete text or an explicit aria-label. Focus rings belong on the button, not the path fill. Outline on the interactive element survives keyboard navigation audits that fill-based hacks fail.

Simulate deuteranopia on error and success icon pairs. Red-green collisions are the first failure mode when semantic exceptions multiply without contrast review. Migration from hard-coded fills starts with auditing the sprite for hex values, converting single-color icons via SVGO batch job, replacing component CSS that targets path fill with parent color tokens, splitting multi-tone assets out of the UI sprite, and running visual regression on high-traffic surfaces first. Expect one-line overrides in product code that masked drift. Those overrides were the symptom. Hard-coded fills were the disease.

Design handoff should treat monochrome icon exports the same way font files are treated: versioned inputs with a single conversion path. When designers paste optimized SVGs into Storybook stories with inline fills for preview convenience, those stories become copy-paste sources for production markup unless the build pipeline strips literals automatically. The same applies to icon fonts and ligature sets that bake color into glyphs. If your stack still ships an icon font for legacy reasons, map glyph color through CSS color on the element, not through a second set of utility classes that parallel text tokens.

Internationalization lengthens labels beside icons without changing icon size. German toolbar strings may wrap where English mockups showed one line. Icons that were contrast-tested only beside twelve-pixel English captions may sit next to longer copy on denser layouts. Leave margin in muted icon contrast during token definition rather than targeting the mathematical minimum beside the shortest label in the primary locale. Right-to-left layouts also expose alignment assumptions baked into negative vertical-align offsets tuned for Latin cap height. Re-verify optical alignment when direction changes, not because currentColor breaks, but because em-based sizing interacts with line-height and script metrics you did not test in the first pass.

One token update should change typography and icons together. Sprite ingestion should reject hard-coded hex. Brand colors should live in a separate asset bucket. Semantic reds and greens should appear on a checklist of fewer than ten components. Dark mode should not require a second sprite. For how text tokens are named and paired across themes, see Naming Color Tokens Semantically.

Icons are not a special color system. They are glyphs in the same semantic vocabulary as captions and labels. Treat currentColor as default, tokens as the only palette for UI chrome, and multi-tone as the exception that proves the rule. The sprite that survived three rebrands did so only after it stopped being a museum of twenty nineteen gray and started behaving like text.