Hi, thanks again for the thoughtful response.

I completely understand the preference for inline SVG in HTML. It’s explicit and works especially well in component-driven environments like React, where icons are encapsulated and reused without much structural cost.

In a server-rendered setup like ActiveAdmin, though, inline SVG can easily become duplicated across templates, and customization often requires overriding entire partials rather than swapping a single visual asset. When the same icon appears in multiple places, updating it means touching several templates. For downstream apps, replacing a single icon often implies copying or patching ERB, even if the change is purely visual.

What I’m proposing is not primarily about “CSS vs inline”, but about centralizing icon definitions and reducing duplication.

Concretely, the direction would be:

• keep all icons as canonical SVG files in one dedicated location
• generate a token layer from them (e.g. Tailwind v4 @theme custom properties)
• expose a small @utility layer to consume those tokens
• have templates reference stable icon classes instead of embedding raw SVG markup

A simplified example of this pattern:

@theme {
  --svgpack-icon-edit: url("data:image/svg+xml,...");
  --svgpack-icon-caret-down: url("data:image/svg+xml,...");
  /* ... */
}

@utility svgpack-* {
  --svgpack-image: --value(--svgpack-*);
}

@utility svgpack-mask {
  mask: var(--svgpack-image) center/contain no-repeat;
  background-color: currentColor;
  width: 1em;
  height: 1em;
}

@utility svgpack-bg {
  background: var(--svgpack-image) center/contain no-repeat;
  width: 1em;
  height: 1em;
}

Usage in templates:

<span class="svgpack-icon-edit svgpack-mask text-red-600" aria-hidden="true"></span>

With this structure:

• Icon definitions live in one place.
• Replacing an icon means swapping a single SVG file.
• Downstream apps can override a specific icon by redefining --svgpack-icon-* in their own theme layer, without patching ERB or JS.
• CSS-based use cases (e.g. form controls) remain naturally supported.

An important detail is that this pattern remains fully compatible with Tailwind v4’s CSS-first model and tree-shaking behavior.

Since icons are exposed as Tailwind utilities, only the utilities referenced in templates are emitted in the final CSS. Unused icons do not inflate the generated CSS, even if additional SVG files exist in the canonical icon source.

I’ve used this approach in other projects via a small CLI tool that extracts SVG files into Tailwind v4 tokens and utilities.

For reference, here is a runnable Tailwind Play example demonstrating the pattern:

https://play.tailwindcss.com/z4448csf2i

If this architectural direction seems reasonable, I can prepare a focused PR.