Blade Ikonate Laravel Package

Product Decisions This Supports

• It reframes "build vs. buy" as "buy vs. vendor." The honest decision isn't whether to commission an icon system or license a commercial set — those carry real cost and procurement cycles. It's whether to take a free MIT stroke-based set (Ikonate) delivered as Blade components, or drop the raw SVGs into resources/svg yourself. Both cost roughly an afternoon. The wrapper saves that afternoon; it does not entitle you to a design-system conversation.
• Roadmap velocity on server-rendered surfaces. Settings pages, admin panels, internal tools, onboarding flows, dashboards — these are exactly where icon work otherwise becomes "let's spin up an icon font" or "add an SVG sprite build step." Inline Blade SVG means no font, no JS bundle, no runtime fetch, no FOUC. That is a genuine unblocker for the surfaces that ship fastest and matter least politically.
• Scope control on the design system. Ikonate is a deliberately narrow set: one visual voice, one weight family, stroke-based 24px. Adopting it is a decision not to have solid/duotone/color variants. If product wants a filled "active" nav state or brand-illustrated empty states, this package cannot serve that — and saying so early prevents a design system from being quietly scoped up inside a feature ticket.
• Cost and exit are both near-zero, which is the actual product argument. Single Composer command, MIT license, no asset publishing, no build step, and a documented escape hatch (fork the vendored svg/ directory into your own registered set with zero template edits if you wrap it properly). That combination is what makes this a team-level decision that doesn't need architecture review.
• Feature-level use cases it directly enables: nav and sidebar iconography driven from a config array, action buttons (download, export, delete, search), empty and error states, table row affordances, status badges where a color change on the parent drives icon color via currentColor.
• It forces a worthwhile accessibility decision early. Because these render bare <svg> elements, someone has to decide decorative (aria-hidden) vs. meaningful (role="img" + aria-label) — and the right place for that decision is a wrapper component you own, not 400 call sites.
• Explicitly out of scope, and worth recording as such: HTML email and PDF generation. Inline SVG is stripped or mangled by Gmail-class clients and renders inconsistently through DomPDF/Snappy. Any roadmap item that assumes "reuse the icons in the onboarding email" is a trap, and the docs say so.

When to Consider This Package

Adopt when:

• The stack is Laravel/Blade and you're already comfortable with blade-ui-kit/blade-icons being in the dependency tree. The wrapper is thin; the base package carries nearly all the coupling.
• You need a small, consistent, stroke-based set for chrome-level UI — navigation, actions, status — not a bespoke illustration library.
• The team will actually do the two things that make this safe: (1) wrap it in a single in-house <x-ui.icon> component so no template names the vendor package, and (2) add a CI test that renders every icon name referenced in views, catching typos and upstream renames before production.
• You're willing to pin (~1.7.0), run php artisan icons:cache in the correct deploy order, and write down the vendoring contingency.
• Speed matters more than provenance. This is a one-afternoon adoption on a surface that is unlikely to differentiate the product.

Look elsewhere — or vendor the SVGs directly — when:

• Provenance or support matters at all. One star, zero dependents, a single maintainer, and a 1.7.0 changelog whose entire content is "Laravel 13 compatibility." That release is a "still alive" signal and a real upgrade unblocker, not a support commitment. If your org requires a maintenance SLA, vendor the SVGs yourself — you keep the exact same Blade ergonomics through blade-icons with no third-party in the path.
• You need visual variants — solid, duotone, two-tone, brand-colored, or multi-weight. Ikonate is a single-voice stroke set. Pairing a second set is possible but doubles the inconsistency risk.
• Icon density is high. Inline SVG at 300–500 rows per page is real HTML weight, and Livewire wire:model.live on an icon-heavy table re-renders the whole set per keystroke. The mitigations (icons:cache, a <symbol>/<use> sprite partial) are things you build, not features the package ships. Budget them.
• The design team has already picked a different set. The wrapper is commodity; the icon set is the actual decision. Don't let package convenience override a design choice.
• The path is customer-revenue-critical. An icon that fails to render throws SvgNotFound at render time. Keep this off any flow where a missing glyph stops someone from paying you.
• The output target is email or PDF. Different medium, different solution.

Sequencing note for the PM: land the wrapper component and the CI icon test before the second feature adopts the package. Retrofitting either is a template sweep; the wrapper especially is what converts a dependency risk into a one-file change.

How to Pitch It (Stakeholders)

For executives — one paragraph: We can add a consistent, customizable icon set to our Blade-rendered screens in a single afternoon, at zero license cost, with no new build tooling, no JavaScript payload, and no runtime dependency at render time. The decision is small and reversible: if the underlying package ever goes stale, we keep the icons (MIT-licensed SVGs) and drop the wrapper without touching a single template — provided we take the one precaution of routing all icons through our own component. It accelerates the unglamorous surfaces — admin, settings, internal tools — where polish is expected but differentiation isn't.

For engineering — the honest version: This is a thin, single-maintainer wrapper over blade-ui-kit/blade-icons that vendors the Ikonate SVG set and exposes it as <x-ikonate-*> components. Treat the svg/ directory in vendor/ as the contract, not the README — icon names come from upstream and can change between versions. Three non-negotiables: (1) every call site goes through an in-house <x-ui.icon> wrapper, so a fork is a config change rather than a find-and-replace; (2) a CI test renders every referenced icon name, because SvgNotFound throws at render time and a typo on a rarely-hit error page ships to production otherwise; (3) pin to ~1.7.0 and place php artisan icons:cache immediately after composer install --no-dev in the deploy script — before config publish, next to view:cache. Known sharp edges: Tailwind Preflight's svg { display: block } breaks inline alignment until you add inline-block align-text-bottom or use flex parents; verify whether stroke-width is set on the root or per-path before design promises variable weight; there are no solid/duotone variants and faking one with fill looks bad; and inline SVG inflates HTML on dense tables — measure before rewriting. Do not use these in email or PDF output.

The ask: Approve adoption for internal and chrome-level surfaces only, conditional on the wrapper component and CI icon test landing in the same PR. Named owner for the vendoring contingency, documented in the repo, before the second feature depends on it.