Skip to main content
Version: 11.14.0

CSS Variables & Theming

Mint uses a three-layer theming system built on CSS custom properties and Tailwind CSS v4. Understanding this architecture makes it straightforward to apply your own branding.

Architecture Overview​

src/themes/chapsvision.css          src/theme.css
─────────────────────────           ─────────────────────────────
Layer 1 · Color Palette             Layer 3 · Tailwind Mapping
  @theme {                            @theme inline {
    --color-sage-800: #445556;          --color-primary: var(--primary);
    --color-pink-200: #efc9f3;          --color-accent:  var(--accent);
    ...                                 ...
  }                                   }
                                    ↓
Layer 2 · Semantic Tokens           Tailwind utility classes
  :root {                             bg-primary, text-accent,
    --primary: var(--color-sage-800);  border-secondary, ...
    --accent:  var(--color-pink-200);
    ...
  }
  .dark {
    --primary: var(--color-sage-200);
    ...
  }
LayerFilePurpose
1 – Color Palettesrc/themes/chapsvision.css (@theme block)Raw color scales (--color-sage-*, --color-pink-*, …). These are the building blocks.
2 – Semantic Tokenssrc/themes/chapsvision.css (:root / .dark)Maps palette colors to roles (--primary, --accent, --sidebar, …). Change these for branding.
3 – Tailwind Mappingsrc/theme.css (@theme inline)Exposes semantic tokens as Tailwind utilities (bg-primary, text-accent, …). Do not edit unless adding new utilities.

Customizing Your Branding​

To apply custom branding, override the semantic tokens (Layer 2) in your own CSS file — you never need to touch chapsvision.css directly or re-declare the full palette.

Minimal Override​

Create or edit src/styles/custom-theme.css (imported after theme.css):

:root {
  /* Your brand primary color */
  --primary: #1a56db;
  --primary-foreground: #ffffff;

  /* Your brand accent color */
  --accent: #e0f2fe;
  --accent-foreground: #0c4a6e;

  /* Sidebar & header */
  --sidebar: #1e3a5f;
  --header: #1e3a5f;
}

.dark {
  --primary: #93c5fd;
  --accent: #1e3a5f;
}

Key Tokens for Branding​

TokenRoleLight default
--primaryMain brand color (buttons, links, active states)
#445556
--primary-foregroundText/icon on primary backgrounds
#f5f8f7
--accentHighlights, selections, badges
#efc9f3
--accent-foregroundText on accent backgrounds
#6c467b
--secondarySecondary buttons and surfaces
#e8f0ee
--sidebarSidebar background
#2d393a
--sidebar-foregroundSidebar text and icons
#d1e1dd
--headerTop header bar background
#374648
--header-foregroundHeader text and icons
#f5f8f7
--backgroundPage background
#fdfefe
--foregroundDefault text color
~#1e1e27

Light & Dark Mode​

Mint uses a class-based dark mode — the .dark class is applied to the <html> element. The semantic tokens are declared twice:

  • :root → light mode values
  • .dark → dark mode overrides
:root {
  --primary: var(--color-sage-800); /* #445556 */
}

.dark {
  --primary: var(--color-sage-200); /* #d1e1dd */
}

When overriding, always provide both blocks to keep dark mode working correctly.

Chrome light-dark() workaround

The CSS light-dark() function has a bug in Chrome (as of early 2026). Avoid using it for semantic token values. Use explicit :root / .dark declarations instead, as done throughout chapsvision.css.

Tailwind Utilities​

Once defined in src/theme.css, every semantic token becomes available as Tailwind classes:

Semantic tokenTailwind classes generated
--primarybg-primary, text-primary, border-primary, ring-primary
--primary-foregroundbg-primary-foreground, text-primary-foreground, …
--accentbg-accent, text-accent, …
--sidebarbg-sidebar, text-sidebar, …
--destructivebg-destructive, text-destructive, …

