Laravel Rnx Laravel Package

Technical Evaluation

Architecture fit Despite being framed as a Laravel/PHP package, every change in v2.3.0 lands in the front-end asset layer: css/rnx.css, css/plugins.css, the Tailwind theme, and a JS mode API (setMode / getMode / getResolvedMode). There are no Composer, config, migration, service-provider, or Blade-side changes called out. The package therefore behaves as a UI kit vendored into a Laravel app via vendor:publish + Vite, not as a PHP integration surface. That is a good fit for Blade/Livewire/Inertia hosts that already compile Tailwind, but it means the theme state lives entirely in the browser (localStorage['rnx-mode'] + data-mode on <html>), so the server can never render the correct theme on first response. Theming now spans three attributes — data-mode, data-theme, and Bootstrap's data-bs-theme — which is three sources of truth for one concern.

Integration feasibility Mechanically easy: publish assets, import CSS, call setMode. The friction is the Tailwind change. Teams that remapped colors.indigo (or any palette key) in tailwind.config.js will silently lose those overrides, because the theme now reads --rnx-* variables with the old hexes as fallbacks. Nothing fails loudly — the UI just reverts to stock colours. That is a customization-breaking change shipped in a minor version, and it needs a config audit before bumping. The color-mix() dependency (tints, hover fills, focus rings) also imposes a browser floor — Chrome 111, Safari 16.2, Firefox 113 — that must be reconciled with the host app's browserslist and any locked-down enterprise browser fleet.

Technical risk

• Semver/change-management risk (highest). Token remapping breaks existing brand customizations in a patch-level-feeling upgrade. Pin the version and treat this as a deliberate migration, not a routine bump.
• First-paint risk. Reading localStorage and setting data-mode from JS means a light flash for dark-mode users unless a blocking inline init script is added in <head>. No such snippet is mentioned.
• Accessibility regression risk. Losing focus rings and hover fills on sub-floor browsers can fail WCAG 2.4.7. The package's AA test validates its own dark tokens only — it cannot validate host-supplied --rnx-* overrides.
• Dual-theme-manager risk. setMode writes data-bs-theme, which will fight any existing Bootstrap 5.3 theme toggle in the host app.
• Livewire/Inertia/Turbo risk. wire:navigate and Turbo swaps don't re-run <head> scripts by default; mode application and prefers-color-scheme listeners may not re-attach or may leak.

Key questions

1. Is there a documented pre-paint init snippet (blocking, CSP-nonce-friendly) so dark users don't see a flash?
2. Is setMode idempotent and listener-cleaning on repeat calls and on wire:navigate/Turbo page swaps?
3. Does the AA test assert contrast against host-overridden tokens, or only the shipped defaults? What is the guidance for teams defining custom dark tokens?
4. What is the recommended fallback strategy for color-mix() — polyfill, static fallback colours, or accept the degradation?
5. Is the palette remap deprecation permanent, and is there a migration table from Tailwind config keys to --rnx-* tokens?
6. Does the 907-test suite cover anything on the PHP side, or is it JS-only? (Release notes imply JS-only.)
7. Should mode preference be persisted server-side per user (a Laravel-side field + cookie) to avoid per-device divergence?

Integration Approach

Stack fit Laravel 10/11 + Vite + Tailwind (config-driven) + Bootstrap 5.3 + Blade/Livewire/Inertia. The package slots in at the compiled-asset layer with no PHP runtime footprint; Bootstrap 5.3 alignment is handled for free via data-bs-theme. Alpine works cleanly with data-mode as a reactive attribute. The main fit caveat is SSR/Blade: because the server has no knowledge of theme choice, any server-rendered markup that bakes in colours must read tokens, not literal hexes.

Migration path

