Blade Codicons Laravel Package

Product Decisions This Supports

• Build vs. buy on icon plumbing (~1–2 engineering days reclaimed). The alternative is hand-curating SVGs, writing per-icon Blade components, and maintaining a sprite build step. Adopting codeat3/blade-codicons collapses that into one composer line, with roughly 700 MIT-licensed Codicon glyphs exposed as <x-codicon-* /> components. This is a maintenance-cost trade, not a capability acquisition — judge it on opportunity cost only, and do not let it appear on a roadmap as a "feature."

• Feature unblocking: shipping developer-tooling surfaces without design-system debt. A CI/log viewer, observability panel, admin console, or internal ops dashboard needs a broad, consistent icon vocabulary immediately. This package lets a feature team ship icons in an afternoon instead of opening a design-system ticket and waiting a sprint. It supports the explicit decision: accept a commodity icon source for internal surfaces, so design cycles go to brand-facing work.

• Segmentation: an icon-language boundary per surface, owned deliberately. Codicons read as native in tool-like UIs (file trees, diff views, terminals, code review) and as borrowed on consumer or marketing pages. The product decision is to approve it for developer-facing and internal admin surfaces and exclude it from brand surfaces — and to write that line down rather than letting it drift screen by screen.

• Roadmap: Laravel 13 readiness as a checklist item, not a feature. The only substantive change in 1.35.0 is Laravel 13 compatibility (PR #51). For planning purposes that means this dependency will not be what stalls a framework upgrade. If Laravel 13 is on the roadmap, 1.35.0 is a prerequisite version, not an optional bump — verify at the same time that the constraint stays additive across Laravel 10/11/12 so the whole fleet isn't forced into a lockstep upgrade.

• Dependency classification: commodity, behind a wrapper. Single maintainer, auto-generated code, 1 star, zero public dependents, steady patch cadence. Classify accordingly: pin the version, route every usage through our own <x-icon name="..." /> alias, and take no roadmap dependency on it. The wrapper is the actual product decision — it converts a future vendor swap (Heroicons, Lucide, bespoke set) from an N-file refactor into a one-file change and preserves the exit path. It also absorbs the accessibility contract (decorative icons get aria-hidden, meaningful ones get a label), the 16px sizing scale, and the semantic name mapping (delete → trash, open → folder-opened) in a single file.

• Explicitly not supported: design-led differentiation. If icons are part of brand expression or art direction, ownership belongs to the design system, not the dependency list. Also out of scope: React/Vue/Inertia frontends (use the upstream Codicons npm package — this wrapper adds nothing there), and icon-dense, payload-sensitive public pages where inline SVG inflates HTML and a sprite or fragment-caching strategy is the better shape.

Scope note for the decision record: 1.35.0 is compatibility-only — no new icons, no API changes, no deprecations, no breaking changes. It does not change the adoption calculus; it confirms the package remains viable on the current framework major.

When to Consider This Package

Adopt when all of the following hold:

• The surface is developer-tooling or admin-style, where the VS Code icon language is an asset rather than a mismatch.
• The team is on — or migrating to — Laravel 12–13 and wants zero-effort Blade components rather than a custom icon component or a JS icon library.
• The requirement is MIT-licensed, static, inline SVG: no runtime JS, no icon font, no Vite/Tailwind/build-step coupling. Works identically in Blade layouts, Livewire views, and @included partials.
• Icon needs are coverage-driven, not design-driven — "give us the whole set, consistently," not "give us twenty icons we art-directed ourselves."
• We will accept single-maintainer risk and mitigate it cheaply: pin the version, enforce the local wrapper, add a framework-compatibility check to the Laravel upgrade runbook, and gate bumps with a CI smoke test that renders a component plus a test asserting every mapped icon name resolves.

Look elsewhere when:

• Design owns the icon set. Branded or art-directed systems belong in our design system, not an upstream package.
• The stack is not Laravel/Blade. In React/Vue/Inertia, use the upstream Codicons npm package directly.
• Risk tolerance is low. One star and zero dependents is a real signal about ecosystem validation. Behind a wrapper that is acceptable; as a load-bearing dependency with no exit path it is not.
• Icons fall outside the Codicon vocabulary. Coverage is fixed upstream — a missing glyph is a design decision or a Microsoft request, not a package PR. Keep a small local escape hatch rather than forking.
• Pages are icon-dense and payload-sensitive. Measure one real screen during the pilot; inline SVG across a 200-row table with three actions per row can add a six-figure byte count. If material, use a sprite strategy or fragment caching.
• Icons need to render in email. Inline SVG is stripped by most mail clients — x-icon will look fine in the browser preview and break in the inbox.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can add a complete, professionally drawn icon set to our internal dashboards and developer tooling for the cost of a single dependency and about a day of setup, instead of a sprint of design-system work. It is MIT-licensed, ships no JavaScript, and requires no vendor contract. The risk is that it is a one-maintainer, low-adoption package — which is exactly why we are wrapping it behind our own component so we can swap it out in one file if it ever stops being maintained. Recommendation: approve for internal and developer-facing surfaces only; exclude from brand-facing pages.

For engineering (the ask): composer require codeat3/blade-codicons:^1.35, no config, no assets, no build changes. In return, three non-negotiables:

1. No <x-codicon-*> in views. Everything goes through resources/views/components/icon.blade.php, which owns naming, sizing (16/32px grid), currentColor inheritance, and accessibility defaults (aria-hidden="true" focusable="false" when decorative, role="img" + aria-label when meaningful). This is what keeps the vendor swappable.
2. A semantic name map in config/icons.php, so product vocabulary (delete, open, branch) is decoupled from vendor vocabulary (trash, folder-opened, git-branch).
3. Pin the version and gate bumps in CI. A missing or renamed icon is a hard Blade render exception, not a blank box — so a smoke test and a "every mapped name renders" test are the difference between a caught rename and a production page down. Also ensure php artisan view:cache runs after composer install in the deploy pipeline; stale compiled views from vendor/ are the most likely confusing post-deploy failure.

Success criteria for the pilot: one admin surface migrated screen by screen (no data migration, no downtime, reversible per commit), a measured HTML payload delta on the densest screen, and the wrapper + name map + CI tests in place before icon #2 is written. If those three hold, expanding to the rest of the internal surface area is a low-risk, mechanical rollout.