Blade Clarity Icons Laravel Package

Product Decisions This Supports

• Icon-system build-vs-buy: settles the recurring "vendor an SVG sprite, license an icon set, or commission custom art" debate in favor of a thin, MIT-licensed Composer dependency for any Blade-rendered surface. No procurement, no design-tooling spend, no asset pipeline to own.
• Design-system consistency across teams: <x-clarity-*> components track upstream Clarity naming, so feature teams stop inventing one-off SVGs and stop arguing over "where does this icon live and who maintains it" at every kickoff. This is the highest-leverage outcome — it converts a per-feature decision into a platform convention.
• Roadmap and platform-lifecycle planning: 1.11.0 is a Laravel 13 compatibility bump. That is the datapoint that lets you keep this dependency inside the upgrade path instead of scheduling a fork or replacement during the next major bump — provided you confirm the constraint widened rather than shifted.
• Scope triage across surfaces: strongest fit on internal, admin, and back-office screens where icons are decorative furniture at volume; weakest fit on brand-critical customer-facing pages where custom iconography is a differentiator rather than a solved problem.
• Accessibility convention-setting: adopting a wrapper forces one deliberate, central decision on aria-hidden vs. aria-label/<title> per icon. That is a product-quality decision worth making once, not per feature.
• Standardization sequencing: gives you a concrete pilot candidate (one internal surface) and a template for evaluating future UI dependencies — narrow scope, semantic wrapper, documented exit cost.

When to Consider This Package

Adopt when most of the following hold:

• The stack is Laravel + Blade, including Livewire or Inertia apps whose views still compile Blade components.
• The design language is Clarity-aligned, or Clarity's vocabulary is at minimum acceptable — this is a curated set, not a general-purpose icon framework.
• You want zero build-step icon management: no sprite pipeline, no per-icon imports, no manual component registration, no runtime JavaScript.
• You are on or moving to Laravel 13 (pin ^1.11); teams on Laravel 10–12 stay on ^1.10.
• Icon needs are broad but shallow — you want the catalog available and do not need per-icon weight, path, or duotone customization.

Look elsewhere when:

• You need a framework-agnostic solution — Vue/React/Svelte-first front ends, or a Blade-plus-heavy-SPA split. A raw SVG set or CDN is a better fit.
• You require active upstream curation, accessibility annotations, or a theming API. This is a faithful wrapper; its ceiling is VMware's Clarity set, not a design system you control.
• Your design system is not Clarity (Material, Carbon, a custom brand set). Unwinding a mismatched icon language costs more than it saves.
• You enforce a strict dependency-minimization policy for what is effectively static asset data. A checked-in sprite may be preferable.
• You need vendor support commitments or SLAs. One maintainer, zero recorded dependents, no commercial backing — acceptable for cosmetic UI assets, unacceptable for anything functionally critical.
• Adoption signal matters to you: 1 GitHub star and 0 dependents means minimal community validation. That does not make it wrong, but it means you are the de facto QA function. Budget accordingly.

How to Pitch It (Stakeholders)

To executives: This is a small, low-risk library that gives our Laravel product a consistent, professionally drawn icon set without spending design or engineering time sourcing and maintaining graphics. The 1.11.0 release adds Laravel 13 support, so adopting it now does not create upgrade debt at our next platform refresh — it removes a category of "our icons broke / our components are stale" work from that migration. Cost is one Composer dependency: no license fee, no infrastructure footprint, no external service, and no page-load penalty because icons render inline. Two caveats stated plainly: it is maintained by a single contributor, and we mitigate that by routing all usage through one wrapper component so it is replaceable in an afternoon.

To engineering: It is a Blade component wrapper over VMware's Clarity icon set. composer require, auto-discovery registers the provider, and <x-clarity-*> components are immediately available — no config publish, no migrations, no env vars, no asset build, no runtime JS. Treat ^1.11 as the constraint on Laravel 13; ^1.10 still serves older majors. The 1.11.0 change is a single compatibility PR — reportedly no new icons, no API changes, no deprecations — so verify the composer.json constraint widened rather than shifted and confirm the PHP floor (likely 8.3+) against our runtime matrix before rollout. Then run view:clear / view:cache on a non-production branch to surface component-resolution errors early, and do a visual regression pass watching SVG attributes and fill="currentColor" — that is the usual breakage class.

The de-risking move, stated once and treated as a delivery requirement: every template goes through a single semantic wrapper (<x-icon name="delete" />) rather than referencing <x-clarity-trash> directly. That wrapper decouples our views from the vendor's icon vocabulary, absorbs component renames, enforces consistent sizing and accessibility defaults, and makes a swap a contained change rather than a sprint. It also gives us the fallback path: the underlying SVGs are public, so forking or vendoring is a low-cost escape hatch if the package is abandoned. The worst realistic failure is not a broken icon — it is a Laravel major bump where this dependency has no compatible release and blocks the whole migration. The wrapper is planned insurance against exactly that.

Recommended next step: pilot on one internal or admin surface, confirm the Clarity vocabulary covers our needs, establish team conventions for sizing and accessibility alongside the wrapper, then standardize. Do not attempt multi-icon-set consolidation during the initial adoption.