Arasy Theme Laravel Package

Getting Started

1. Install and pin. composer require rafyakbar/arasy-theme:^1.2.0 — then immediately pin it exactly ("rafyakbar/arasy-theme": "1.2.0") in composer.json. This is a visual-only package; a floating constraint means a composer update can silently change radii, scrollbar geometry, or the sidebar's dark treatment between deploys, and nothing in your test suite will notice.
2. Check the compatibility table first. The v1.2.0 README ships a Filament version matrix. The theme targets Filament v5 and depends on Filament's internal class names (.fi-sidebar-nav, .fi-*), which is exactly the kind of thing that breaks across majors. Confirm your filament/filament constraint matches before you spend time debugging CSS that was never going to apply.
3. Register the theme on the panel in your PanelProvider, following whichever mechanism the README documents (->viteTheme('resources/css/filament/admin/theme.css') for a Vite-backed theme, or the package's plugin/->theme() registration). If the package ships publishable assets: php artisan vendor:publish --tag=arasy-theme-assets.
4. Build and clear. npm run build, then php artisan filament:assets && php artisan view:clear && php artisan optimize:clear. CSS pipelines and Filament's asset cache both hold stale copies aggressively.
5. First use case to verify: open a panel page that has both a long sidebar nav (scrolls) and a long content area (scrolls a table or form). Check it in light and dark mode: 4px rounded scrollbar on content, 3px on the sidebar, visible thumb in both modes, Outfit rendering, indigo accents on primary actions, 16px/8px corner radii, sidebar staying dark regardless of mode.

Where to look first: the README compatibility table, then the published/compiled theme CSS (grep for --arasy custom properties and ::-webkit-scrollbar) so you know what you're allowed to override without touching vendor/.

Implementation Patterns

Treat the package as a baseline layer, and keep all divergence in one file. Create your own panel theme CSS (e.g. resources/css/filament/admin/theme.css) that imports the package stylesheet and then declares your overrides. Every future package bump stays a clean merge, and there's exactly one place to look when something looks wrong.

Override through CSS custom properties, not selectors. v1.2.0 moved the adaptive scrollbar colors onto custom properties specifically so inheritance is reliable. The day-to-day pattern:

:root {
    --arasy-scrollbar-thumb: #475467;
    --arasy-sidebar-scrollbar-thumb: rgba(255, 255, 255, 0.25);
}
.dark {
    --arasy-scrollbar-thumb: #98a2b3;
}

(Verify the exact property names in the shipped CSS — the pattern is right, the identifiers are whatever the package actually declares.) Overriding the property beats writing ::-webkit-scrollbar rules, because you inherit the package's width, radius, and track handling for free.

Map the design tokens into Tailwind. The theme's identity is three things you'll be asked to match in custom views and widgets: Outfit as the font, indigo as the accent, and a 16px/8px radius scale. Encode them as tokens in your own Tailwind config so a Blade component you hand-roll next month doesn't drift:

theme: {
  extend: {
    fontFamily: { sans: ['Outfit', ...defaultTheme.fontFamily.sans] },
    borderRadius: { card: '16px', control: '8px' },
  },
}

Scope per panel. In multi-panel apps (admin, staff, customer), register the theme only where you want it. Filament panels are the natural boundary — you get a different look for internal vs. external panels without conditional CSS.

One upgrade workflow, repeated. Bump the pin → npm run build → php artisan filament:assets → screenshot a light and a dark panel page → diff. Because there is nothing here to unit-test, a committed visual snapshot (Playwright or even a checked-in PNG pair) is your regression suite. Dark-mode scrollbar visibility is precisely the class of bug this release fixed — protect it.

Integration tip for custom widgets and tables: don't fight the always-dark sidebar. If your brand color is light or pastel, the sidebar will look wrong; adjust the sidebar's own nav background variables rather than switching the sidebar to light, or you'll be reimplementing the theme.

Gotchas and Tips

• !important removal is the upgrade risk. v1.2.0 dropped !important from scrollbar declarations. Any global ::-webkit-scrollbar rule in your app CSS now competes on specificity instead of losing outright. Audit your app stylesheet — and any third-party admin CSS — after upgrading, and re-check in dark mode specifically.
• Dark mode hinges on the .dark class. The fix restores html-prefixed WebKit selectors with a solid #475467, and the adaptive colors are keyed to .dark. If you've customized how dark mode is toggled (a different class name, a data attribute, a class on body instead of html), the palette won't switch. Keep Filament's default .dark-on-html convention.
• The 3px sidebar scrollbar is scoped to .fi-sidebar-nav. If you've restructured the sidebar with a custom render hook, a custom sidebar view, or your own nav container, that selector misses. Add equivalent rules against your container, or extend the existing one.
• Firefox behaves differently. ::-webkit-scrollbar does nothing there; you get scrollbar-width/scrollbar-color rendering. If the release doesn't ship those, Firefox users will see native scrollbars. Test both engines before a stakeholder demo — this is the most common "it looks broken on my machine" report for scrollbar styling.
• Cache is the number one false negative. Before concluding an upgrade did nothing: private window or hard refresh, a cache-busted build hash, and confirm the compiled CSS Filament is actually serving contains your new rules (php artisan filament:assets after every build).
• Debugging order that saves time: DevTools → select html or .fi-sidebar-nav → computed styles → look at which rule wins and from which stylesheet. If the theme's stylesheet isn't in the list at all, it's a registration or asset-publish problem, not a specificity problem. Those two failure modes look identical in the browser and are diagnosed very differently.
• Font loading is a real integration concern. Outfit must come from somewhere: if the package fetches it from a CDN, that's a CSP font-src entry and a GDPR question, plus a FOUT on first paint. Self-host the woff2 and declare the @font-face yourself if you have either constraint.
• Radius and sidebar contrast will clash with custom components. The 16px/8px scale is generous; hand-built cards, badges, and inputs copied from older Filament versions will look subtly off. Use the radius tokens rather than raw pixel values so the next scale change is one-line.
• Never edit vendor/. composer update wipes it. The supported extension points are CSS custom properties, your own published theme stylesheet, published config/views (if offered), and panel-provider registration. If a requirement genuinely can't be met that way, open an issue or fork deliberately with a note in your composer.json — don't patch in place.
• Keep the dependency honest about its scope. It's a palette, typography, radius, and chrome package — not a design system. Anything needing component-level behavior (custom nav, data tables, dashboards) belongs in your app code. Adopt it for fit-and-finish and stop there; the value collapses if you start using it as a framework.