Blade Gravity Ui Icons Laravel Package

Product Decisions This Supports

• Design-system commitment, made enforceable. Adopting this package is the code-level ratification of a design decision — "our product looks like Gravity." It turns icon choice from taste into a reviewable convention, and eliminates the most common source of visual drift between squads (each one hand-pasting or borrowing a different set).

• Build vs. buy, and it's a genuinely cheap buy. The alternative is hand-maintaining an icons/ folder of copied SVG blobs, which is a permanent Figma-to-code tax with no owner and no changelog. Here the cost is one Composer line; the maintenance surface is effectively zero.

• Server-rendered vs. client-side icon strategy. This is a performance and SEO decision wearing a dependency's clothes. Icons ship inside the HTML payload — no JS bundle growth, no hydration cost, no late-loading layout shift. If the roadmap carries Core Web Vitals targets, this is a free point on the board. If we later move the front end to Vue/React via Inertia, this package stops applying to the app shell and we'd switch to the upstream @gravity-ui/icons JS package — worth flagging now, not at migration time.

• Accessibility posture. Every icon is decorative-by-default with no ARIA emitted, and color flows from currentColor. That means the accessible pattern (label the button, hide the icon) is easy to standardize once in a shared wrapper — a small engineering decision that closes a recurring audit finding.

• Roadmap / framework currency. 1.4.0 adds Laravel 13 compatibility, so the package tracks framework majors. That's the signal that matters for a dependency we'd carry across an upgrade cycle.

• Concrete use cases where it pays back fastest: internal admin dashboards and settings panes, data tables with per-row actions, navigation rails driven by config or CMS data, empty states, alerts and toasts. These are exactly the screens where dozens of icons appear and where inconsistency is most visible to users.

• White-label / multi-brand optionality. Prefix and default class are publishable config, and icons accept arbitrary attributes. Rebinding to a second icon set later is a wrapper-level change, not a find-and-replace across the codebase — provided we adopt the wrapper discipline up front.

When to Consider This Package

Adopt when: the surface is Laravel Blade (including Livewire views and the Inertia root template); the product has already chosen, or is actively converging on, the Gravity UI visual language; icon-heavy screens are on the roadmap; and the team is currently pasting raw <svg> or hand-maintaining icon partials. It's also a reasonable default for a new Laravel app that has no icon opinion yet and wants one cheaply.

Look elsewhere when:

• The front end is SPA-first. Vue/React templates can't consume Blade components. Reach for the upstream JS package instead.
• We need stroked or multi-color iconography. Gravity UI icons are filled paths; stroke-* and fill-none don't do anything useful, and forcing them is off the paved road.
• Brand-critical custom icons are the requirement. Copy them into our own registered SVG directory rather than fighting per-path CSS through a wrapper.
• Vendor policy bars zero-star, single-maintainer dependencies. This one has 0 stars, 0 dependents, one maintainer, and a largely automated release cadence. The blast radius is benign — MIT license, payload is just SVG files plus a ~50-line service provider — but the policy either allows it or doesn't.
• We need a design-org-backed set with a support contract. Blade Heroicons or Lucide-backed equivalents have more institutional weight, at the cost of a different visual language.

Mandatory guardrail if adopted: wrap the set once in a single design-system component and depend on that wrapper everywhere. It centralizes sizing, the aria-hidden default, and the allowed-name check for data-driven icons — and it's the seam that makes the vendor risk a non-event. The documented exit (copy resources/svg/, register the set in ~10 lines, composer remove) is roughly ten minutes of engineering. Do that before it's load-bearing, not after a missing icon on a Friday.

How to Pitch It (Stakeholders)

For executives: one line in composer.json replaces an ongoing manual chore of hand-copying icons into templates, and it makes our visual language consistent by construction rather than by reviewer vigilance. There is no JavaScript cost, no asset pipeline, and no vendor lock-in worth the name — the entire dependency is a folder of SVG files we could vendor in-house in under an hour. Cost: near zero. Risk: low and fully mitigated. Decision requested: approve the dependency and the one-page convention that all icon usage goes through a shared wrapper component.

For engineering: it's a thin wrapper over blade-ui-kit/blade-icons, so components, @svg, and the svg() helper all work, and php artisan icons:cache collapses per-request filesystem reads into one array lookup — worth adding to the deploy script unconditionally. Three things to get right on day one: build the <x-ui.icon> wrapper so sizing and accessibility aren't ad-hoc; validate user- or CMS-supplied icon names against an allowlist (an unvalidated :component string is an enumeration surface); and bake icons:clear && icons:cache into deploys, because the icon cache goes stale on every version bump and the symptom is silent — a wrong or missing icon renders nothing at all rather than throwing. Pin to ^1.4 and let the lock file do its job; don't chase patch releases unless a specific icon is needed.

Bottom line: a small, reversible, MIT-licensed bet that buys design consistency and removes a recurring manual task. The correct posture is adopt-with-a-wrapper, and keep the ten-minute vendor-in exit documented.