devLap

Style Active Admin 3 and 4 with One Rails Theme Gem

ruby dev.to

Active Admin gives Rails applications a productive admin surface, but its styling depends on which major version your application uses. Active Admin 3 expects a Sass and Sprockets workflow. Active Admin 4 uses Tailwind CSS v4 and a different source-to-build path. A theme that treats them as the same problem can leave you with a successful generator run and an unstyled page.

This tutorial uses activeadmin-claude-theme, an MIT-licensed Rails engine gem, to install the same warm visual language on both Active Admin branches. The current 0.2.0 release includes a version-aware generator, Active Admin 3 support, and Active Admin 4 support. The theme is a community project inspired by Claude aesthetics. It is not affiliated with or endorsed by Anthropic.

TL;DR

Add the gem, run its installer, and then use the asset step that belongs to your Active Admin version:

bundle add activeadmin-claude-theme
rails generate activeadmin_claude_theme:install

# Active Admin 4 only
npm run build:css
Enter fullscreen mode Exit fullscreen mode

For Active Admin 4, the generator keeps Tailwind source in app/assets/tailwind/active_admin.css and builds the served file into app/assets/builds/active_admin.css. For Active Admin 3, it writes the Sass entry point at app/assets/stylesheets/active_admin.scss.

Prerequisites

You need an existing Rails application with Active Admin installed, Ruby 3.2 or newer, and Rails 7.2 or newer. The theme's release notes document support for Active Admin 3.2 through the 3.x line and Active Admin 4.0.0.beta22 or newer. Active Admin 4 also requires the Node-based Tailwind build used by its asset setup.

The commands below assume you have already run Active Admin's installer. If you are starting from an empty Rails application, follow the Active Admin installation guide first, then return here.

Install the theme

Add the gem to your application's Gemfile:

gem "activeadmin-claude-theme"
Enter fullscreen mode Exit fullscreen mode

Install dependencies and run the generator:

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

The generator detects the installed Active Admin major version. It does not ask you to choose a stylesheet manually, because the integration points are different.

Active Admin 4: build the Tailwind output

Active Admin 4 uses Tailwind v4. The theme generator vendors its CSS into the application, imports it from the Tailwind source, and updates the build script when the standard setup is present.

Run the CSS build after installation:

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

The important distinction is source versus served output:

app/assets/tailwind/active_admin.css   # Tailwind source
app/assets/builds/active_admin.css     # compiled output
Enter fullscreen mode Exit fullscreen mode

The source file is outside the Propshaft-served path. Serving the uncompiled source instead of the build output is a common reason for seeing an admin page with little or none of the expected styling.

The generator also adds the theme gem's view directory to the Tailwind content configuration when tailwind-active_admin.config.js exists. That lets Tailwind see the engine templates that contain utility classes. The implementation uses bundle show activeadmin-claude-theme to locate the installed gem rather than asking you to hard-code a machine-specific path.

Active Admin's own dark-mode toggle remains part of the AA4 setup. The theme remaps color scales and adds semantic variables while preserving the existing hooks instead of replacing the whole plugin.

Active Admin 3: use the Sass entry point

Active Admin 3 follows a Sprockets and Sass path. After running the same generator, check app/assets/stylesheets/active_admin.scss:

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

Then make sure your application includes a Sass pipeline such as sassc-rails or dartsass-rails, and restart Rails:

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

The AA3 integration replaces the legacy active_admin/base import when it finds one. If the stylesheet has a different structure, the generator appends the theme import so you can review the result before committing it.

There is an intentional feature difference here: Active Admin 3 receives the light theme only. Native dark mode is documented for the AA4 path because Active Admin 3 does not provide the same dark-mode mechanism.

Customize the palette without replacing the theme

The theme exposes semantic tokens for the common colors. On 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

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

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

This is safer than editing generated gem files. The repository's design token reference lists the available roles, including the accent, canvas, ink, and body colors.

Verify the installation

