Icons Laravel Package

Technical Evaluation

Architecture fit: orchid/icons is a presentation-layer dependency for Laravel/Blade, rendering SVG icons through a Blade component/helper with first-class coupling to the Orchid Platform admin UI (menu builders, form fields, table actions, layouts). It belongs in the admin UI concern of the application — never in domain, service, or shared platform code. It changes no architecture; it standardises a cosmetic, non-differentiating surface. Fit is strong inside an Orchid admin and weak-to-nil outside it; treat it as an admin-UI dependency, not an enterprise icon system.

Integration feasibility: High for a team already on Orchid: Composer require, Laravel auto-discovery, optional vendor:publish of config/assets, then a one-line Blade call (<x-icon name="tabler.home" /> or the helper) alongside the icon-picker field in Orchid forms. Low for non-Orchid Laravel apps unless we deliberately consume the raw SVG paths. A one-day spike on a real admin screen with real content is sufficient to validate install, render, sizing, currentColor inheritance, the picker field, and CSP behaviour. This is a config-and-styling workstream, not an engineering epic — it can ride alongside a dashboard rebuild or permissions rework rather than competing for a milestone.

Technical risk: Runtime complexity is low; adoption and longevity risk is high. Zero stars, zero dependents, score 0.3 means no external production validation of the API surface, release cadence, or maintenance intent. Concretely:

• Version drift against our pinned orchid/platform and Laravel/PHP constraints.
• Asset publishing in production caching/CDN setups — missing assets fail quietly.
• Licence clarity for the bundled sets (Font Awesome, Bootstrap Icons, Tabler each carry their own terms) — commercial redistribution must be confirmed before we ship them.
• CSP and SVG sanitisation — inline styles or unsanitised paths can violate policy or open injection surface.
• Accessibility semantics — decorative vs. semantic handling (aria-hidden, labelled icons) is unverified.
• Silent failure on unknown names — a bad identifier renders an empty <svg>, producing a blank gap that survives code review.

Decisive mitigation: reversibility. The value is portable SVG files behind one Blade call site. Exit is a sprint, not a migration. That asymmetry justifies a fast yes/no rather than a quarter of deliberation.

Key questions:

• Is the package actively maintained, and does it declare compatibility with our pinned Orchid, Laravel, and PHP versions?
• What licence applies to each bundled icon set, and does it permit commercial use and redistribution of the assets?
• What exactly is the Blade component and icon-picker API, and which path does asset publishing write to?
• Does it support accessible labels, aria-hidden for decorative use, and a visible fallback icon?
• Are SVGs sanitised, and do they render under our current CSP without inline-style violations?
• Should we vendor or fork the SVG set up front so upgrades are independent of upstream?
• What is the failure behaviour for an unknown icon name — silent blank or thrown error?
• Can the underlying SVGs be reused outside Orchid, or is the package unusable if we later build a customer-facing surface?

Integration Approach

Stack fit: Laravel + Blade + Orchid admin surfaces. Adopt it as the single source of truth for admin iconography — menu items, screen actions, table row actions, empty states, modal headers, status indicators. Do not introduce it into customer-facing frontends without design sign-off; the set is deliberately a quiet, single-weight line vocabulary for wayfinding, not brand expression. If the roadmap includes a brand-forward surface, that is a separate decision — and stretching this set to cover it reintroduces exactly the inconsistency we are removing.

Migration path:

1. Inventory — enumerate current icons: downloaded SVGs in resources/, existing sprites, any icon font or JS icon package in the admin bundle.
2. Map — build an old→new name table inside the wrapper, not at call sites.
3. Wrap — create one local Blade component (e.g. <x-admin-icon>) that every call site uses. The wrapper matters more than the source set; it is the thing that makes the swap cheap later and the place where naming, sizing, and fallbacks are normalised.
4. Pilot — one low-risk admin module, real content, visual regression check.
5. Publish & verify — assets published in the deploy pipeline, cache-busting confirmed, smoke test against published paths.
6. Incrementally replace existing icon usage, with visual diffs per screen. Remove the old sprite/font only after the last screen is migrated.

Compatibility: Pin the package version explicitly; verify orchid/platform major compatibility in the same PR. Run PHP/Laravel constraint checks in CI. Test asset publishing under production caching and CDN settings — not just locally. Normalise icon naming in the wrapper so upstream renames are absorbed in one place. Complete licence and CSP/SVG scrutiny in the same review pass as the technical spike, not as a follow-up; either can invalidate the whole adoption.

Sequencing:

1. Technical spike (one real admin screen) + licence + SVG/CSP/accessibility review — timeboxed to ~1 day.
2. Establish local wrapper component and an approved icon-name list.
3. Pilot one admin module; verify sizing, colour inheritance, screen-reader semantics, light/dark theming.
4. Wire asset publishing into the deploy pipeline plus a deploy smoke test for published assets, and a dev-only unknown-name check.
5. Measure asset weight and render impact; then decide adopt, vendor, or fork based on whether upstream signals improve from zero.
6. Document the exit path (direct SVG assets behind the same wrapper) before rollout completes, not after.

Operational Impact

Maintenance: Low code footprint, but maintenance risk is concentrated in a low-adoption upstream package. Assign a named internal owner; pin the version; track upstream releases; hold a small contingency to vendor or fork the SVG files — measured in days, not money, and worth stating out loud rather than discovering later. Treat the wrapper component as the long-term control point and upstream as replaceable supply, not a platform commitment. Because the sets are third-party (Font Awesome, Bootstrap Icons, Tabler), the real maintenance surface is the licence and asset provenance record, which should live in the repo next to the wrapper.

Support: Community-only, no SLA, no external validation of the API surface. Document the approved icon vocabulary and usage patterns internally so teams are not dependent on upstream responsiveness. Escalate licence or compatibility ambiguity before adoption rather than after. Practically: the team can support the wrapper; nobody can support the package.

Scaling: Static SVGs scale cheaply via CDN and browser caching; compute impact is negligible. Guard against icon-bundle growth — do not load unused icons into admin layouts, and keep the approved-name list curated rather than "add whatever the designer finds." Keep sizing and colour in CSS (currentColor, utility classes) so one icon works across admin themes and light/dark modes without duplicating assets. Because icons live behind a Blade call site, there is no new JS runtime, no icon font, and no build-step change — which is most of why the operational cost stays near zero.

Failure modes (each needs a cheap guard, because all of them fail silently):

Ramp-up: Effectively zero for any developer who has used Blade components — the learning curve is conventions, not tooling. The cost is in the one-time standardisation pass, not in ongoing developer education. Onboarding material should be one page: the wrapper component, the approved name list, the fallback rule, and where the licence record lives. Budget the ramp-up as a half-day of team communication plus one migrated screen as the worked example.

Verdict for planning purposes: A bounded, reversible sanctioned pilot with a named internal owner — not a platform commitment. Adopt behind a wrapper, pin it, smoke-test the assets, and keep the contingency to vendor the SVGs. The cost of deciding this week is lower than the cost of deliberating for a quarter.