devLap

Theme Active Admin 3 and 4 with a Version-Aware Rails Generator

ruby dev.to

Active Admin gives Rails teams a productive admin interface, but its default presentation is rarely the visual language of the rest of an application. The difficult part is not changing a color. It is applying a theme without mixing the asset pipeline for Active Admin 3 with the Tailwind pipeline used by Active Admin 4.

This tutorial uses activeadmin-claude-theme, a community MIT-licensed Rails engine gem. Its version-aware installer detects the Active Admin major version and chooses the corresponding integration path. The current stable release is 0.2.0.

TL;DR

Add the gem to an existing Active Admin application, run rails generate activeadmin_claude_theme:install, then rebuild CSS when the application uses Active Admin 4. The generator writes a Sass entry for Active Admin 3 and a Tailwind source/import setup for Active Admin 4. Active Admin 4 keeps native dark mode; Active Admin 3 receives the light theme only.

Prerequisites

You need an existing Rails application that already has Active Admin installed, plus:

  • Ruby 3.2 or newer;
  • Rails 7.2 or newer;
  • Active Admin 3.2 or newer for the AA3 path, or Active Admin 4.0.0.beta22 or newer for the AA4 path;
  • Node.js and the Active Admin Tailwind toolchain for Active Admin 4.

These requirements come from the gemspec and the project's version matrix. This is a theme for an existing admin application, not a replacement for active_admin:install.

The minimal installation path

Install the stable release in the application's Gemfile:

gem "activeadmin-claude-theme", "~> 0.2"
Enter fullscreen mode Exit fullscreen mode

Then resolve the bundle and run the generator:

bundle install
rails generate activeadmin_claude_theme:install
Enter fullscreen mode Exit fullscreen mode

The generator checks the installed Active Admin version. It raises an unsupported-version error instead of silently applying the wrong asset integration when the application is outside the supported range.

Active Admin 4

Active Admin 4 uses Tailwind CSS v4. After the generator runs, rebuild the stylesheet and restart Rails:

npm run build:css
bin/rails server
Enter fullscreen mode Exit fullscreen mode

The AA4 integration places the source stylesheet under app/assets/tailwind/active_admin.css, imports the theme CSS, and builds the served file under app/assets/builds/active_admin.css. Keeping the source outside the served build path matters when Propshaft is involved: the browser should receive compiled CSS, not the Tailwind source file.

The generator also adds the theme's view content to the Tailwind configuration when that configuration is present. That lets Tailwind see classes used by the engine's view overrides.

Active Admin 3

Active Admin 3 uses the Sprockets and Sass path. After the generator runs, make sure the application has a compatible Sass dependency and restart Rails:

bundle install
bin/rails server
Enter fullscreen mode Exit fullscreen mode

The resulting app/assets/stylesheets/active_admin.scss should contain the theme entry:

@import "activeadmin_claude_theme/aa3/base";
Enter fullscreen mode Exit fullscreen mode

If the application already has an active_admin/base import, the generator replaces it with the theme entry. If the stylesheet does not exist, it creates the file. The manifest also receives active_admin.css when the application uses an asset manifest that does not already include it.

Verify what the generator changed

Do not treat a successful generator command as proof that the browser is serving the right stylesheet. Check the generated files and the asset command for the relevant branch.

For an AA4 application:

git diff -- app/assets/tailwind/active_admin.css app/assets/builds package.json tailwind-active_admin.config.js
npm run build:css
test -f app/assets/builds/active_admin.css
Enter fullscreen mode Exit fullscreen mode

For an AA3 application:

git diff -- app/assets/stylesheets/active_admin.scss app/assets/config/manifest.js
bundle exec rails runner 'puts Rails.application.config.assets.paths'
Enter fullscreen mode Exit fullscreen mode

On Windows, use Test-Path app/assets/builds/active_admin.css instead of test -f. The important result is that the generated integration matches the asset pipeline your application actually uses.

The release itself is also inspectable without trusting a copied version string:

gem fetch activeadmin-claude-theme -v 0.2.0
gem specification activeadmin-claude-theme-0.2.0.gem version license required_ruby_version
Enter fullscreen mode Exit fullscreen mode