1. Pin the current version; do not float on ^2.
2. Grep tailwind.config.js and any CSS for palette overrides (colors.indigo, brand key remaps) and inventory them.
3. Translate each override into a --rnx-* token declaration — verify the fallback behaviour first, since a no-op migration should be visually identical.
4. Add the pre-paint init script to the root Blade layout <head> before any stylesheet-dependent paint.
5. Adopt setMode behind the existing toggle (or replace the existing toggle) and remove any competing data-bs-theme manager.
6. Regression pass on Toast, StatCard, and TopAppBar — their spacing classes are now emitted by Tailwind, which can shift layout in hosts that had been compensating for the missing utilities.
7. Measure the CSS delta from the new dark token block and newly generated utilities.

Compatibility Functional compatibility is broad; visual compatibility requires Chrome 111 / Safari 16.2 / Firefox 113 for tints, hover fills, and focus rings. Confirm the host's browserslist and Tailwind targets, and decide explicitly whether to raise them or accept degraded affordances. Bootstrap 5.3 is now effectively required for the data-bs-theme behaviour to be meaningful. localStorage availability in private/blocked-storage contexts needs a graceful no-op path.

Sequencing Split into two shippable steps: (a) token migration with zero intended visual change, then (b) dark-mode enablement. Land (b) behind a feature flag or a single canary route, observe for a release cycle, then roll out. Do not bundle this with other UI or design-system work — the palette change and the browser-floor decision both need clean attribution if something regresses. Avoid shipping near a release freeze given the first-paint and contrast risks.

Operational Impact

Maintenance The --rnx-* token set is now a public API surface owned by the package; treat it as such and pin versions. Hosts that override tokens take on permanent maintenance of a parallel theme, including dark variants that the package's tests will not cover. Dual attribute management (data-mode / data-theme / data-bs-theme) is a small but recurring source of drift that should be centralised in one helper, not scattered across toggles.

Support Expect three ticket classes: "our brand colours stopped applying" (Tailwind remap no longer honoured), "dark mode flashes light on load" (missing pre-paint script), and "hover/focus styling disappeared on older Safari/Chrome" (color-mix() floor). Write a short internal runbook covering the token mapping table, the init snippet, and the browser-floor statement. Note that mode preference is per-browser and per-device — users will report inconsistency across devices, which is expected behaviour, not a bug, unless server-side persistence is added.

Scaling Effectively zero server-side cost: no queries, no queues, no PHP memory. The scaling concerns are payload and cache. CSS grows from the dark token block, the newly emitted spacing utilities, and color-mix() expressions — measure the gzipped delta and confirm it stays inside the CSS budget. Both css/rnx.css and css/plugins.css changed, so CDN/browser cache invalidation must be handled deliberately (hashed filenames via Vite are the clean answer). prefers-color-scheme listeners are per-tab and cheap, but must be torn down on navigation to avoid accumulation in long-lived SPA sessions.

Failure modes

• Theme flash on first paint — localStorage read after paint; most visible on slow connections and the most likely first bug report.
• Host token sets without dark values — package AA test passes, host contrast fails; no automated guard.
• Lost focus indicators on sub-floor browsers — accessibility failure that automated visual tests on modern headless browsers will not catch.
• Competing theme managers — host toggle and setMode both writing data-bs-theme yields flicker or a stuck theme.
• Navigation lifecycle — Livewire/Inertia/Turbo swaps leaving mode unapplied or listeners duplicated.
• Blocked localStorage — private mode or storage-partitioned contexts; setMode must degrade to in-memory only.
• Layout shift on Toast/StatCard/TopAppBar — spacing utilities that previously weren't generated now are, changing computed spacing in hosts that had patched around the gap.

Ramp-up Low for any developer comfortable with Tailwind and CSS custom properties: roughly half a day for the token migration and init script on a mid-size app, plus a QA cycle for dark mode across every component in both Bootstrap and Tailwind surfaces. The two items that require real judgement rather than mechanical work are the browser-floor decision and the contrast audit of host-supplied tokens — both should be owned by someone with accessibility accountability, not delegated to the implementer.