Blade Jam Icons Laravel Package

Product Decisions This Supports

• Laravel upgrade roadmap (the headline decision): Release 1.8.0 does exactly one thing — it confirms Laravel 13 compatibility, with no new icons, no API changes, and no deprecations. That makes this a line item on the upgrade checklist, not a feature in the backlog. The PM action is to mark the dependency "verified compatible" in the upgrade ticket so it stops being a suspected blocker, and to establish whether the constraint widens (a single version across the estate) or replaces older majors (a knowingly two-tier estate: 1.7.x on legacy, 1.8.x on Laravel 13).

• Build vs. buy for iconography: Icons are commodity UI assets. Hand-vendoring and maintaining SVGs is a recurring tax with zero product differentiation. Buying here costs one Composer line and is reversible in a single PR. Default answer: buy — unless the glyph vocabulary is brand-defining, in which case it belongs in the design system where the product team owns cadence.

• UI consistency as a delivery-velocity decision: One call style (<x-jam-alarm-clock />, or <x-dynamic-component :component="'jam-'.$item->icon" />) removes the "designer exports SVG → developer pastes markup" loop from every sprint that touches dashboards, admin tables, nav configs, empty states, or CMS-driven menus. That is a throughput gain, not a styling nicety.

• Dynamic, data-driven UI capability: Icon-per-record tables, menu config arrays, CMS-authored pages, and per-tenant navigation collapse into a one-line template concern. This unlocks product surface that is otherwise gated behind front-end asset plumbing.

• Dependency-register hygiene: A single-maintainer, 0-star, 0-dependent package entering the UI layer is a governance decision, not just a technical one. Recording it with an explicit trigger — "lags two Laravel majors behind → build-vs-buy review" — converts an unbounded risk into a scheduled checkpoint.

• Scoping decision: Approve for internal tooling, admin panels, and non-brand-critical UI. Hold brand-defining iconography inside the design system. Also approve the one non-negotiable engineering commitment: wrap it in an in-house <x-icon name="..." /> so the package is referenced in exactly one file and the exit path stays hours-scale.

When to Consider This Package

Consider it when:

• You are on Laravel 12 planning a 13 upgrade (or already on 13) and want one fewer suspect in the dependency graph — 1.8.0 is precisely that.
• Views are Blade-rendered, including Livewire. Icons are server-rendered markup with no JavaScript, and attribute passthrough (class, style) means Tailwind sizing and coloring work for free.
• Jam Icons' rounded, stroke-based style fits the product's visual language, and the set is stable enough that "no new icons" is acceptable.
• You are already in the blade-ui-kit/blade-icons ecosystem and want a consistent component API across icon sets.
• Blast radius if you swap later is low — i.e. you follow the one design commitment worth enforcing: wrap it in your own component so the package name appears in exactly one file.

Look elsewhere when:

• The front-end owns rendering — Inertia/React/Vue SPAs or API-only services. Icons belong in the JS bundle; a PHP dependency is pure cost.
• You need breadth or variants — duotone, filled, brand logos, rapid additions. Prefer blade-icons with multiple sets over stacking single-set wrappers.
• Icons are brand-critical or you need a controlled, proprietary glyph vocabulary — own the assets.
• Sprite-based or JS runtime delivery is required, or icon-dense views make per-icon inline SVG a payload problem worth measuring first.
• Solo-maintainer risk is unacceptable for the surface in question — fine for internal tooling, a flag for consumer-facing critical UI.
• You need proof of maintenance health — 1.8.0 proves the maintainer tracks framework releases; it proves nothing about issue latency or icon-set currency. Verify before deep adoption.

How to Pitch It (Stakeholders)

Executives (30 seconds): This is a free, small add-on that gives our Laravel app a single consistent set of UI icons, so designers and engineers stop passing SVG files around each sprint. The new release does one thing: confirms it works with the next Laravel version, which removes a possible blocker from our framework upgrade. No budget, no vendor contract, no added infrastructure. The only caveat is that it is maintained by one volunteer, so we deliberately scope it to internal and non-brand-critical screens — and if it ever goes stale, replacing it internally is measured in hours, not months.

Engineering leads: 1.8.0 is a compatibility-only release — no API change, no deprecations, no behavioral delta; a safe patch bump within the same major line. Three asks: (1) add it to the Laravel 13 upgrade ticket as verified-compatible and dry-run the constraint change against each app's lockfile first — resolution deadlock with the underlying blade-ui-kit/blade-icons dependency is the highest-probability failure and the cheapest to find early; (2) enforce an internal <x-icon> wrapper on day one and publish the config once for house defaults (size, aria-hidden, focusable="false"), so an icon-set swap is a single-file change and we don't accumulate hundreds of ad-hoc class strings — also note that class merging only happens in our wrapper, not on the vendor component, so keep sizing in exactly one place; (3) pin ^1.8 and log the single-maintainer bus factor with an explicit review trigger. The exit path is pre-approved, not improvised: the SVGs are static files, so vendoring or forking them internally is an hours-scale task. Two operational guardrails: set a fallback icon in config so a bad dynamic icon name degrades to a generic glyph instead of a production 500, and add one data-driven test that renders every icon value actually present in our database or config — that is the single highest-value test in this integration.