Customize Active Admin with CSS Design Tokens and Mobile Navigation

If an Active Admin interface works but still feels like an internal tool from another decade, replacing the entire admin stack is usually too expensive. The smaller move is to change the visual system around the screens you already have.

This tutorial shows how to use Active Admin AAA Theme as a Rails theme and then customize its CSS design tokens. The useful idea is not the Apple-inspired visual language itself. It is the separation between the theme structure and the values you are likely to change: colors, type, spacing, radiuses, and shadows.

The repository currently identifies itself as version 0.1.0, requires Ruby 3.0 or newer, and declares Rails 6.1 or newer plus Active Admin 3.0 or newer as gem dependencies. It is public, MIT licensed, and has no published GitHub release or RubyGems package at the time of writing. Treat the current branch as an early project, not as a stability guarantee. The version and dependency claims come from the version file and gemspec.

TL;DR

Add the theme gem to a Rails application, import its stylesheet and JavaScript entrypoints, then override the --aaa-* variables in your own stylesheet. Verify the result in both light and dark color schemes, and check the mobile menu before treating the change as complete.

Prerequisites

You need:

• A Rails application that already uses Active Admin.
• Ruby 3.0 or newer.
• Rails 6.1 or newer and Active Admin 3.0 or newer.
• Bundler and an asset pipeline or JavaScript setup that can load the documented imports.
• A way to inspect the admin UI at desktop and mobile widths.

The theme is a presentation layer. It does not replace Active Admin authentication, authorization, database models, filters, or resource definitions. Keep those responsibilities in your application.

Install the theme

Add the gem name from the project's current README to your application's Gemfile:

gem 'activeadmin-aaa-theme'

Install dependencies:

bundle install

The repository's gemspec declares the Rails and Active Admin dependencies, while the package metadata reports the same project version, 0.1.0. Because the gem is not currently published to RubyGems, a real application may need to point Bundler at the source repository or use a locally built gem until a package is released. Do not assume that the short gem name resolves from RubyGems today.

Connect the stylesheet and JavaScript

The README asks you to replace the default Active Admin stylesheet import in app/assets/stylesheets/active_admin.scss:

// Remove the default Active Admin base stylesheet
// @import "active_admin/base";

// Load the AAA theme
@import "active_admin/aaa_theme";

Then load the theme JavaScript from your Active Admin entrypoint:

import "active_admin/aaa_theme";

The JavaScript is intentionally small. On DOMContentLoaded, it looks for Active Admin's #header, creates a button with the aaa-menu-toggle class, and toggles menu-open on the header when the button is clicked. It also closes the menu when a click happens outside the header. You can inspect this behavior in the theme JavaScript source.

This means the import is not decorative. If the stylesheet loads but the JavaScript entrypoint does not, desktop styling can appear correct while the mobile navigation remains incomplete.

Customize the design tokens

The theme defines CSS custom properties under :root. Put your overrides after the theme import so your application stylesheet wins in the cascade:

@import "active_admin/aaa_theme";

:root {
  --aaa-primary-h: 260;
  --aaa-primary-s: 85%;
  --aaa-primary-l: 55%;
  --aaa-border-radius-lg: 8px;
  --aaa-font-family: "Helvetica Neue", Arial, sans-serif;
}

The current README documents tokens for the primary color, page and card backgrounds, primary text, medium and large radiuses, and body and display font stacks. The source stylesheet also defines transition values, sidebar width, border colors, shadows, and status colors. This gives you two useful levels of customization:

1. Change a few variables to match an existing product identity.
2. Fork or extend selectors only when the structure itself needs to change.

Start with tokens. Selector overrides are more coupled to Active Admin's generated HTML and are therefore more likely to need maintenance after an Active Admin upgrade.

Understand dark mode before overriding colors

The theme has two dark-mode paths. First, a prefers-color-scheme: dark media query changes background, text, border, shadow, and primary-lightness variables. Second, body.dark applies a similar palette when your application explicitly adds the class.