Use a short checklist rather than relying only on a successful generator exit code:

  1. Confirm the gem is locked to the version you reviewed. For this tutorial, that is 0.2.0.
  2. On AA4, confirm the Tailwind source exists under app/assets/tailwind/ and the compiled CSS exists under app/assets/builds/ after npm run build:css.
  3. On AA3, confirm the Sass entry imports activeadmin_claude_theme/aa3/base.
  4. Open an Active Admin dashboard and an index page. Check the header, navigation, table, form, and login screen.
  5. On AA4, toggle dark mode and verify that the existing control still works.
  6. Change one semantic token, rebuild the relevant assets, and confirm the rendered color changes.

For a repository-level verification, the project documents separate dummy applications and integration commands for AA4 and AA3. Running those tests is useful when upgrading the theme or changing its overrides:

# AA4
cd test/dummy
npm install
npm run build:css
ruby bin/rails db:setup db:seed
cd ../..
ruby -Itest test/activeadmin_claude_theme_test.rb
ruby -Itest test/integration/theme_integration_test.rb

# AA3
BUNDLE_GEMFILE=gemfiles/activeadmin_3.gemfile bundle install
cd test/dummy_aa3
bundle exec rails db:setup db:seed
cd ../..
DUMMY_PATH=dummy_aa3 BUNDLE_GEMFILE=gemfiles/activeadmin_3.gemfile \
  ruby -Itest test/activeadmin_claude_theme_test.rb
Enter fullscreen mode Exit fullscreen mode

Why the version-aware generator matters

The visual goal is shared, but the integration boundary is not. AA4 needs Tailwind source discovery, a build command, and view content paths. AA3 needs a Sass import and a Sprockets-compatible manifest. The generator makes that branch explicit in code through Active Admin version detection.

It also handles a subtle AA4 failure mode: a legacy app/assets/stylesheets/active_admin.css file can be moved to app/assets/tailwind/active_admin.css before compilation. That keeps the source from being treated as the final served asset by Propshaft.

The result is not magic CSS. It is a small Rails engine with two integration paths, shared design tokens, and limited view overrides. That makes the generated changes inspectable in your own application.

Failure modes and security boundaries

If rails generate activeadmin_claude_theme:install reports an unsupported Active Admin version, check the resolved bundle. Active Admin 2.x is outside the documented support range. If AA4 looks unstyled, rebuild CSS and check the source and build locations before changing templates. If AA3 fails to compile, verify the Sass dependency and import path.

The theme changes presentation. It does not provide authentication, authorization, CSRF protection, or a security review of your admin resources. Active Admin's authorization and Devise configuration remain application responsibilities. Keep the admin surface behind your existing authentication and authorization controls, and review generated template changes before deploying them.

Also treat the name accurately: this is a community theme, not an Anthropic product. The visual inspiration is not a security or compatibility guarantee.

FAQ

Does one installation command support both Active Admin versions?

Yes. The generator detects Active Admin 3 or 4 and applies the corresponding asset setup. The follow-up verification differs because AA4 needs a CSS build while AA3 uses Sass.

Do I need Node.js for Active Admin 3?

Not for the theme's documented AA3 path. AA3 uses Sass through Sprockets. Node.js is required for the AA4 Tailwind workflow.

Can I use the theme with Propshaft?

Yes for the documented Active Admin 4 setup, provided Tailwind source stays under app/assets/tailwind/ and the compiled file is emitted under app/assets/builds/. AA3 typically uses Sprockets instead.

Can I keep my own brand colors?

Yes. Override the semantic CSS variables for AA4 or Sass variables for AA3, then verify the generated CSS in the browser. Use the design token reference to choose the right role instead of changing many selectors.

Takeaway

The useful lesson is not the palette. It is respecting the boundary between Active Admin 3's Sass pipeline and Active Admin 4's Tailwind pipeline. A version-aware installer can keep the setup small, but you still need to verify the actual source path, compiled asset, and rendered admin pages.

Have you kept one Rails admin theme working across a major asset-pipeline change? I would be interested in which compatibility boundary caused the most maintenance in your application.

AI assistance disclosure

AI assistance was used to organize this tutorial and review its wording. The technical details and commands were checked against the project's current README, generator implementation, gemspec, changelog, FAQ, override map, and the Active Admin documentation linked above.

Source: dev.to

arrow_back Back to Tutorials