Theming

Any colour you like, as long as it's yours. Change the brand colour, add your own tones and switch to dark mode.

Components never hard-code a colour. They read colour tokens with the usual names, --primary, --background, --border and so on, written in OKLCH. Every fill comes with a foreground meant to sit on it. In dark mode the fills turn light and their foregrounds dark, so --primary works as a button fill and as link text, in either theme.

Success, warning and info are the exception. A green, amber or sky blue dark enough to carry white text turns olive, brown and navy, so in light mode their fills stay bright under dark text. For text on the page, use --success-text, --warning-text and --info-text: text-warning-text, not text-warning.

Components read these tokens but never set them, so any theme with these names works. The values below are Kappa UI's own, from the theme item. They're read live from this page, so the theme toggle changes them too.

Each card lists the WCAG contrast of its pairs, as rendered in the theme shown. Text needs 4.5:1 and control borders 3:1. Between 3:1 and 4.5:1 is only enough for large text.

--brand

Seed colour; --primary and --ring take its hue and chroma

Aa

--primary

--primary-foreground

Brand fill and label; brand-coloured text on the page

Aa

--background

--foreground

Page and outline fill; inherited text colour; disabled colour

Aa

--secondary

--secondary-foreground

Soft neutral fill

Aa

--destructive

--destructive-foreground

Destructive actions and errors

Aa

--success

--success-foreground

Fill for confirming actions and success states

--success-text

Success-coloured text, borders and tints on the page

Aa

--warning

--warning-foreground

Fill for actions and states that need care

--warning-text

Warning-coloured text, borders and tints on the page

Aa

--info

--info-foreground

Fill for notices and tips

--info-text

Info-coloured text, borders and tints on the page

Aa

--muted

--muted-foreground

Subdued surfaces and text

Aa

--accent

--accent-foreground

Skeleton fill and completed Stepper steps

Aa

--card

--card-foreground

Card surface and text

Aa

--dialog

--dialog-foreground

Dialogs, alert dialogs and drawers

Aa

--popover

--popover-foreground

Menus, select lists, popovers, hover cards and toasts; a step above dialogs in the dark theme

--input

Borders of controls; 3:1 against the page

--border

Decorative borders and dividers

--ring

Focus ring, drawn at 50% opacity

Brand colour

Want your own brand colour? Change one value:

:root {
  --brand: oklch(0.6 0.2 150);
}

--primary and --ring follow --brand, but take only its hue and chroma. The lightness is fixed per theme, so white text on --primary stays above 4.5:1 whatever hue you pick.

Hue and chroma in, lightness fixed
--brandoklch(0.9 0.15 95)--primary
--brandoklch(0.6 0.2 150)--primary
--brandoklch(0.35 0.12 25)--primary
--brandoklch(0.7 0.2 320)--primary

Rather click than type? The palette button in the header opens the theme customiser. Pick a colour and a neutral, a density, a radius and a font, then how surfaces, borders, shadows and the status colours look, and press Copy CSS.

The derivation needs relative colour syntax: Chrome 119, Safari 18, Firefox 128 or later. Older browsers fall back to the static values in :root and .dark, which match the default blue. Supporting them? Update those static values too.

--brand only works where --primary is declared, on :root and .dark. Setting it on an element further down changes nothing, unless you redeclare the derived tokens on the same selector.

Tones

A tone is the colour a component is drawn in, picked with its color prop. color="success" sets data-color="success" on the root, and that turns into the variables every variant, the component's look, reads. Three variables are inputs. The other four are derived from them, and you can override those too.

What each variant reads
solid
--tone fill --tone-foreground text
soft
--tone-soft fill --tone-soft-foreground text
subtle
--tone-soft fill --tone-soft-foreground text --tone-border-subtle edge
outline
--tone-text text --tone-border edge
ghost
--tone-text text
link
--tone-text text
VariableValueRole
--toneinputFills: the solid variant, a checked box, a switch that's on, the active step.
--tone-foregroundinputText and icons on that fill.
--tone-textinputText, lines and marks in this colour on the page: outline, ghost, link, the toast icon, checked edges and dots, the slider and progress bars, the tab line, and the focus ring of a control in a colour other than primary.
--tone-soft12% of --tone over transparentThe fill of soft and subtle.
--tone-soft-foreground--tone-textText on the soft fill.
--tone-border--tone-textThe edge of outline.
--tone-border-subtle25% of --tone-border over transparentThe edge of subtle.

