CSS
How the CSS works
One Tailwind source file your own build compiles, in the components layer, coloured from your palette.
The gem ships no compiled stylesheet. Every component's look is Tailwind CSS v4 source in one file,
app/assets/tailwind/unmagic_components/engine.css, and your app's own Tailwind build compiles
it with your theme. That's why Tailwind v4 is required, and why the components pick up your colours, radii
and dark mode without any setup.
What's in the file
The Ruby renders stable class names (UnmagicCard, UnmagicInput) and the file gives
those classes their look, mostly with @apply:
@layer components {
.UnmagicBadge {
@apply inline-flex items-center gap-1 rounded-full bg-neutral-100 px-2 py-0.5 text-xs font-medium whitespace-nowrap text-neutral-600;
@apply dark:bg-neutral-800 dark:text-neutral-400;
}
}Because the styles hang off the gem's own classes, Tailwind doesn't have to scan the gem's Ruby for class names. Tailwind always outputs rules written in a CSS layer, so every component's styles are in your build whether a page uses them or not.
Importing it
With tailwindcss-rails, the first build writes an entry point for the file. Import it after Tailwind:
/* app/assets/tailwind/application.css */
@import "tailwindcss";
@import "../builds/tailwind/unmagic_components";
With the Tailwind CLI or an npm build, import engine.css by its path inside the installed gem
(bundle show unmagic-components).
Overriding a style
Every rule sits in @layer components, which comes before Tailwind's utilities. So a utility
you pass through class: wins over the gem's own style, whatever its specificity:
<%= card title: "Members", class: "rounded-none shadow-none" do %>…<% end %>CSS you write outside a layer beats every layer, so a rule of your own for a gem class wins too. Use this to change a component everywhere at once:
.UnmagicCard {
@apply rounded-sm shadow-none;
}For colours, radii, fonts and dark mode, change your theme instead, and every component follows. See Theming and Colours and variables.