Laravel Rnx Laravel Package

Getting Started

This is a front-end styling package (CSS tokens + Tailwind theme + a small JS mode controller) consumed by a Laravel app's Blade layouts. You don't need a service provider for the v2.3.0 feature set — it is mostly asset wiring.

1. Install the package and pull in both stylesheets, not just one. css/rnx.css carries the component styles and the --rnx-* token blocks; css/plugins.css carries plugin-level overrides (Toast dark styling lives here):

/* resources/css/app.css */
@import 'vendor/rnx/css/rnx.css';
@import 'vendor/rnx/css/plugins.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

2. Register the package's Tailwind theme so utilities generate. The theme now reads --rnx-* CSS variables with the old hex values as fallbacks, so an app that has not customised anything looks identical to before.

3. First place to look: the --rnx-* token block in css/rnx.css — including the new [data-mode="dark"] / [data-theme="dark"] block. That file is now the entire theming surface of the package. If you want to know why a colour is what it is, it's defined there, not in your Tailwind config.

4. First use case: a three-way theme switch in your layout header. setMode('light' | 'dark' | 'system') sets data-mode on <html>, persists to localStorage under rnx-mode, and (in system mode) follows prefers-color-scheme live.

{{-- layouts/app.blade.php, in <head>, before your stylesheets render paint --}}
<script>
  // Avoid a flash of light theme on a dark-preferring user.
  document.documentElement.dataset.mode =
    localStorage.getItem('rnx-mode') || 'light';
</script>

Then in your header component:

<div x-data="{ mode: localStorage.getItem('rnx-mode') || 'light' }">
    <select x-model="mode" @change="setMode(mode)">
        <option value="light">Light</option>
        <option value="dark">Dark</option>
        <option value="system">System</option>
    </select>
</div>

Implementation Patterns

Use getResolvedMode() for anything that must know the actual theme. getMode() returns what the user picked ('system'), getResolvedMode() returns what is being rendered ('light' or 'dark'). Charts, iframes, embedded editors, or a <meta name="theme-color"> tag should all read the resolved value:

const meta = document.querySelector('meta[name="theme-color"]');
meta.content = getResolvedMode() === 'dark' ? '#0b0b0c' : '#ffffff';

Server-rendered pages cannot know the mode. The choice lives in localStorage, so PHP will never see it. Always pair a persistent-mode script in <head> with a sane default, and let setMode reconcile on boot. Do not try to render data-mode from a Blade variable unless you are also persisting the choice to a cookie.

Brand overrides go through tokens, not Tailwind config. Since the theme now reads --rnx-*, the supported customisation path is to redefine the tokens in your own layer after importing css/rnx.css:

:root {
  --rnx-primary: theme('colors.brand.600');
  --rnx-primary-hover: theme('colors.brand.700');
}
[data-mode='dark'] {
  --rnx-primary: theme('colors.brand.400');
}

This is also the only way to make dark mode brand-correct: overriding the token once gets you both modes if you scope a second block to [data-mode="dark"].

Bootstrap 5.3 interop is automatic. setMode also writes data-bs-theme, so Bootstrap's own dark styling follows without you writing a second controller. If you already manage data-bs-theme yourself, pick one owner — two writers on the same attribute will fight on every boot.

Scoping a theme to a subtree. [data-theme="dark"] is honoured alongside [data-mode="dark"], so you can darken a single region (a preview pane, a code block, a sidebar) without changing the page mode:

<aside data-theme="dark">…</aside>

Component usage stays declarative. Toast, StatCard and TopAppBar are used exactly as before; v2.3.0 only fixed their spacing classes so Tailwind actually generates them. If you had a safelist entry or a hand-written fallback class working around missing p-*/gap-* utilities on those three, delete it.

Test your theme, not just your markup. The package itself asserts that the dark token block overrides every colour the Tailwind theme reads and that text pairs reach AA; mirror that in your app by snapshotting getResolvedMode() after setMode and checking the computed background-color on a fixture element in system mode with an emulated prefers-color-scheme.

Gotchas and Tips

• Breaking: remapping colors.indigo no longer themes the package. The theme reads --rnx-* with the old hex as fallback, so a Tailwind config that redefined colors.indigo (or whatever the theme's palette keys are) now affects only your utilities, not the package's components. The symptom is subtle — your buttons look right, the package's components keep the default look. Migrate to setting the tokens.

• color-mix() is a hard floor for tints, hover fills and focus rings. Chrome 111 / Safari 16.2 / Firefox 113 are the minimums. Older browsers don't degrade gracefully here — they lose those effects entirely rather than falling back to a flat colour. Check your support matrix before shipping if you have an enterprise or kiosk audience on pinned browser versions.

• The focus ring offset now follows --rnx-surface. If you've set a custom surface token but left content backgrounds hard-coded, focus rings will look offset against the wrong colour. Set --rnx-surface wherever you set your page background.

• Upgrade css/plugins.css too, or Toast dark styling stays broken. The Toast dark styling used prefers-color-scheme and ignored setMode; the fix is in the plugin stylesheet. Copying only css/rnx.css across will leave you with a component that goes dark when the OS says so regardless of what the user picked.

• The default is still light, not system. Users on a dark OS get a light app until they choose. If OS-following is the behaviour you want out of the box, call setMode('system') on boot (or default your inline script's fallback to 'system' instead of 'light').

• localStorage key is rnx-mode and it's not namespaced to your app. Two apps on the same origin — app.test and admin.app.test is fine, but path-based multi-tenancy is not — will share the preference. Worth knowing before you file a bug about "the wrong theme following me around".

• Debugging checklist for "dark mode does nothing": (1) is data-mode actually on <html> — inspect the element, not the source; (2) did css/rnx.css load the [data-mode="dark"] block (view the compiled CSS, not the source file); (3) is something else setting data-mode or data-theme later and stomping it; (4) in system mode, is the OS-level toggle actually firing — the live prefers-color-scheme listener is the part most likely to be silently broken by a re-render.

• Extension points, in order of preference: override --rnx-* tokens; scope with data-theme; pass props to the components. Reach for setMode/getMode only for the mode controller itself — don't build your own parallel dark class system on top, or you'll have two sources of truth for the same visual state.