Statamic Font Awesome Laravel Package

Product Decisions This Supports

• Build vs. buy for the icon layer: Blade Icons turns "icons" from a design-system chore into a one-line Blade component (<x-icon name="..." />), so teams can ship a consistent icon set without building and maintaining their own SVG-inlining helper, sprite pipeline, or caching layer. The v2.2.0 addition of custom CSS classes on icon output removes the most common reason teams fork the package: you can now attach Tailwind/utility classes, state classes (text-red-500, group-hover:...), or your own BEM classes directly at the call site instead of wrapping every icon in an extra <span> or duplicating markup.
• Design-system and theming roadmap: Because styling is now a first-class parameter rather than an afterthought, "per-context icon styling" (size/color/hover/animation variants) can be planned as a config/CSS concern instead of a component API redesign. This supports decisions like standardizing on Tailwind or a token-based CSS system without an adapter layer.
• Feature scoping and use cases: Concrete product scenarios this unblocks — marketing pages with inline brand SVGs, admin dashboards with stateful nav icons, email-safe icon usage (inline SVG vs. sprites), and accessibility passes (decorative vs. labelled icons) — all expressible in Blade templates rather than in bespoke helper classes.
• Scope discipline / roadmap hygiene: A small, additive, backward-compatible release signals a stable dependency. That supports a "keep the icon layer thin" decision: resist building an in-house icon manager, and instead spend roadmap capacity on differentiating features.
• Adoption and migration decisions: No breaking changes here, so there's no forced upgrade work; custom classes can be rolled out incrementally, template by template, which lets you schedule the change as opportunistic cleanup rather than a dedicated migration epic.

When to Consider This Package

Adopt when:

• You're on Laravel and rendering SVG icons in Blade — the ergonomics (<x-icon name="heroicon-o-bell" />) are a genuine DX and consistency win over hand-copied SVG blobs.
• You want multiple icon sets (Heroicons, Font Awesome, custom brand sets) behind one naming convention, with per-set configuration rather than per-file imports.
• Your design system needs per-instance styling — v2.2.0's custom-classes support is the deciding factor if you previously needed wrapper elements or component forks to color/size icons contextually.
• You value inline SVG (CSS-controllable currentColor, no extra HTTP requests, no sprite-sheet build step) and want caching handled by the package rather than by your own pipeline.
• You want a low-maintenance, community-maintained dependency with an established release cadence and no breaking changes in this release.

Look elsewhere or build your own when:

• You need a full icon management UI / asset pipeline (upload, versioning, CDN delivery, per-icon analytics) — this is a rendering helper, not a DAM.
• You're not on Blade (API-only, Inertia/Vue/React front-ends) — you'd be paying for a templating integration you don't use; prefer an SVG component set for your JS framework.
• Your icons come from a runtime/remote source with per-request fetching or user-generated SVGs — sanitization and trust boundaries become your problem.
• You require guaranteed long-term vendor support (SLA, security backport commitments); a community package is a supply-chain consideration worth documenting.
• Your build already emits optimized SVG sprites and you have zero need for Blade-level composition — adding this creates two icon paths.

How to Pitch It (Stakeholders)

To executives: This is a small, low-risk dependency that standardizes how icons appear across the product. The latest release (v2.2.0) is a purely additive feature — you can now apply your own styling classes to any icon — so it improves design flexibility with no migration cost and no breaking changes. Net effect: less bespoke front-end plumbing, faster UI iteration, and continued low maintenance overhead. No budget ask; the decision is a "keep using it and adopt the new styling capability opportunistically" call.

To engineering: Upgrade is safe — the change adds an optional custom-classes parameter to icon rendering and preserves existing behavior. It removes the common workaround of wrapping icons in extra elements or forking the component just to apply Tailwind/state classes, which simplifies templates and reduces DOM noise. Recommend: bump the dependency, standardize the class-passing convention in the design-system docs, and use the change to delete any wrapper-span hacks currently in the codebase. Watch items: keep an eye on the package's maintenance cadence and pin versions; if we ever move icons out of Blade (e.g., into a JS component library), revisit whether this layer still earns its place.