The built-in tones read the tokens above:

  • primary and destructive use their pair, with the fill doubling as the text colour.
  • success, warning and info write their text in --success-text, --warning-text and --info-text.
  • neutral fills with --foreground, softens with --secondary and draws its edges in --input.

Switch, Checkbox, Radio and Slider take color too, with four differences:

  • What they draw straight on the page, such as a checked edge, the radio's dot and the slider's range, takes --tone-text. A control needs 3:1 against the page, and the bright success, warning and info fills fall short of it. A fill with something on it, like the checked box or the track of a switch that's on, keeps --tone.
  • The edge stays --input while unchecked, so empty controls in a form look alike whatever their colours.
  • An invalid control turns destructive, whatever its color, so an error always looks like one.
  • Keyboard focus rings a primary control in --ring, as everywhere else, and any other in its --tone-text, which turns destructive along with the rest of an invalid control. The ring matches the control it surrounds.

CheckboxGroup and RadioGroup pass their color to every control in them that has none of its own. Progress, the line indicator of Tabs and the active step of a Stepper take color as well. The progress bar and the tab line sit on the page, so they're drawn in --tone-text; the step's indicator is a fill.

Rating, Calendar and RangeCalendar take color on the same terms. A Rating's stars fill with --tone inside a --tone-text edge. A calendar's selected day and a range's two ends fill with --tone, today's outline is --tone-text and the band between the ends is --tone-soft. All three turn destructive when invalid.

Your own tone

Three tokens and one rule. Declare the tokens per theme, next to the rest of your theme, then map them in the base layer:

:root {
  --pro: var(--color-violet-600);
  --pro-foreground: var(--color-violet-50);
  --pro-text: var(--color-violet-700);
}
.dark {
  --pro: var(--color-violet-400);
  --pro-foreground: var(--color-violet-950);
  --pro-text: var(--color-violet-300);
}

@layer base {
  [data-slot][data-color='pro'],
  [data-slot][data-state='on'][data-active-color='pro'],
  [data-slot][aria-pressed='true'][data-active-color='pro'] {
    --tone: var(--pro);
    --tone-foreground: var(--pro-foreground);
    --tone-text: var(--pro-text);
  }
}
<Button color="pro">Upgrade</Button>
<Badge color="pro" variant="soft">Pro</Badge>
<Alert color="pro" variant="subtle">Your trial ends in 3 days.</Alert>
<Switch color="pro" aria-label="Pro features" />

The last two selectors cover active-color on Toggle and ToggleGroup, which take the tone while pressed.

Keep the rule in @layer base, where the built-in tones live. A rule outside any layer beats every utility, so an invalid Switch or Checkbox in your colour would keep it instead of turning destructive.

Keep [data-slot] in the selector too. The derived values live on [data-slot][data-color], and a less specific rule can't override them. To override one, add it to the same rule, such as --tone-soft: var(--color-violet-50) when the design has its own tint.

Got a scale from 50 to 950, from Tailwind or a design file? Map it like this:

LightDark
--tone600400
--tone-foregroundwhite or 50950
--tone-text700300

Your own elements can join in. Give one data-slot and data-color, and bg-tone-soft, text-tone-text and the other tone-* colours work on it and its children.

Just one component? Skip the rule and set the inputs in its class: class="[--tone:var(--color-pink-500)] [--tone-foreground:white] [--tone-text:var(--color-pink-700)]".

Dark mode

Want dark mode? Add the dark class to <html>.

The theme puts the light values on :root and the dark ones on .dark. Components read tokens only, with no dark: utilities: the tokens change value under .dark, and every variant follows. .dark works on any element, not only <html>, so one part of a page can go dark on its own:

One markup, two classes
:root

