Styling

How the theme is layered, which tokens exist, and what to override.

Overview

Every Mako component is styled with semantic design tokens — bg-primary, text-muted-foreground, border-border — never raw palette classes. Retheming the library is therefore a matter of redefining CSS variables, not patching components.

Importing mako-ui/globals.css after Tailwind gives you the whole system. See Get Started for the setup.

How the theme is layered

The stylesheet is built in three layers, and which one you touch determines how far the change reaches.

1. Rubix primitives (--mako-*). The raw brand scale: 80 color steps (--mako-color-blue-700, --mako-color-neutral-200, …, each ramp from 10 to 950), plus spacing, radii, shadows, breakpoints, font sizes, line heights and z-indexes. These are plain custom properties — they do not generate Tailwind utilities. Read them when you need an exact brand value.

2. Semantic tokens. --primary, --muted-foreground, --border and friends, each pointing at a primitive. This is the layer you override.

3. Tailwind utilities. A @theme inline block maps every semantic token to a Tailwind namespace, so --primary becomes bg-primary / text-primary, --radius becomes rounded-lg, and so on. A second @theme block points Tailwind's blue, yellow, green, red, purple and neutral ramps at the Rubix palette, so bg-blue-500 is a Rubix blue — see Colors.

Two reference pages cover the layers in full: Colors for the palette and all 47 color tokens, and Typography for the type scale and font variables.

Most --mako-* primitives are reference values only

Outside of the color ramps, no Mako component uses them and none generate utilities. Components are built on Tailwind's own spacing, shadow and z-index scales — so --mako-breakpoint-md (768px) happening to match md: is a coincidence, and --mako-breakpoint-lg (992px) does not match lg: (1024px). Do not mix the two scales in one layout.

Overriding tokens

Redefine any semantic token in a :root block after the import. Everything downstream — components, utilities, variants — follows:

app/globals.css

@import "tailwindcss";
@import "mako-ui/globals.css";
 
:root {
  --primary: var(--mako-color-purple-600);
  --primary-foreground: var(--mako-color-white);
  --radius: 0.5rem;
}

Point tokens at --mako-* primitives where you can, so overrides stay inside the brand scale. Any valid CSS color works too.

--alpha() is valid Tailwind v4

Some tokens are defined as --alpha(var(--mako-color-black) / 4%). That is a Tailwind v4 theme function resolved at build time — it is not broken CSS, and it should not be "fixed" into color-mix() or rgba().

Radius and spacing

--radius (default 0.25rem) drives the four radius utilities: rounded-sm is --radius - 4px, rounded-md is --radius - 2px, rounded-lg is --radius, and rounded-xl is --radius + 4px. Change the one variable to reshape every component at once.

Two extra breakpoints are registered on top of Tailwind's defaults: 3xl (1600px) and 4xl (2000px).

Type and fonts

Components read three font variables — --font-sans, --font-mono, --font-heading — and Mako's type scale adds --mako-text-bump: 2px to every --text-* step, so text-sm renders at 16px rather than 14px. Both are semantic tokens you can redefine like any other.

Typography has the full scale, the weights, the metric overrides and the setup for Next.js and everything else.

CSS isolation setup

Portaled components (Dialog, Popover, Select, Menu, Toast…) need a stacking context to render above page content.

Application root isolation

Add isolation: isolate to your application's root wrapper. This creates a separate stacking context, so portaled content always paints above the page without z-index conflicts:

app/layout.tsx

<body>
  <div className="isolate relative flex min-h-svh flex-col">
    {children}
  </div>
</body>

iOS Safari compatibility

On iOS Safari 26+, add position: relative to <body> as well. Without it, backdrops fail to cover the visual viewport once the page has been scrolled:

app/layout.tsx

<body className="relative">
  <div className="isolate relative flex min-h-svh flex-col">
    {children}
  </div>
</body>

Skip this setup and you will hit the classic symptom: page content rendering on top of an open dialog or popover.

On This Page

Overview How the theme is layered Overriding tokens Radius and spacing Type and fonts CSS isolation setup Application root isolation iOS Safari compatibility