Skip to main content

UI

cm-admin uses Bootstrap 6 (loaded from the bootstrap npm package and compiled with Dart Sass) as its CSS foundation, wrapped inside a .cm-admin root class to ensure style isolation and prevent conflicts with the host application's styles.

Design System: CM-Admin Design System (Figma)

Core Concept: Scoped Bootstrap​

All cm-admin styles are scoped under the .cm-admin class. When creating custom components, we use SCSS @extend to inherit Bootstrap classes while keeping them namespaced:

// Don't use Bootstrap classes directly in markup
<button class="btn btn-primary btn-sm">Click</button>

// Use cm-admin scoped classes
<button class="btn-cta">Click</button>

How It Works​

@import "../helpers/index.scss";

// Custom buttons composed from Bootstrap 6 variant + theme classes
.cm-admin .btn-cta {
@extend .btn-solid, .theme-primary, .btn-sm;
}

.cm-admin .btn-primary {
@extend .btn-outline, .theme-primary, .btn-sm;
}

This pattern:

  • Isolates styles - cm-admin styles won't leak into the host app
  • Leverages Bootstrap - Full access to Bootstrap's utility classes and components
  • Enables customization - Override Bootstrap variables and add custom properties

Bootstrap 6 notes for host applications​

cm-admin moved from Bootstrap 5 to Bootstrap 6 (6.0.0-alpha.1). If your application adds its own views, styles or scripts to the admin panel, check the following. The full list of changes is in the official migration guide.

What changed that affects your custom code:

AreaBootstrap 5Bootstrap 6 (use this)
CSS buildsassc-railsDart Sass via the CSS bundler
Modals.modal + data-bs-toggle="modal"<dialog class="dialog"> + data-bs-toggle="dialog"
Dropdowns.dropdown/.dropdown-item.menu/.menu-item + data-bs-toggle="menu"
Offcanvas.offcanvas<dialog class="drawer">
Form checks.form-check.check, .radio, .switch
Selects.form-select.form-control
Text colors.text-*.fg-*
Color variants.alert-*, .bg-*.theme-*
Responsivecol-md-6md:col-6 (breakpoint is a prefix)
Spacing scale-2 -3 -4 -5-3 -5 -7 -12
JS APIModal, Dropdown, Offcanvasbootstrap.Dialog, bootstrap.Menu, bootstrap.Drawer β€” events *.bs.dialog, *.bs.menu, *.bs.drawer

Other things to know:

  • Cascade layers: Bootstrap 6 puts its CSS in @layers and its utilities no longer use !important. cm-admin styles live in Bootstrap's custom layer. Unlayered CSS from your app beats every layered rule, including utilities such as .d-none.
  • CSS variables: Compiled custom properties have no --bs- prefix (--primary-base, --border-color, --fg-body, …). Bootstrap's own component tokens (e.g. --drawer-inset) are declared outside its layers, so overriding them from a layer needs !important.
  • Alerts: Every cm-admin alert (alert_box, flash and custom action banners, form errors, import notes, auth pages) is Bootstrap 6's .alert.theme-<type> component. The icon and content sit directly inside the alert: .alert-banner-icon and .alert-banner-content. The .alert-banner-body wrapper is gone, along with the custom styles for .flag-alert, .custom-auth-alert and .password-error-alert. Those classes stay on the markup as hooks, so restyle them in your app if you relied on the old look. Render CmAdmin::UI::Alert::Component to get the same markup in custom views.
  • Custom action modals: Bootstrap 5 size classes passed through modal_configuration[:html_attrs] (modal-lg, modal-xl, …) are mapped to their Dialog equivalents automatically.
  • Color mode: cm-admin layouts set data-bs-theme="light", because Bootstrap 6 otherwise follows the operating system's dark mode.

File Structure​

app/assets/stylesheets/cm_admin/
β”œβ”€β”€ helpers/
β”‚ β”œβ”€β”€ _variable.scss # Color, typography, spacing variables
β”‚ β”œβ”€β”€ _mixins.scss # Reusable mixins (flex, font, etc.)
β”‚ β”œβ”€β”€ _typography.scss # Typography utilities and classes
β”‚ └── index.scss # Exports all helpers
β”œβ”€β”€ components/
β”‚ β”œβ”€β”€ _buttons.scss
β”‚ β”œβ”€β”€ _alerts.scss
β”‚ β”œβ”€β”€ _modal.scss
β”‚ └── ...
β”œβ”€β”€ base/ # Page-specific styles
└── dependency/
└── bootstrap/ # Bootstrap source files