Blade Microns Laravel Package

Product Decisions This Supports

• Build vs. buy vs. adopt on the icon layer. The real question is not "which glyphs do we like" but "do we hand-roll SVG components, license a paid set, or take a maintained Blade adapter?" This package is a thin adapter over blade-icons, so the commitment is to the delivery pattern (Blade component → inline SVG), not to Microns specifically. That makes the decision cheap and reversible — the right shape for a low-stakes infrastructure call.
• Scoping a UI-consistency feature. If the roadmap contains "polish the admin/dashboard," "clean up inconsistent iconography in settings and empty states," or similar, this is a near-zero-engineering, zero-license-cost input. Microns is monochrome, 1px-grid, utilitarian — correct for dense chrome (nav rails, toolbars, table actions, empty states), wrong for marketing surfaces.
• Design-system consolidation. Standardising on a single <x-icon name="..." /> primitive (wrapping <x-microns-*> once) removes per-feature SVG decisions and stops engineers hand-pasting markup. It converts "we should be consistent" into a codified, reviewable convention with one place to change sizes, colour tokens, and accessibility attributes.
• Roadmap sequencing for a swappable dependency. The same author ships parallel adapters (Heroicons, Tabler, Phosphor, etc.) on a shared base package. The icon family is therefore a replaceable dependency: ship Microns now, migrate later by changing one prefix in one file. This is a legitimate "make the reversible choice" call rather than a platform bet.
• Vendor / supply-chain risk review. Zero stars, zero dependents, single maintainer. That is a genuine PM-level input into "depend on this, or vendor the SVGs and own them?" The failure mode is favourable — an unknown component throws loudly at render, never corrupts data — so blast radius is small, but the answer may still be "vendor and own it."
• Framework-upgrade planning. Release 1.7.0 is a single change: Laravel 13 compatibility, no API or icon-set delta. That's a positive maintenance signal and a non-event for an upgrade track — routine pin-and-smoke-test territory, not a roadmap conversation. Caveat to verify in composer.json: whether the constraint was widened (safe for everyone) or replaced with ^13 (stranding Laravel 10–12 on 1.6.0).
• Accessibility and brand-consistency debt. Icon migrations are the most common source of icon-only buttons with no accessible name. Adopting a single primitive lets you bake aria-hidden="true" and a documented <span class="sr-only"> pattern into one file, turning an a11y risk into a solved-by-default.

When to Consider This Package

Adopt when:

• The surface is a Laravel Blade app (or a Blade shell with server-rendered chrome), and the UI is admin/dashboard/internal-tooling heavy — nav, tables, toolbars, status badges, empty states.
• You want consistency fast and have no appetite for building or maintaining an SVG component registry. There is no install command, no publish step, no asset pipeline — Composer plus auto-discovery and you're rendering icons.
• You are willing to wrap it once in a project-level <x-icon> primitive. That single seam is what makes adoption safe and makes exit a one-file edit.
• You accept the risk posture of a single-maintainer, zero-dependent package — and are prepared to write down the fork path (vendor the ~20 glyphs you actually use, register them with blade-icons directly).
• You have confirmed the artwork licence separately from the wrapper's MIT, especially if anything is customer-facing or the SVGs end up in compiled bundles.

Look elsewhere when:

• The product needs expressive iconography: marketing pages, hero imagery, duotone or two-tone treatments, brand marks. Microns is monochrome and utilitarian; forcing colour or flourish into it is the wrong tool.
• The frontend is predominantly React/Vue/SPA. A Blade wrapper inside a SPA shell creates two sources of truth and two migration problems — use upstream Microns components in the SPA instead.
• You already run a differently-prefixed icon package, or another codeat3/blade-* adapter, and don't intend to standardise on one primitive. Multiple families registering into the same x-* namespace will argue in the same templates.
• The org's procurement or supply-chain policy has a floor on maintainer count, dependents, or stars that this package does not clear. (Opportunity signal here is low at 33.74; treat this as a small, contained bet, not infrastructure you build a strategy on.)
• Pixel-perfect brand alignment demands a bespoke set. Then the right call is a custom icons directory registered directly with blade-icons — skip the adapter entirely.

Non-negotiable pre-checks before committing: read the illuminate/* and php constraints in the vendor manifest; ls the vendored SVG directory into a cheatsheet (there's no editor autocomplete for component names); confirm the microns prefix; pin the version and add it to the SBOM.

How to Pitch It (Stakeholders)

To executives — one paragraph: "We're standardising iconography across the admin and internal tooling on a small, MIT-licensed Laravel package. It costs nothing to license, takes hours not weeks to adopt, and reduces visual inconsistency and accessibility gaps in one move. The risk is deliberately contained: it's a thin adapter we wrap in a single component, so if we ever want a different icon family or to own the artwork ourselves, that's a one-file change with no template rewrite. I'd rather make that reversible choice now than let icon decisions keep accumulating per-feature."

To engineering — the substance:

• It's a thin wrapper over blade-icons; the actual dependency to evaluate is the base package and the SVG artwork, not this adapter. Rendering is fully server-side, so it composes cleanly with Livewire and Blade class components.
• Day-one task is not sprinkling <x-microns-*> through views. It's building one <x-icon name="..." /> primitive that centralises size defaults, aria-hidden, and colour tokens — and makes migration a prefix change.
• Failure mode is good: a missing or renamed component throws at render, loud and local. Keep icon names in a config or enum map, not inline in templates, and add a test that renders every name in the nav and status maps.
• Sizing and colour are plain HTML/Tailwind (class="h-4 w-4 text-gray-500"), inheriting currentColor. Don't set fill directly; it fights hover states.
• Watch two things: (1) the illuminate/* constraint in 1.7.0 — widened vs. narrowed determines whether Laravel 10–12 teams still get fixes; (2) inline SVG duplication in dense tables — measure HTML weight and switch to a sprite if a 200-row view with three icons per row regresses payload.
• Ops: ensure view:clear runs in deploy so renamed components aren't served from stale compiled views; confirm behaviour on read-only filesystems.
• Budget a light review at each Laravel major and each upstream icon re-sync — a resync can change SVG paths with no API change. A visual regression test over ~20 representative icons catches it for almost nothing.

The honest caveat to state up front: zero stars, zero dependents, single maintainer. We mitigate by pinning, wrapping, documenting the fork path, and verifying the artwork licence independently of the MIT wrapper. If any of those mitigations are unacceptable to the org, the fallback — vendoring the specific SVGs we use and registering them with blade-icons ourselves — is genuinely cheap, and that's the point: we're not locked in either way.