Vesper Laravel Package

Product Decisions This Supports

• White-label and multi-brand admin (the headline unlock). Theming is now configured per panel via $panel->plugin(VesperPlugin::make()->preset(...)->branding(...)->header(...)), so one codebase can ship distinct branded admin experiences to different panels — internal ops, customer portal, per-tenant instances. This moves "multi-brand admin" from a custom build to configuration.
• Per-tenant / per-plan branding on the roadmap. Because config is fluent and evaluated per panel, theming can be driven from runtime data (a tenant record, a plan tier) rather than a static file. Tiered branding becomes a shippable paid feature rather than an architecture project.
• Build vs. buy tilts further toward buy. The Preset contract plus AbstractPreset base class lets you express your brand as a class in your own codebase and register it with ->registerPreset(new MyPreset), instead of forking the package or copying ~520 lines of design tokens. Custom design intent without custom maintenance.
• Upgrade/maintenance economics. Presets and tokens now live in src/Theme and are never published. We stop carrying a large published config that goes stale, drifts from upstream, and conflicts on every release — a recurring cost removed from every future upgrade.
• Migration scoping decision. This is a breaking major (config/vesper/tokens.php and config/vesper/presets/*.php removed; Blade overrides and TopbarNavigation now read from the active plugin, not config('vesper.*')). But config-based theming survives as an optional fallback beneath fluent calls, so the real decision is when, not whether: migrate in one PR now, or ship on ^2.0 immediately with the fallback and set a hard deadline to remove published config.

When to Consider This Package

Adopt when:

• You're on Filament and need panel-level branding — name, eyebrow, mark, palette, fonts, layout and control tokens — without hand-rolling a theme layer.
• You run (or expect to run) more than one panel: multi-tenant, white-label, or separate staff/customer surfaces.
• You want a small, versioned design-token surface you override selectively (->tokens(['shared' => ['vs-control-radius' => '999px']])) rather than maintain a full theme fork.
• You need per-environment, per-tenant, or per-plan variation in branding without config-file churn.
• Specifically for v2: you accept moving settings from config/vesper.php into the PanelProvider. The retained fallback makes adoption incremental and low-risk.

Look elsewhere when:

• You need a fully bespoke design system or a non-Filament frontend — this is a panel theming layer, not a general-purpose design system.
• You're pinned to v1 with a heavily customized published config and no capacity to migrate. v1 keeps working, but you inherit exactly the maintenance burden this release was built to eliminate.
• Your dependency policy can't absorb a breaking major — pin ^1.0 and revisit.
• Branding is static forever and a one-off config edit is genuinely cheaper than adding and tracking a dependency.

How to Pitch It (Stakeholders)

Executives. v2 makes our admin UI brandable per panel from code instead of from a large static config file. That turns white-labeling — multiple branded admin experiences off a single codebase, and potentially per-tenant branding as a paid tier — from a custom build into configuration. It also deletes ~520 lines of theme code we would otherwise own and re-diff on every upgrade, lowering both maintenance spend and upgrade risk.

Engineering. The theming surface is now fluent on VesperPlugin — preset(), registerPreset(), branding(), header(), sidebar(), fonts(), colors(), tokens(), layout(), themeId(), themeAsset() — with presets as first-class classes behind a Preset contract and VesperPlugin::current() available for reads in views and Blade overrides. Presets and design tokens ship inside the package and are never published. config/vesper.php is now slim, optional, and acts as a fallback layered beneath fluent calls.

On the breaking change — be direct. This is a major version. config/vesper/tokens.php and config/vesper/presets/*.php are gone; Blade overrides and TopbarNavigation read branding/header/sidebar from the active plugin rather than config('vesper.*'). Mitigation is built in: config-based theming still works as an optional fallback, so we can move to ^2.0 immediately and migrate incrementally. Recommended plan — upgrade the dependency, move each panel's preset/branding/header/sidebar onto the plugin in the PanelProvider, delete the now-ignored presets and tokens keys, and audit any custom Blade overrides that still read config('vesper.*'). Scope it as a small, schedulable ticket, not a release blocker.

Ask. Approve the ^2.0 upgrade plus a contained migration ticket, and flag any near-term white-label or tenant-branding commitments — v2 is the enabler for those, and knowing the timeline determines whether migration happens this sprint or next.