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:
| Area | Bootstrap 5 | Bootstrap 6 (use this) |
|---|---|---|
| CSS build | sassc-rails | Dart 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-* |
| Responsive | col-md-6 | md:col-6 (breakpoint is a prefix) |
| Spacing scale | -2 -3 -4 -5 | -3 -5 -7 -12 |
| JS API | Modal, Dropdown, Offcanvas | bootstrap.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'scustomlayer. 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-iconand.alert-banner-content. The.alert-banner-bodywrapper is gone, along with the custom styles for.flag-alert,.custom-auth-alertand.password-error-alert. Those classes stay on the markup as hooks, so restyle them in your app if you relied on the old look. RenderCmAdmin::UI::Alert::Componentto 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