Tomato Themes Laravel Package

Product Decisions This Supports

Build vs. buy for theme infrastructure — this is the clearest win. If the roadmap includes "customers can white-label / rebrand the admin UI," the default engineering instinct is to hand-roll view path resolution, asset publishing, and per-theme config. This package is that layer, pre-built, MIT-licensed, and installable in hours. The PM decision is to not spend a sprint on a solved, low-differentiation problem, and instead protect that sprint for whatever actually differentiates the product. Caveat: the "buy" here costs nothing in license but everything in dependency risk — see the adoption criteria.

Admin-surface roadmap sequencing. The package is a presentation-layer concern with low blast radius, which makes it a decoupling tool for sequencing. It lets the team ship a rebranded or second admin theme without touching core application code, meaning it can be scheduled independently of (and after) a Filament major upgrade rather than entangled with it. Useful when the roadmap has a "polish/rebrand the admin" item competing with substantive feature work for the same engineers.

Scope boundary for the theming feature — decide it now, in product terms. The package manages deployment themes (a fixed theme per environment or release), not runtime tenant-scoped themes. This distinction is the single most important product call: if "each customer sees their own branding" is on the roadmap, this package is roughly 20% of that feature, not the feature. Treating it as the latter is the failure mode that costs a quarter. If the requirement is genuinely "two or three curated themes we ship," the package covers it end to end.

Feature scoping for internal admin tooling vs. customer-facing surfaces. The support posture (community-only, no SLA, single maintainer, 1 star, zero dependents, last release May 2024) is acceptable for internal admin chrome and a blocker for customer-facing or regulated surfaces. This gives the PM a clean, defensible line to draw: internal yes, external no — without needing to relitigate it per request.

Governance as a product artifact. The adoption produces a governance question the PM owns, not engineering: who may add a theme, where theme assets live, how themes are reviewed. Budget half a day of documentation. The cheap insurance is a smoke test asserting a known theme marker renders — require the adopters to write it. This is a product-quality gate, not a technical nicety: without it, a patch release can silently rename a view namespace, themes fall back to defaults, and nobody notices until a demo.

Roadmap hedging / fork contingency as a scheduled decision. If theming becomes load-bearing, the decision to vendor a fork under our namespace must happen before customization, not after. From a PM lens, that is a roadmap item with a trigger condition, not a vague worry: "if we customize beyond configuration, we fork." Put the trigger in the backlog with an owner.

When to Consider This Package

Adopt when all of these hold:

• The stack is already Laravel 10/11 + Filament 3 + PHP 8.1+, ideally standardized on the TomatoPHP/Filament admin ecosystem. Architecturally, this package is a fit only there — it is a shallow presentation-layer plugin whose value depends on the host panel.
• Theme switching is a genuine, near-term product requirement — curated deployment themes, not speculative "maybe we'll want themes someday." Absent a real requirement, this is an unnecessary abstraction layer.
• The admin surface is internal or low-stakes. No vendor SLA, no security response commitment, single maintainer.
• Someone owns the review discipline the upstream changelog does not provide. v1.2.2's release notes are a bare changelog link — no summary, no migration notes, no labelled breaking changes. A patch bump conventionally implies backward compatibility, but that cannot be confirmed from metadata alone. Someone must read raw compare diffs.
• Budget exists for a spike: throwaway branch, staging panel, diff generated config and asset output, verify an existing custom theme renders identically before introducing a second theme.

Look elsewhere (or build) when any of these hold:

• Per-tenant / runtime theming is the requirement. This package handles deployment themes; tenant-scoped theming needs its own layer regardless. Don't buy this expecting it to grow into that.
• The frontend is already invested in a design-token system you don't want duplicated. Duplication here is a permanent tax.
• Headless/API-only service — no views to theme.
• Customer-facing or regulated admin surface. The support posture is disqualifying.
• The asset pipeline assumes Laravel Mix or direct public/ writes and your build is Vite. Unresolved, this turns an hours-long integration into an open-ended one — verify before committing.
• No documented extension point for custom themes and your requirements exceed configuration; you'd be forking from day one, which inverts the build-vs-buy economics entirely.

Before committing, get answers to four questions (these are the ones that change the decision, not the ones that are nice to know): Which Filament major does v1.2.2 pin, and does it resolve against our panel version (composer why-not)? Does the v1.2.2 diff touch published config keys, view namespaces, or asset manifest paths? Is the asset pipeline Vite-compatible? Is there a documented extension point, or must we fork?

If adopting: pin ^1.2 but commit composer.lock; add to Dependabot/Renovate with patch PRs auto-raised and manually reviewed only when the diff touches config, views, or assets; land in a PR isolated from any pending Filament upgrade (do the Filament upgrade first, then re-validate — coupling them makes failures unattributable); keep theme definitions in our repository, not the package's published directory.

How to Pitch It (Stakeholders)

To executives — one paragraph. We can ship a rebrandable admin interface without spending engineering time building theme infrastructure from scratch. It's MIT-licensed, installs in hours, and touches only presentation — no domain logic, no data, no queues. The trade-off is dependency risk: it's a single-maintainer community package with one star, zero known dependents, and a May 2024 last release whose notes are a bare changelog link. That makes it appropriate for internal admin tooling and inappropriate for anything customer-facing or regulated. The recommendation is a bounded spike on a staging branch — roughly a day of engineering — with a go/no-go before it enters the mainline. Cost of finding out is low; cost of assuming is a surprise rebrand outage.

To engineering — the framing they'll care about. It's a publish-and-configure job measured in hours, not sprints, on a greenfield Filament panel; a Laravel developer is productive in under a day because the concepts are idiomatic (published views, asset registration, panel plugin registration). The real cost isn't integration, it's review discipline: the upstream changelog gives us nothing, so someone has to read compare diffs. Three known failure modes to design against — silent breakage on a patch release (mitigate with a smoke test asserting a theme marker renders), asset-cache staleness after deploy (cache-busting plus deploy-time view:clear/asset rebuild), and version drift against Filament producing obscure container-binding errors at boot (pin, lock, and upgrade Filament first). Also note the ramp-up asymmetry: technical onboarding is fast; the governance work — who owns themes, where assets live, how they're reviewed — is the slower half and needs half a day of documentation. And if we end up customizing beyond configuration, the fork decision needs to be made before we customize, not after.

The honest bottom line for the room. This is a small, cheap, correctly-scoped tool for a narrow situation: internal Filament admin, curated deployment themes, a real near-term requirement. It is not the foundation of a white-label/multi-tenant theming feature, and it should not be sold internally as one. Adopt behind a spike, keep it off customer-facing surfaces, and write the smoke test.