Ui Laravel Package

Technical Evaluation

Architecture fit storyfeed/ui is a presentation-layer package, not a domain package: it ships Blade components plus parallel Vue and React kits, all rendering Storyfeed feed data from the host app. That is a good architectural fit for Laravel teams already on Storyfeed core who want a maintained renderer rather than hand-rolled Blade partials — it keeps view concerns in a vendor package and leaves data/domain ownership with the app. The v0.10.0 additions (Code and Callout body renderers, a headline-text formatting seam) extend the package further into "presentation policy" territory, which is fine, but it means the package now encodes decisions (escaping rules, which tokens get formatted, palette semantics) that product and design stakeholders should explicitly sign off on rather than inherit by default.

The most strategically interesting item is the Laravel Boost guideline and storyfeed-ui skill. Shipping agent-facing setup instructions inside the package — with a test that fails if the guideline names a component, prop, provide key, class or path the package does not actually ship — is unusually disciplined DX work. It directly reduces the cost of the hardest part of adopting this package: wiring the kit, @source lines, Vite alias, and props correctly. For a TPM, that is a measurable onboarding-cost reduction and a credibility signal about how this maintainer works.

Integration feasibility Feasible for a standard Laravel + Vite + Tailwind app, with caveats. Integration is Composer install, optional php artisan boost:install for agent guidance, kit selection (Blade/Vue/React), then Tailwind @source configuration for either a copied kit or a Vite alias into vendor. The vendor-alias path requires an additional Tailwind scan of vendor/storyfeed/ui/resources/js, now documented in the README — that is exactly the class of step teams skip and then debug for a day. The new FeedMedia payload fix removes a previous sharp edge for custom image renderers, so teams that already forked image rendering have a supported escape hatch instead of a patch.

The main feasibility constraint is version coupling with Storyfeed core. Headline formatting delegates count-token exclusion and pluralisation to core 0.21's headline text API; on older core, headlines silently stay plain. Silent capability degradation by dependency version is a support-ticket generator and should be pinned explicitly in the app's composer.json.

Technical risk

• Pre-1.0 semver. 0.9.8 → 0.10.0 is a minor bump that can legitimately break; there is no compatibility promise to lean on. Treat every upgrade as a change requiring a visual regression pass.
• Three-kit surface area. Blade, Vue and React parity is maintained by hand across bodies, seams and palettes. Parity gaps are the most likely defect class, and they surface as "works in our marketing site, broken in the app."
• Build-tool coupling. The Vite alias into vendor and Tailwind @source scans tie the package to Tailwind v4-era tooling (@theme, @source). Apps on older Tailwind or non-Vite bundlers are out of scope in practice.
• Escaping responsibility shifted to the app. The Blade HeadlineText callback returns trusted HTML and must escape text itself. That is a documented, reasonable design — and a straightforward XSS path for a team that skims the README.
• Coordinated 1.0 timing. Render Payload v1 landing at 1.0 alongside core's release candidate implies a joint release window. Upgrading one side ahead of the other is the likely failure mode.
• Governance upside. The new CI rules (tey/standards, full CI on drafts) and the doc-drift test reduce the risk that the Boost guideline misleads an agent into nonexistent APIs — a real risk in agent-assisted setup.

Key questions

1. What is the support matrix — which core versions pair with v0.10.0, and is there a hard floor or only graceful degradation?
2. Is the 1.0 Render Payload contract frozen, or still subject to change before core 1.0?
3. Is kit parity an enforced guarantee (shared fixtures/contract tests across Blade, Vue, React) or best-effort?
4. Which kit do we standardise on, and does our Tailwind/Vite setup match the documented alias path?
5. Do we want the inlineCode headline formatter on by default, and who owns that product decision?
6. What is the deprecation/support policy for 0.x minors — how much notice before a breaking change?

Integration Approach