That gives you a simple verification matrix:

• Light system preference with no dark class.
• Dark system preference with no dark class.
• Light preference with body.dark.
• A mobile viewport with the menu closed and open.

Do not override only --aaa-bg-base and assume dark mode is handled. Check text, borders, focus rings, links, flash messages, tables, and form controls as well. A readable dashboard can still have an inaccessible input or a low-contrast action link.

Verify the result reproducibly

Run the normal dependency and application setup commands documented by your Rails application. If you are using the repository's dummy application, its contribution guide points to the standard Rails database setup and server commands.

After the application boots, verify the theme in the browser:

1. Open an Active Admin index page with a table and filters.
2. Confirm that the stylesheet import changes the sidebar, title bar, cards, tables, and controls.
3. Use browser developer tools to inspect :root and confirm that your overridden --aaa-* values are active.
4. Switch the operating system or browser color preference to dark and repeat the inspection.
5. Reduce the viewport below the theme's mobile breakpoint and click the generated menu button.
6. Click outside the header and confirm that the menu closes.

For a source-level check, compare your built asset output with the theme's SCSS entrypoint and JavaScript entrypoint. This catches a missing import without confusing it with a CSS specificity issue.

Failure modes and tradeoffs

The gem cannot be found

The repository currently has no RubyGems release even though the README includes a Gem Version badge. Check the package source before debugging Bundler. Until a release exists, use the source repository or a locally built gem according to your organization's dependency policy.

The menu button does not appear

Check that the JavaScript import is part of the entrypoint loaded by the Active Admin layout. The script exits without creating a button when it cannot find #header, so a wrong page, an earlier script failure, or a changed Active Admin layout can all produce the same symptom.

The color override has no effect

Confirm that the override is loaded after the theme and that the variable name is exact. Inspect the computed value rather than only searching the source file. A selector that sets a concrete color can also win over a variable-based declaration.

A table becomes hard to use on mobile

The theme adds responsive behavior, but it cannot make every wide Active Admin table fit a narrow screen. Test real resources with realistic column names and action links. Keep horizontal scrolling available where the data cannot be meaningfully collapsed.

Security boundaries

This theme changes CSS, HTML-adjacent behavior, and a small client-side menu controller. It does not provide authorization, secure sessions, CSRF protection, input validation, or protection from unsafe Active Admin resource definitions. Continue to use Rails and Active Admin security controls, review the generated asset policy, and treat third-party font loading as a separate privacy and availability decision.

The README imports Google Fonts in the theme stylesheet. If your admin area must remain self-contained or avoid third-party requests, remove that import and provide local font fallbacks. The theme's MIT license permits reuse subject to its license terms, but it does not turn the project into a security-reviewed dependency.

FAQ

Does this replace Active Admin?

No. It is a theme gem that styles an existing Active Admin installation.

Can I use my own brand colors?

Yes. The documented CSS custom properties are the intended starting point for primary colors, typography, radiuses, and related visual values.

Does dark mode require a JavaScript framework?

No. Automatic dark mode uses the CSS media query, and manual dark mode uses a dark class on the body. The small JavaScript entrypoint is for the responsive navigation toggle.

Is version 0.1.0 a stable release?

No. It is the version declared in the repository's source. There is no published GitHub release or RubyGems package to treat as a stable distribution.

Takeaway

The practical value of Active Admin AAA Theme is its tokenized boundary: install the theme once, keep application-specific branding in your own stylesheet, and verify desktop, dark mode, and mobile behavior as separate states. That approach makes visual customization easier to review and gives you a clear place to look when an upgrade changes the admin markup.

If you try this pattern, which token or Active Admin component would you want the theme to expose next: navigation spacing, table density, form controls, or accessibility-focused color presets?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. Project facts, examples, limitations, and links were checked against the public repository sources listed in the article on October 10, 2026.