Spirit Web Twig Bundle Laravel Package

Product Decisions This Supports

• Design-system standardization: Decide whether Spirit becomes the UI foundation for any Twig-rendered surface in the estate. This bundle is the rendering layer that makes that decision actionable for Symfony teams, converting a design-system policy into reusable component markup rather than a style guide nobody follows.

• Build vs. borrow for UI primitives: The bundle supplies Spirit-styled Twig components under MIT, so the comparison is not "buy vs. build" but "borrow vs. build." For buttons, form fields, alerts, cards, and modals, borrowing saves sprint time — but only on a Twig stack. On Laravel/Blade the borrow value collapses to copying markup, and the bundle itself adds no leverage.

• Framework-boundary scoping: A PM decision this package forces into the open: is the product surface Twig-first or Blade-first? That is a product/architecture call, not a technical detail, because it determines whether design-system investment is portable across the portfolio or siloed per framework. Treat any Spirit adoption as two tracks — a Twig track that can consume this bundle, and a Blade track that consumes @lmc-eu/spirit-web directly with hand-authored partials.

• Roadmap prioritization for design-system migration: With one star and zero dependents, this is a pilot or back-office candidate, not a platform bet. Fund it as a time-boxed spike in a single low-risk surface, with an explicit success criterion (component parity, accessibility pass) and an explicit kill criterion (upstream stalls, version drift emerges).

• Use-case fit: Strong for Symfony admin panels, internal tools, and back-office apps where consistency and accessibility matter more than ecosystem size. Poor for Blade/Livewire-heavy Laravel products, where twigbridge would add a second template engine to the mental model for marginal gain.

• Risk posture on dependency health: Low adoption means the product team, not a vendor, owns continuity. That is acceptable for a class-name/markup contract that can be vendored or forked; it is not acceptable in the request-rendering path of a customer-facing product without an internal ownership plan.

• Accessibility and brand commitments: Spirit's custom elements carry ARIA and focus-management behavior in the JS layer. Adopting the design system (with or without this bundle) is the cheapest credible path to WCAG-oriented components — but the accessibility contract lives in the front-end package, so that is where the commitment should be anchored.

• Design-dev handoff efficiency: Reduces transcription drift between the design system docs and shipped templates. This is a real but modest productivity lever — worth measuring in the pilot, not worth assuming.

When to Consider This Package

Consider it when:

• The consuming application is genuinely Symfony 6/7 with Twig 3, and the team already uses or has approved the Spirit Design System. Without both conditions, the bundle delivers nothing that copying markup from the docs would not.
• You are building internal tools, admin panels, or back-office surfaces where visual consistency and accessibility outweigh ecosystem size and long-term vendor confidence.
• You want low procurement friction — MIT license, no commercial negotiation, full control over a small code surface.
• The alternative is building comparable components from scratch and the team can absorb the support risk of a thinly adopted dependency.
• You are running an explicit pilot and can isolate the bundle behind your own component conventions, so a stalled upstream is a contained problem rather than a migration.

Look elsewhere when:

• The product is Laravel/Blade-first. This is a Symfony bundle; it cannot boot in Laravel, and reconstructing its extension registration and asset paths via twigbridge costs more than porting four to six components to Blade partials.
• You need a large, actively maintained component ecosystem, broad third-party adoption, documented release cadence, or a vendor escalation path. None of those exist here.
• The organization has not standardized on Spirit. Adopting the bundle without the design system creates coupling to an upstream roadmap you do not control and adds design-governance overhead for no consistency payoff.
• You require version-cadence evidence before committing — no observable release history across multiple minor versions means no basis for a production dependency.
• Your asset pipeline is Vite or another non-Symfony convention. Asset resolution is precisely where bundle assumptions leak, and you should not spend engineering time fighting it for a UI helper layer.

How to Pitch It (Stakeholders)

For executives: This is a free, MIT-licensed way to test whether standardized UI components reduce repeated build work and improve brand and accessibility consistency. The underlying design system is credible — it comes from a media company's active design-system team — but this specific integration package has essentially no adoption: one star, zero dependents. That means we would be the maintainer if upstream goes quiet. The recommendation is a bounded pilot in one low-risk, Twig-based surface with a defined success metric and a defined exit, not a platform-wide commitment. Cost is measured in days of engineering, not license fees; the risk is continuity, not spend.

For engineering: This is a Symfony bundle that registers a Twig extension and template namespace for Spirit's web components. It is not Laravel-native — there is no service provider, no publishable config, no Blade directives. It also does not ship the CSS/JS; you pair it with @lmc-eu/spirit-web through Encore, AssetMapper, or a CDN, and nothing renders correctly without the JS because these are custom elements. If we proceed, we wrap the bundle in our own Twig component layer so we can patch one file when its API shifts, and we pin the npm package version explicitly because the class contract and the Twig markup version independently and drift silently. Realistic integration effort: under a day for a Twig-fluent team; negative ROI for a Blade team. Preferred path for Laravel surfaces is the front-end package plus hand-ported Blade partials, using any Twig adoption elsewhere in the estate as the parity reference.

For design and product: The value here is enforcing Spirit patterns where Twig is already in use, closing the gap between design intent and shipped markup. Before we commit, we need to confirm three things: component coverage against what our roadmap actually requires, whether the accessibility contracts in the JS layer (focus management, ARIA wiring) survive our integration, and whether theming needs are met without forking. If the answers hold, this is a low-cost consistency win. If any of them is unclear, we should ship the design system decision first and defer the bundle until a Twig-first surface genuinely needs it.