Stack fit Strong fit for Laravel 11+/12 apps on Vite and Tailwind v4 that already consume Storyfeed core. Weak fit for Livewire-only shops that don't run a JS build (Blade kit partially mitigates), for apps on Tailwind 3, and for apps that cannot accept a vendor-path Vite alias. Confirm the kit choice before scoping: Blade is lowest-risk, Vue/React raise the parity and build-config surface.

Migration path This is an initial adoption, so the path is greenfield: Composer require with a pinned constraint, publish or alias the chosen kit, add @source lines (including the documented vendor/storyfeed/ui/resources/js scan if aliasing), then run php artisan boost:install to seed the agent guideline and skill. If adopting alongside an existing in-house feed renderer, migrate one body type at a time — text first, then Image via FeedMedia with payload, then Code and Callout — so visual diffs stay legible.

Compatibility Pin both storyfeed/ui and Storyfeed core together; treat them as a single upgrade unit. Headline formatting requires core 0.21+. HeadlineText is additive and no-ops when unset, so it is safe to ship code that registers it before deciding to enable a formatter. The inlineCode formatter is opt-in across all three kits — good, since enabling it changes rendered headline output and should be a deliberate product call.

Sequencing

1. Pin versions and lock the kit choice.
2. Stand up a single low-traffic surface (one feed, one page) and validate Tailwind scanning and image sizing.
3. Enable Boost guidance and confirm the agent produces only shipped components/props — this is the cheapest way to validate the guideline before it influences broad work.
4. Roll out Code and Callout bodies, deciding palette intent mapping (note/info/success/warning/danger) with design.
5. Enable the headline text seam and, if wanted, inlineCode; audit escaping in any custom Blade callback.
6. Expand to remaining surfaces after a visual regression pass on the pilot.

Operational Impact

Maintenance Ongoing cost is upgrade-driven rather than runtime-driven. Budget a recurring per-upgrade task: bump package + core together, run a visual diff across every feed surface, and re-check that the Boost guideline still matches the installed version (the package's own test guards the guideline against its own components, but not against our overrides). Custom Blade HeadlineText callbacks and custom image renderers become our code to maintain and secure — treat them as owned code with an escaping review, not as configuration.

Support Support burden concentrates in three places: build configuration (Tailwind @source, Vite alias), version skew against core (silent plain headlines), and escaping bugs in custom formatters. Pre-1.0 status means upstream support expectations should be modest; the maintainer's CI discipline and the doc-drift test are positive signals, but there is no LTS. Document the internal "which kit, which version pair, which surfaces" answer somewhere durable — the Boost guideline helps agents, not on-call humans.

Scaling Rendering is server/Blade-side plus client hydration for Vue/React kits; there is no new infrastructure to scale. Real scaling risk is breadth, not load: each additional feed surface multiplies the visual regression surface across three kits, and Code/Callout palettes add light/dark permutations. Keep a representative fixture set (including long code blocks, all five callout intents, unknown intent, dense child rows, full image override) as the regression baseline.

Failure modes

• Tailwind not scanning the aliased vendor path → unstyled or partially styled components in production only.
• Core older than 0.21 → headline formatting silently does nothing; looks like a bug, is a version mismatch.
• Custom Blade headline callback without escaping → stored XSS.
• Upgrading ui without core (or vice versa) around the 1.0 payload window → renderer errors or mismatched props.
• Kit parity gaps → one framework's surface renders a body type the others don't.
• Agent following a stale guideline if we vendor our own copy → invents props; mitigated upstream but not for our forks.
• Unknown callout intent falling back to note → silent design drift rather than a visible error; worth a lint or test on our side.

Ramp-up Low for a team already fluent in Laravel + Tailwind + one of the three kits: the Boost guideline compresses setup to roughly a day for a pilot surface, plus a day for visual QA. Add meaningful time if the team must pick a kit, reconcile Tailwind version, or migrate an existing renderer. Non-frontend stakeholders need a short briefing on two decisions that are now product-visible: the callout intent palette mapping and whether headline inline-code formatting is enabled — both change what end users see and should be owned explicitly rather than defaulted.