The published gem reports version 0.2.0, MIT licensing, and Ruby >= 3.2.0. Remove the downloaded gem after inspection if you do not need it.

Customize tokens without rewriting the theme

The theme exposes design tokens for the main surfaces and accent color. In Active Admin 4, override CSS variables after the theme import:

:root {
  --claude-primary: #d4845f;
  --claude-canvas: #fff8f0;
}

.dark {
  --claude-canvas: #121110;
}
Enter fullscreen mode Exit fullscreen mode

In Active Admin 3, set Sass variables before importing the theme base:

$claude-primary: #d4845f;
$claude-canvas: #fff8f0;
@import "activeadmin_claude_theme/aa3/base";
Enter fullscreen mode Exit fullscreen mode

The design token reference documents the available values. Start with a small override file so upgrades remain reviewable. Editing generated or vendored CSS makes future gem updates harder to reason about.

Why the version-aware approach works

Active Admin 3 and 4 do not share one stylesheet contract. AA3 expects Sass and Sprockets conventions, while AA4 uses Tailwind v4 and a build output. A single copy-pasted import can look plausible and still fail at runtime because it targets the wrong pipeline.

The installer centralizes that decision in the application generator. It detects the Active Admin major version, writes only the corresponding integration, and prints the next build or restart action. The result is not magic. It is a small amount of version-specific setup made explicit and repeatable.

Failure modes to check first

The generator reports an unsupported version

Check the resolved Active Admin version with:

bundle exec ruby -e 'spec = Gem.loaded_specs["activeadmin"]; puts spec&.version'
Enter fullscreen mode Exit fullscreen mode

Active Admin 2.x is outside the supported range. Upgrade Active Admin or choose a theme that explicitly supports that version.

AA4 has no active_admin.css after installation

Run the Active Admin asset generator first, then run the theme generator again if necessary:

rails generate active_admin:assets
rails generate activeadmin_claude_theme:install
npm run build:css
Enter fullscreen mode Exit fullscreen mode

Inspect the source and build locations. The README specifically distinguishes the Tailwind source file from the compiled file served by Propshaft.

AA3 styles compile with Sass errors

Confirm that the application has sassc-rails or another compatible Sass pipeline and that active_admin.scss imports activeadmin_claude_theme/aa3/base. AA3 does not use the AA4 Tailwind import.

The page is styled but dark mode is missing

That is expected for Active Admin 3. The project's FAQ documents native dark mode for AA4 only. AA3 has the light theme and approximate visual parity, not the AA4 dark-mode implementation.

Security and operational boundaries

This gem changes presentation and asset files. It does not provide authentication, authorization, secret storage, or a security guarantee for the admin application. Keep Active Admin's authorization and deployment controls in place.

The installer can add a Google Fonts import to the generated AA4 stylesheet. If your deployment must avoid third-party browser requests, replace that import with self-hosted fonts or remove it according to your policy. The repository describes the project as a community theme and explicitly says it is not affiliated with Anthropic.

FAQ

Does the theme work with both Active Admin 3 and 4?

Yes, on the supported versions, but the implementation differs. AA3 uses Sass and is light-only. AA4 uses Tailwind v4 and preserves native dark mode.

Do I need Node.js?

For Active Admin 4, yes, because the documented CSS workflow uses the Tailwind toolchain. The Active Admin 3 path uses Sass through the Rails asset pipeline.

Can I use this with Rails 6?

Not according to the current gemspec. The declared minimum is Rails 7.2, so an older application needs an explicitly compatible theme or an upgrade plan.

Is this an official Claude or Anthropic theme?

No. It is an independent open-source community theme inspired by a visual direction. The repository makes that boundary explicit.

Takeaway

The useful part of this gem is not only its palette. It packages the integration boundary between two Active Admin asset systems into a repeatable generator. Install the pinned stable release, inspect the generated files, rebuild the correct pipeline, and keep your own token overrides small and reviewable.

Have you found the Sass-to-Tailwind boundary in an Active Admin upgrade, or do you keep separate admin themes for each major version?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. The commands, version requirements, integration behavior, license, and limitations were checked against the project's public README, gemspec, release tag, changelog, FAQ, and published gem metadata.

Source: dev.to

arrow_back Back to Tutorials