Shout Laravel Package

Technical Evaluation

Architecture fit

• Shout is a pure presentational Filament schema component (Awcodes\Shout\Components\Shout), not a persistent field. It is dropped into the schema() array of forms and infolists alongside TextInput or Section. No domain model change, no migrations, no routes, no service container bindings we must configure, no queue or event surface. Server-side footprint is one Blade view plus a thin PHP class — the lowest-blast-radius category of dependency.
• It fits cleanly if we are already Filament-first for admin. It offers nothing outside Filament: no public-page, email, or API rendering.
• Composition is richer than "a placeholder": heading(), content(), color() (Filament Color object or hex), icon()/iconSize()/icon(false), and actions() accepting real Filament Action objects. That last one matters — the notice can carry a CTA, which means it can host deprecation warnings with an "upgrade" link, compliance copy next to a PII field, or trial-expiry prompts with a "manage billing" action, in context rather than as a global banner.
• Be honest about what we are buying: this is a design-system primitive, not a capability. Every behaviour listed is reproducible with a Filament Placeholder/custom view plus ~20 lines of Blad. The adoption case is consistency (one notice style across all panels), dark-mode correctness handled upstream, and zero maintenance of that partial — not functionality we cannot otherwise get.

Integration feasibility

• composer require awcodes/shout, then include the component. The real gate is theming: the README requires a custom Filament theme and an @source '../../../../vendor/awcodes/shout/resources/**/*.blade.php' line in the theme CSS (Tailwind v4 CSS-first syntax). If our panels rely on Filament's precompiled default CSS, notices will render unstyled until we stand up a custom theme build. That is the single largest integration precondition and should be scoped as such.
• The 4.x line supports Filament 4 and 5 on one constraint (v4.1.0). That is a good forward path and reduces the upgrade tax to one package major bump per Filament major.

Technical risk

• Low and mostly cosmetic. Failure manifests as a visual regression, not data loss or a broken write path.
• Principal risks: (1) CSS compilation drift — a theme refactor, a moved vendor path, or a CI build that does not recompile Tailwind produces silently unstyled notices; (2) single-maintainer bus factor — 71 stars and 0 tracked dependents is thin ecosystem validation, though the author (Adam Weston) is a well-established Filament ecosystem maintainer, so maintainer credibility is materially higher than the star count suggests; (3) version coupling — every Filament major requires a new Shout major, historically shipped promptly (v1→v4 across Filament 2→5) but still a recurring review obligation; (4) the visual surface is still settling — v4.1.1 fixed unresolved icon aliases, dark-mode contrast, inline action alignment, and empty headings, all in one patch.
• MIT license is clean. Exit cost is near zero: fork, or replace with an in-house partial.

Key questions

• Is awcodes/focus ^1.0 (mentioned in the v4.1.1 changelog) a runtime dependency or docs/tooling only? Confirm the resolved dependency tree before approval — an unexpected runtime dependency on a second single-maintainer package changes the risk profile.
• Do we already have a custom Filament theme with a CI-enforced asset build? If not, this package forces one and that work must be on the critical path, not assumed.
• How many contextual notices do we actually need, and where? If the answer is under ~5 call sites, a local Blade partial wins on every axis.
• Do we pin ^4.0 (Filament 4 & 5) rather than ^3.0 (Filament 4 only)? Pin 4.x.
• Who owns re-validating the package at each Filament major, and does that name exist today?

Integration Approach

Stack fit — Laravel/PHP application with Filament v4 or v5 panels and a Tailwind v4 theme pipeline. Zero fit for a non-Filament surface; do not consider it for customer-facing notices.

Migration path — None required; the change is purely additive. Install, add the @source directive, rebuild assets, drop Shout into a schema. Backout is removing the @source line and the imports — no persisted state, no schema to unwind, no data to backfill.

Compatibility — The matrix is explicit and cleanly versioned: Shout 1.x↔Filament 2, 2.x↔3, 3.x↔4, 4.x↔4 & 5. Verify the PHP constraint in composer.json against our floor (not stated in the README) during the spike. Pin exactly one line in composer.json and let Dependabot surface majors rather than floating.

Sequencing

1. Spike (½ day). Branch, install, add the @source line, rebuild the theme, render one Shout on a low-traffic form. Verify light and dark mode explicitly — dark mode is where the recent fixes landed.
2. Define semantics. Pick a fixed type set (info/success/warning/danger) and map them to our palette via icon aliases and colors, so call sites never pass raw hex. The package does not make this decision for us and will happily let 12 arbitrary colors into the admin.
3. Wrap it. Expose an app-level factory (e.g. Notices::warning(...) returning the configured Shout) so usage sites never import the vendor class. This is the single step that keeps exit cost at approximately one day.
4. Pilot 2–3 real sites — a deprecation banner on a legacy edit form, a compliance note beside a PII field, an upgrade CTA with an Action.
5. Standardize, then add the component to the internal pattern catalogue. Do not gate any release on this work.

Operational Impact

Maintenance — Small code surface, but two recurring obligations: the theme CSS must recompile in CI whenever this or Filament is bumped, and someone must review the package at each Filament major. Track record on the latter is good (v3 for Filament 4, v4 for Filament 5, majors shipped promptly), which is the signal that actually matters for a version-coupled UI package. Expect ~1–2 hours per Filament major plus the CI build cost.

Support — No commercial support, no SLA; GitHub issues only. Acceptable for a cosmetic component precisely because the escalation path is cheap: fork under MIT, or swap in an in-house partial. Do not adopt it for anything where a styling defect becomes a compliance incident without a fallback — and if compliance copy lives in a Shout, keep the copy in a config/translation file the app owns.

Scaling — Not a scaling concern in any meaningful sense. Blade render only, no queries, no JS, no queued work, no external calls. Cost is proportional to admin page renders and is negligible against any realistic panel traffic. It will never be the bottleneck.

Failure modes

• Silent styling breakage — wrong @source glob after a theme restructure, or a CI build that skips the recompile, leaving raw markup in a form. Detect with a visual smoke check on one admin page post-deploy; this is the most likely real-world incident.
• Version conflict on Filament upgrade — a loud composer conflict is the good outcome (safe, blocks the upgrade). The bad outcome is a loose constraint resolving to an incompatible pair and breaking the schema at runtime. Mitigate by pinning.
• Dark-mode / contrast regression inside the notice — low severity but user-visible, and it degrades exactly the compliance text the component exists to surface.
• Abandonment — package goes stale on a Filament major. Impact is bounded and known: fork cost ≈ one day.

Ramp-up — Effectively zero engineering ramp; the public API is five fluent methods and the README is complete. The real ramp cost is design, not code: agreeing the semantic type system and palette before rollout. Budget that conversation, or you will get per-developer color choices that undermine the consistency argument that justified the dependency in the first place.