Artemis Laravel Package

Getting Started

Verify the stack before you type anything. Artemis is a presentation-only theme for the Lara Zeus family of Filament plugins (bolt, thunder, rhea, sky, athena, hermes, cron). It ships Blade views, Tailwind/CSS tokens, and a service provider that registers a panel theme — no models, migrations, routes, or backend behavior. If your admin panel isn't already running at least one Zeus package, it gives you nothing.

Install pinned. The repo is archived; the last release is v1.0.10 (2025-03-07). Avoid a floating constraint that implies upgrades exist:

composer require lara-zeus/artemis:1.0.10

Discover what the provider actually publishes rather than hunting for docs that aren't there:

php artisan vendor:publish --provider="LaraZeus\Artemis\ArtemisServiceProvider"

Publish config, views, and CSS/asset tags into your app, and commit the published output. Published views are your editing surface — never touch vendor.

Register on one panel, not all of them. In your Filament PanelProvider, use whichever the theme ships for your Filament major (->viteTheme(...) for a compiled Vite entry, ->theme(...) for a plain CSS asset). Start with a secondary or throwaway panel so rollback is a one-line diff.

Then fix the thing that will actually break first — Tailwind scanning the vendor Blade files:

// tailwind.config.js
content: [
  './resources/**/*.blade.php',
  './app/Filament/**/*.php',
  './resources/views/vendor/artemis/**/*.blade.php',
],

First use case. Pick one existing Zeus resource with a list page, a form, and a table. Register the theme on your throwaway panel, run npm run build (not just dev), and diff the rendered output against your current panel. That five-minute exercise surfaces the package's defining failure mode — looks right in dev, half-styled in the built CSS — before you've committed to anything.

Where to look first, in this order: the service provider (what it registers and publishes), resources/views (which Zeus view namespaces it overrides — this is your collision map against your own customizations), resources/css (the token layer you'll fold into your design system), and composer.json (its Laravel/Filament/Tailwind constraints versus yours).

Implementation Patterns

Fork into a path repository rather than depending on the archive. This is the only durable pattern for an archived theme:

"repositories": [
  { "type": "path", "url": "packages/admin-theme", "options": { "symlink": true } }
],
"require": { "lara-zeus/artemis": "*" }

Copy the package in, rename it under your vendor namespace, drop the upstream composer.json requirement, and record ownership in your service catalog with a note explaining why it's a local package. Without that note, a future engineer will "clean up" the local dependency, reinstall the archived original, and silently make abandoned upstream the source of truth again.

Respect the override precedence chain: your app's own views beat published vendor views, which beat the package's views. Day-to-day workflow is publish → edit the published copies → leave the vendor directory pristine. When a single page needs to deviate, reach for Filament's own extension points (custom page classes, ->extraAttributes(), render hooks) instead of forking a Blade file, so your upgrade surface stays legible.

Flatten the theme into your design tokens in the same PR that installs it. Don't run two competing palettes. Map Artemis's CSS custom properties and type scale onto the tokens you already own, and keep one source of truth. Artemis's aesthetic is opinionated and narrative — the adaptation cost is paid once in design time and is far cheaper before ten pages depend on the raw values.

Theme per panel, never globally. If you run multiple Zeus panels, register the theme independently on each so you can roll forward and back per surface. Never run Artemis alongside another panel theme on the same panel; CSS specificity conflicts there won't show up in code review but will show up for users.

Add a visual regression check to CI. Breakage in a theme package is silent and visual, not a runtime exception. Screenshot the themed list/form/table pages with Playwright or Dusk and diff. That's the only cheap detection you'll get.

Deployment checklist: npm run build in CI → confirm the theme entry exists in the Vite manifest → php artisan view:clear → php artisan config:cache if you keep a published config → cache-bust assets off the manifest so a deploy doesn't serve stale CSS against new markup.

Gotchas and Tips

• The Tailwind content glob is the #1 trap. Classes living in vendor Blade files you don't scan simply don't exist in the built CSS. Symptom: correct under npm run dev, unstyled blocks in production. Grep the built CSS for a known theme class before you trust any build.
• Archived means the support clock already ran out. No Filament v4 work, no Tailwind v4 work, no security response. Pin Filament and Tailwind majors explicitly, and budget a manual theme-compatibility task into every upgrade runbook — that recurring cost, not the install, is the real price of adoption.
• The v1.0.10 icon change degrades silently. That release removed iconpark. If you're upgrading from <=1.0.9 and any published view references those icons, they vanish without erroring. Grep your published views for the icon set before bumping.
• Blade executes PHP inside an authenticated admin panel. Review every shipped view before it renders for an admin. Low risk for a mostly-CSS theme, but "mostly CSS" isn't a guarantee.
• vendor:publish --force will clobber your edits. Commit published views and treat --force as a deliberate, reviewed operation.
• Config cache surprises. Change the published config on a machine with config:cache active and nothing appears to happen. Always php artisan config:cache after the change, then re-check the panel.
• Collision mapping is your most valuable artifact. If you've already customized the same Zeus views, the theme's overrides land in a different precedence slot than you expect. Produce an inventory of overridden view namespaces up front; it saves hours later.
• Debugging an unstyled panel, in order: panel theme registration → Vite manifest → Tailwind content glob → view:clear. Nine times out of ten it's one of the middle two.
• Extension points worth knowing: published views (your primary lever), Filament render hooks, the theme's CSS custom properties, and — if present — its Theme class for programmatic registration. Prefer all of them to editing vendor files.
• Defer if you're mid-migration to Filament v4 or Tailwind v4. Adopting an archived theme during a major upgrade means straddling two sets of breaking changes with no upstream to absorb either. Use Artemis as a design reference in that window, not a dependency.