The full mapping is in src/theme.css inside the@theme inline` block.

Full Semantic Token Reference​

Core Colors​

TokenLight valueDark valueTailwind utility
--background
--color-gray-50
--color-sage-975
bg-background
--foregroundoklch(0.141…)oklch(0.985…)text-foreground
--borderoklch(0.922…)oklch(1 0 0 / 10%)border-border
--input
--color-gray-50
--color-sage-950
bg-input
--ringaccent color—ring-ring
--muted
--color-gray-200
--color-sage-950
bg-muted
--muted-foregroundoklch(0.552…)--color-neutral-300text-muted-foreground

Primary​

TokenLight valueDark valueTailwind utility
--primary
--color-sage-800
--color-sage-200
bg-primary / text-primary
--primary-foreground
--color-sage-50
--color-sage-300
text-primary-foreground
--primary-hovered
--color-sage-950
--color-sage-900
bg-primary-hovered
--primary-pressed
--color-sage-300
--color-sage-700
bg-primary-pressed
--primary-activeprimary color
--color-sage-600
bg-primary-active
--primary-disabled
--color-disabled
--color-sage-800
bg-primary-disabled
--primary-light
--color-sage-200
--color-sage-700
bg-primary-light
--primary-lighter
--color-sage-100
--color-sage-900
bg-primary-lighter
--primary-lightest
--color-sage-50
--color-sage-950
bg-primary-lightest

Secondary​

TokenLight valueTailwind utility
--secondary
--color-sage-100
bg-secondary
--secondary-foreground
--color-sage-900
text-secondary-foreground
--secondary-hovered
--color-sage-100
bg-secondary-hovered
--secondary-pressed
--color-sage-200
bg-secondary-pressed
--secondary-light
--color-almond-200
bg-secondary-light
--secondary-lighter
--color-almond-100
bg-secondary-lighter
--secondary-lightest
--color-almond-50
bg-secondary-lightest

Accent​

TokenLight valueDark valueTailwind utility
--accent
--color-pink-200
(inherited)bg-accent / text-accent
--accent-foreground
--color-pink-900
—text-accent-foreground
--accent-alt
--color-pink-200
--color-pink-700
bg-accent-alt
--accent-hovered
--color-pink-100
--color-pink-500
bg-accent-hovered
--accent-pressed
--color-pink-900
--color-pink-800
bg-accent-pressed

Status Colors​

TokenLight valueForeground tokenTailwind utility
--success
--color-green-200
--success-foreground →
--color-green-800
bg-success
--warning
--color-orange-200
--warning-foreground →
--color-orange-800
bg-warning
--info
--color-blue-200
--info-foreground →
--color-blue-800
bg-info
--error
--color-red-200
--error-foreground →
--color-red-800
bg-error
--destructiveoklch(0.577…) ≈
red
--destructive-foregroundbg-destructive

Layout – Sidebar​

TokenLight valueDark valueTailwind utility
--sidebar
--color-sage-950
--color-sage-900
bg-sidebar
--sidebar-foreground
--color-sage-200
--color-sage-100
text-sidebar-foreground
--sidebar-accent30% opacity sage-80030% opacity sage-975bg-sidebar-accent
--sidebar-active
--color-sage-700
--color-sage-975
bg-sidebar-active
--sidebar-border
--color-sage-900
white 10%border-sidebar-border
--sidebar-ring
--color-pink-400
--color-pink-700
ring-sidebar-ring

Layout – Header & Card​

TokenLight valueTailwind utility
--header
--color-sage-900
bg-header
--header-foreground
--color-sage-50
text-header-foreground
--card
--color-almond-50
bg-card
--card-foreground
--color-almond-950
text-card-foreground
--popover
white
bg-popover
--aside
--color-sage-50
bg-aside
--aside-border
--color-sage-200
border-aside-border

Tooltip​

TokenLight valueTailwind utility
--tooltip
--color-gray-700
bg-tooltip
--tooltip-foreground
--color-gray-50
text-tooltip-foreground

AI & Assistant​

TokenLight valueDescription
--ai-from
--color-blue-500
AI gradient start
--ai-via
#6c5ce7
AI gradient mid
--ai-to
#8a3bff
AI gradient end
--ai-foregroundwhiteText on AI gradient
--ai-border--borderAI card border
--assistant
#ff732e
Assistant brand color
--gradient-namelinear-gradient(93deg, #1B97BF, #8A3BFF)Animated name gradient

Effects & Backdrop​

TokenDefault valueDescription
--backdropoklch(from foreground l c h / 50%)Dialog/modal overlay color
--backdrop-filterblur(2px)Frosted-glass blur on modal backdrop
--drawer-box-shadow-10px 0px 10px rgba(0,0,0,0.1)Side drawer shadow

Z-index Reference​

Defined in src/theme.css under @theme inline:

TokenValueTailwind utility
--z-menu100z-menu
--z-popover100z-popover
--z-dropdown100z-dropdown
--z-backdrop1000z-backdrop
--z-drawer2000z-drawer
--z-multiselection2050z-multiselection
--cdk-z-index-overlay5000— (CDK internal)

Typography & Spacing​

TokenValueDescription
--radius0.65remDefault border radius
--radius-sm0.5remSmall border radius
--radius-button100vwPill-shaped button radius
--text-2xs10pxExtra-small font size

Color Palette Reference​

The full color scales are defined in src/themes/chapsvision.css inside the @theme block and are available as Tailwind utilities (bg-sage-800, text-pink-200, etc.):

ScaleStepsCrown color (recommended for primary)
sage50 → 975
sage-800
almond50 → 950
almond-100
pink50 → 950
pink-200
green50 → 950
green-600
orange50 → 950
orange-600
red50 → 950
red-600
blue50 → 950
blue-600
gray50 → 950
gray-600
yellow50 → 950
yellow-600
cherry50 → 950
cherry-600
indigo50 → 950
indigo-600
cyan50 → 950
cyan-600

Crown colors (👑 in the source file) are the recommended choices when picking a single representative color from each scale.