DEV Community

Fernando Paladini
Fernando Paladini

Posted on

Install Active Admin Claude Theme 0.2.0 in Rails

#ruby #rails #tutorial #activeadmin

If an Active Admin backend works but still looks like a default admin panel, a theme gem can improve the interface without forcing a full frontend rewrite. The difficult part is choosing the correct integration path. Active Admin 3 uses Sass and Sprockets, while Active Admin 4 uses Tailwind CSS v4 and a different asset layout.

This tutorial installs activeadmin-claude-theme version 0.2.0 in a Rails application, explains the version-aware generator, and shows how to customize its tokens. The gem is a community project inspired by Claude aesthetics. It is not affiliated with or endorsed by Anthropic.

TL;DR

Add the gem to an existing Active Admin application, run rails generate activeadmin_claude_theme:install, rebuild CSS when using Active Admin 4, and verify the generated asset entry before restarting Rails. Active Admin 4 keeps dark mode and uses CSS variables. Active Admin 3 receives a Sass theme and light mode only.

Prerequisites

The release documentation lists these requirements:

  • Ruby 3.2 or newer
  • Rails 7.2 or newer
  • Active Admin 4.0.0.beta22 or newer for the Tailwind path
  • Active Admin 3.2 or newer for the Sass path
  • Node.js and the Active Admin npm toolchain for Active Admin 4

The project is distributed under the MIT license. The 0.2.0 release is available on GitHub and RubyGems. The gem declares runtime dependencies on Active Admin >= 3.2.0, < 5 and Rails >= 7.2.

This guide assumes that Active Admin is already installed. It does not replace the official Active Admin installation guide.

Install the theme in Active Admin 4

Active Admin 4 uses Tailwind CSS v4. The theme's release documentation uses 4.0.0.beta22 as its documented example, so keep the Active Admin and npm versions aligned with the application you are actually maintaining.

Add the gem to your Gemfile:

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

Install the bundle and run the generator:

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

The generator detects Active Admin's major version. For Active Admin 4, it prepares the Tailwind entry and the theme assets. Rebuild the stylesheet and restart Rails:

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

The important detail is the separation between source and served CSS. The documented layout is:

app/assets/tailwind/active_admin.css
app/assets/builds/active_admin.css
Enter fullscreen mode Exit fullscreen mode

The first file is the Tailwind source. The second is the generated stylesheet served by the application. If the source file is placed directly in the served Propshaft path, the build can produce confusing results or fail to expose the expected active_admin asset.

Install the theme in Active Admin 3

Active Admin 3 follows the Sprockets and Sass path. Add the same gem, but make sure the application has the Sass dependencies documented by the project:

gem "activeadmin", "~> 3.5"
gem "sprockets-rails"
gem "sassc-rails"
gem "devise"
gem "activeadmin-claude-theme", "~> 0.2"
Enter fullscreen mode Exit fullscreen mode

Install the bundle and run the same generator:

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

For Active Admin 3, the generator updates app/assets/stylesheets/active_admin.scss to use the theme entry:

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

Restart Rails after the asset change. Do not copy the Active Admin 4 Tailwind setup into an Active Admin 3 application. The two integration paths intentionally use different asset pipelines.

Customize the design tokens

The theme exposes a small set of semantic tokens instead of requiring selectors to be rewritten throughout the application. 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 theme base:

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

The release's design reference documents the palette, typography, spacing, and token naming. The default primary color is #cc785c, the canvas is #faf9f5, and the semantic token prefix is --claude- for CSS variables.

Prefer semantic tokens for global changes. If a single screen needs a special treatment, use a narrow application-level selector rather than changing the theme's generated files. This keeps upgrades reviewable and makes it clear which choices belong to the application.

Verify the generated integration

After the generator finishes, verify the files before debugging the browser. For an Active Admin 4 application, check that the Tailwind source and build output exist:

Test-Path app/assets/tailwind/active_admin.css
Test-Path app/assets/builds/active_admin.css
Enter fullscreen mode Exit fullscreen mode

On a Unix-like shell, the equivalent check is:

test -f app/assets/tailwind/active_admin.css
test -f app/assets/builds/active_admin.css
Enter fullscreen mode Exit fullscreen mode

Then rebuild and inspect the generated CSS for one token that you changed:

npm run build:css
grep -n "claude-primary" app/assets/builds/active_admin.css
Enter fullscreen mode Exit fullscreen mode

On Windows PowerShell, use this instead of grep:

Select-String -Path app/assets/builds/active_admin.css -Pattern "claude-primary"
Enter fullscreen mode Exit fullscreen mode

For Active Admin 3, verify the Sass import and run the normal Rails asset precompile or development server path used by the host application:

grep -n "activeadmin_claude_theme/aa3/base" app/assets/stylesheets/active_admin.scss
bin/rails assets:precompile
Enter fullscreen mode Exit fullscreen mode

The expected result is an Active Admin page using the theme's warm palette. On Active Admin 4, the built-in dark mode and mobile drawer remain Active Admin features. The theme's AA4 override map explains which partials the gem overrides and which hooks it deliberately preserves.

Common failure modes

The page is unstyled after installation

For Active Admin 4, run npm run build:css or the application's documented bin/rails css:build command, then restart Rails. Also confirm that the source is under app/assets/tailwind and the generated file is under app/assets/builds.

The generator changes the wrong file

The generator detects the installed Active Admin major version. Check the bundle before running it. An application with a stale or conflicting Active Admin dependency can be classified differently from what you expect.

Active Admin 3 reports a Sass error

Confirm that sassc-rails or a compatible Sass pipeline is installed and that the file imports activeadmin_claude_theme/aa3/base after your own variable overrides.

You expect dark mode on Active Admin 3

That is not supported by this release. The project documents dark mode for Active Admin 4 only because Active Admin 3 does not provide the same native dark-mode mechanism.

You treat the theme as an official Claude product

Do not. The README and FAQ explicitly describe it as a community theme. The name and visual inspiration do not provide any Anthropic affiliation, endorsement, security guarantee, or product compatibility promise.

FAQ

Can one Gemfile support both Active Admin 3 and 4?

The gem supports both major versions, but an individual application should use one Active Admin integration path at a time. The project's own development setup uses separate dummy applications and dependency files for its version coverage.

Does the theme replace all Active Admin templates?

No. The AA4 documentation describes minimal partial overrides and preserved Active Admin hooks. It remaps Tailwind colors, adds semantic tokens, and customizes selected header and navigation partials.

Can I use it with Propshaft?

The FAQ documents Propshaft support for Active Admin 4 when the standard Tailwind and cssbundling setup is followed. Active Admin 3 typically remains on Sprockets.

What should I customize first?

Start with --claude-primary and --claude-canvas on Active Admin 4, or their Sass equivalents on Active Admin 3. These two choices demonstrate the token flow without coupling your application to internal selectors.

Takeaway

The useful part of activeadmin-claude-theme is not only its palette. Its version-aware generator makes the Active Admin 3 and 4 boundary explicit, while its token model gives Rails teams a small, reviewable customization surface. Install against the release that matches your application, verify the generated asset path, and treat Active Admin 3 and 4 as separate pipelines.

Have you kept one Active Admin application compatible with both major asset pipelines, or did you choose a clean upgrade to Active Admin 4? Share the constraint that shaped the decision.

AI assistance disclosure: AI assistance was used to organize this tutorial and draft prose. Project behavior, versions, commands, limitations, and links were checked against the public repository, the v0.2.0 release, the gem metadata, and the project documentation.

Top comments (0)