Spirit Web Twig Bundle Laravel Package

Technical Evaluation

Architecture fit The package is a Symfony bundle, not a Laravel package. Everything it does is bound to Symfony kernel conventions — a Bundle subclass, a DI Extension, Twig namespace/path registration, and asset-resolution hints. There is no service provider, no publishable config, and no Blade surface. In a Laravel codebase this is a framework-boundary mismatch: the value proposition ("Spirit components available in Twig") is real, but Laravel does not supply the container bootstrapping that makes it true.

Critically, the bundle does not ship the design system itself. It emits markup — class names, modifier conventions, accessible attribute wiring — against a separately installed @lmc-eu/spirit-web front-end package. That means the actual asset — the HTML/CSS/JS contract — is portable to Laravel. Only the Twig convenience layer is not. As a TPM, that distinction is the whole decision: we would be adopting a markup contract, and the bundle is one of two possible delivery mechanisms for it.

Integration feasibility Two paths, and only one is credible for a Laravel product:

1. Symfony target — composer require plus bundle registration, then follow the design system docs. Low friction, but only applies if the consuming application is genuinely Symfony.
2. Laravel target — the bundle cannot boot. twigbridge can graft a Twig engine onto Laravel and register Twig extensions, but it does not emulate bundle bootstrapping; extension registration, template namespacing, and asset paths would all be reconstructed by hand, and the app would carry two template engines. The cheaper and more stable path is npm install @lmc-eu/spirit-web plus a small set of Blade partials mirroring the reference markup. We would copy maybe four to six components to validate, not reimplement a component library.

Technical risk Elevated, and driven almost entirely by adoption rather than code quality. One star and zero dependents means no community backstop, no third-party regression signal, and no observable commitment to a release cadence outside the maintainer's own roadmap. The scoring corroborates this: overall 6.2 with opportunity at 28.9 reads as "capability is real, strategic upside relative to integration cost is thin."

Secondary unknowns that materially affect the estimate:

• Undeclared or unverified PHP/Twig/Symfony version ranges, and whether Twig 3.x is mandatory.
• Whether the bundle ships or publishes assets, or only emits class names against an externally installed package.
• Whether this repository is actively released or extracted-and-parked from a larger internal monorepo.
• Whether JS-driven component behaviors (focus management, ARIA state) live in spirit-web behind an init layer the Twig bundle does not wrap.

Key questions

• What PHP, Twig, and Symfony ranges does composer.json declare? Is Twig 3.x mandatory?
• Does the bundle deliver assets, or assume we install spirit-web ourselves?
• Who owns Spirit upstream, and what is the deprecation policy for component class names?
• Which accessibility contracts live in the JS layer, and would a Blade port silently lose them?
• Is the target application Twig-first, or is this an attempt to force a Twig artifact into a Blade stack?

Recommendation: do not take a production dependency on this bundle in a Laravel codebase. Evaluate @lmc-eu/spirit-web on its own merits, and treat the bundle as relevant only where a genuine Symfony/Twig surface exists.

Integration Approach

Stack fit Strong for Symfony 6/7 + Twig 3. Weak-to-absent for Laravel + Blade. The decisive question is not "is this a good package" but "is the consuming application a Twig application." Every downstream decision follows from that answer, and the opportunity score suggests the answer is usually no.

Migration path

• Adopting Spirit as a design system: pilot the CSS/JS package directly in one low-risk Laravel surface, hand-porting four to six representative components (button, input, alert, card) to Blade partials. Measure divergence from upstream markup across one release cycle before expanding.
• Where a Twig environment already exists — a Symfony admin, a marketing site, a legacy portal — adopt the bundle there first and use its rendered output as the parity oracle for the Blade ports. This extracts real value from the bundle without betting the primary product on it.
• Avoid introducing twigbridge into Laravel solely to consume one component library. A second template engine in the mental model is a permanent tax for a marginal gain.

Compatibility Verify before committing: run composer require in a scratch Laravel project to surface Symfony polyfill conflicts; confirm asset delivery works under Vite rather than AssetMapper or Encore, since asset resolution is precisely where bundle assumptions leak; and check that the pinned spirit-web npm version matches the class names the Twig layer expects — these version independently and drift silently. If the bundle is used at all, pin both sides explicitly and treat the pairing as a tested tuple.

Sequencing

1. Ratify the design-system decision (Spirit vs. incumbent) — a product call, not a technical one, and the gate for everything below.
2. Prove the front-end package in a single Laravel surface via Blade partials.
3. Establish a version-pinning policy for spirit-web in package.json, and document the class-name contract we depend on.
4. Only if multiple Twig applications emerge, evaluate the bundle — and expect to fork it internally.
5. Defer bundle adoption until upstream release cadence is observable across at least two minor versions.

Operational Impact

Maintenance Assume we are the maintainer. With one star and zero dependents, no ecosystem absorbs upgrade pain. Budget a fork-to-internal-ownership plan from day one: vendor the package, or mirror the relevant Twig templates into our repo so a stalled upstream does not block a PHP or framework upgrade. Owning roughly a dozen markup templates is a tractable, bounded commitment; owning a dependency we cannot patch is not.

Support No vendor SLA. Support is GitHub issues on an OSS repository maintained by a media company's design system team, where our use case is peripheral to their internal priorities. There is no escalation path. That is acceptable for a CSS/class-name contract that we could reimplement from docs; it is not acceptable for a dependency sitting in the request-rendering path of a customer-facing application.

Scaling The templating layer scales trivially — it is compile-time markup generation and carries negligible runtime cost. The real payload is the CSS/JS bundle, so scaling reduces to standard asset strategy: hashed filenames, long-lived cache headers, CDN distribution. Note the consequence of forking: our asset pipeline diverges from upstream and we inherit responsibility for keeping class names current.

Failure modes

• Silent design drift — the npm package and the Twig markup are versioned independently; components render with stale classes and degrade visually without ever erroring.
• Framework upgrade lock — a Twig or Symfony major bump strands a pinned version; if forked, we absorb the port ourselves.
• Asset path breakage — bundle assumptions about asset resolution break after a Composer update outside a Symfony context.
• Abandonment — repository goes quiet, with no security patching and no compatibility work.
• Accessibility regression — hand-ported Blade components lose the ARIA and focus wiring the JS layer expects. This fails audits, not test suites, which makes it the most expensive failure mode to discover late.

Ramp-up For a Blade-native team the bundle imposes a Twig learning curve in exchange for markup that is documented upstream anyway — negative ROI. The recommended ramp to the underlying capability is under a day: install the front-end package, read the component reference, port partials, verify behavior. Reserve bundle-specific onboarding for teams already fluent in Symfony and Twig, where the marginal cost is near zero.

Overall: the design system is worth evaluating; this specific bundle is a low-signal, low-adoption artifact whose value is fully realizable through the front-end package alone. Gate any adoption on a documented upstream release cadence and an explicit product decision that the target stack is Twig-first.