Dark Mode Laravel Package

Product Decisions This Supports

• Build vs. buy on theming infrastructure. Dark mode is a small but cross-cutting concern touching Blade layouts, Livewire components, Alpine stores, and CSS. This package bundles the whole chain (root-class initialisation, persisted toggle state, event bus) so the team can stop re-implementing the same 150 lines in every project.
• Delivery of a user-facing dark mode feature without a design-system project. The included accessible toggle is built on Laravel UX UI and Icons components, meaning the feature can ship as part of an existing UI kit rollout rather than as a standalone accessibility initiative.
• Roadmap sequencing for "theme + preference persistence" work. Because the package handles session-persisted state and a dark-mode-toggled browser event, it can be the foundation for a broader theming roadmap item (light/dark/system, per-user preference, per-tenant branding) instead of a one-off ticket.
• Scope decisions on Livewire vs. Blade vs. Alpine surfaces. The release explicitly covers all three, which supports deciding where the toggle lives (full-page Blade layout, embedded Livewire component, or Alpine-driven client-only) without choosing a stack commitment up front.
• AI-assisted onboarding as a real cost lever. The Laravel Boost skill lets an agent wire the package into a codebase, which supports decisions about how much internal documentation and pairing time to budget for adoption across multiple apps.
• Accessibility compliance planning. Shipping an accessible toggle by default supports WCAG-related commitments and reduces the review burden for each new screen.

When to Consider This Package

Consider adoption when:

• The application is Laravel-based and already uses Blade and/or Livewire, with Alpine present or acceptable as a dependency.
• You need persisted user theme preference (session-level, per the release notes) rather than purely OS-driven prefers-color-scheme behaviour — this package covers the persistence path, so if you only ever want OS-default you may be over-buying.
• You are using Laravel UX UI and Icons components, or are willing to, since the accessible toggle is composed from them.
• You want the event and store contract (darkMode Alpine store, dark-mode-toggled browser event) standardised so analytics, third-party widgets, or chart libraries can react to theme changes.
• You are standardising across multiple Laravel applications and want one integration pattern rather than N bespoke ones.
• Your team uses AI coding assistants and values a first-party Boost skill for guided integration.

Look elsewhere or wait when:

• Maturity matters more than convenience. This is v0.1.0 — no prior assessment exists, no migration history, no evidence of a stable public API. Expect breaking changes to directive names, store shape, and event names. If theming is load-bearing for a large surface area, pin the version and be prepared to vendor it.
• You are on Vue, React, or Inertia-only front ends with no Blade/Alpine investment; the value proposition largely evaporates.
• You need server-persisted per-user preferences (database column, user profile setting). The release describes session-persisted state, so a database-backed preference layer is your own work.
• You need system as a third state or per-tenant/per-brand palettes — not mentioned, so assume it is out of scope.
• Your policy forbids depending on pre-1.0 third-party packages in production without a fork plan.

How to Pitch It (Stakeholders)

For executives: This is a small, focused package that removes a recurring piece of undifferentiated work — implementing dark mode — from every Laravel project we ship. It delivers an accessible toggle, remembered user preference, and a documented integration path, including an AI-assisted setup skill, which shortens time-to-first-screen for new apps. The commercial argument is consolidation, not capability: we could build this ourselves in a few days per project, but we would rebuild it repeatedly and inconsistently, and accessibility regressions would be ours to own. The caveat to state plainly is maturity — this is version 0.1.0, so treat it as an early-adopter dependency: adopt it in one or two lower-risk surfaces first, pin the version, and revisit once it reaches a stable release.

For engineering: The package gives you a @darkModeScripts Blade directive for setting and synchronising the root dark class, a ux.dark-mode::toggle Livewire component with session-persisted state, an Alpine darkMode store with a dark-mode-toggled browser event, and an accessible toggle composed from existing Laravel UX UI and Icons components. That means one integration contract instead of per-project variants, and a clean event surface for anything that needs to re-render on theme change. The trade-offs: it is v0.1.0 with no upgrade history, the persistence is session-scoped rather than database-backed, and it assumes Blade/Alpine/Livewire and the UX UI component set. Integration effort should be low — start with the Blade directive on the base layout, add the Livewire toggle where you already use Livewire, and rely on the Boost skill and the published installation docs to wire it up. Budget an explicit spike to confirm the store and event names are what you want to standardise on before multiple teams depend on them.