Notifications On

Email me when someone replies.

Weekly digest
.dark

Notifications On

Email me when someone replies.

Weekly digest

The theme also sets color-scheme: dark under .dark, so the browser's own controls, such as date pickers and scrollbars, turn dark with it.

The shadcn-vue CLI adds this variant to your stylesheet at init and on every add, unless the stylesheet already declares a custom variant:

@custom-variant dark (&:is(.dark *));

From then on your own dark: utilities follow the .dark class too. To keep them on prefers-color-scheme, remove that line. Kappa UI's colours switch with .dark either way.

Using Nuxt? @nuxtjs/color-mode with classSuffix: '' sets exactly this class. That's how this site switches.

States and shape

Hover and press show as a translucent layer of the button's own text colour, so no variant needs a hover colour of its own. A disabled button takes its colours from --foreground, whatever its variant. Pressable parts also carry the ripple, which uses the same pressed opacity and takes over the press.

Keyboard focus is a 3px outline in --ring at half strength, outside the element. Switch, Checkbox, Radio and Slider in a colour other than primary draw it in their --tone-text instead, and so does a focused card of a CheckboxGroup or RadioGroup in one. Being an outline, it leaves the element's shadow alone and stays visible in forced colours mode. Use it in your own components too: focus-visible:focus-ring, or focus-ring-inset to draw it inside. To draw one element's ring in another colour, set --focus-ring-color on it, as AlertClose does with [--focus-ring-color:currentColor].

Corners come in three roles, controls, surfaces and items, each scaled from --radius and tunable on its own. Radius lists them, with a playground.

Surfaces are the panels that sit on or above the page: cards, dialogs, menus, popovers and select lists. A menu opens on a card or in a dialog, never the other way round, so --popover sits a step above --dialog in the dark theme, and its shadow carries an edge, so a menu stays apart from whatever it opens on. Want a hairline around every surface? Set --surface-border to var(--border).

VariableDefaultDescription
--state-hover8%Opacity of the layer under the pointer.
--state-pressed12%Opacity of the layer, or of the ripple, while pressed.
--state-selected8%Opacity of the tint under a selected option, list item or choice card. A choice group tints in its own color.
--disabled-opacity38%Opacity of --foreground for disabled text and icons.
--disabled-container-opacity12%Opacity of --foreground for disabled fills and outlines.
--scrimoklch(0 0 0 / 40%)The dimmed layer behind a modal dialog; 60% in the dark theme.
--surface-bordertransparentBorder colour of cards, dialogs, menus, popovers and select lists. The default theme draws them without one; set it to var(--border) for a hairline. The width is always there, so nothing moves. Set it on :root for every surface or on one element for that one.
--shadow-xs … --shadow-xlTailwind's shadow-xs … shadow-xlElevation of slider thumbs and the pill tab indicator, drawn with shadow-shadow-xs to shadow-shadow-xl. In the light theme the two role shadows below build on --shadow-lg and --shadow-xl. The shadcn-vue CLI mirrors these tokens into @theme inline, so Tailwind's own shadow-* classes draw them too, and shadow colour classes such as shadow-primary/30 have no effect on them.
--shadow-popovera 1px ring and --shadow-lg; in the dark theme a highlight, two rings and a four-layer dropEdge and shadow of menus, select lists, popovers, hover cards and toasts, drawn with shadow-shadow-popover. Set it to var(--shadow-lg) for a plain shadow without the edge.
--shadow-dialoga 1px ring and --shadow-xl; in the dark theme a highlight, two rings and a five-layer dropEdge and shadow of dialogs and alert dialogs, drawn with shadow-shadow-dialog. Set it to var(--shadow-xl) for a plain shadow without the edge.
--radius0.5remBase corner radius, part of the theme item and of shadcn's own theme. --radius-xs to --radius-4xl (from theme) and the control, surface and item roles (from tokens, so they work without the theme) are multiples of it, so 0 squares every corner. [Radius](/docs/getting-started/radius) lists them.

Next

  • Typography: the type roles and how to change them.
  • Sizing: heights, padding and gaps.