CSS Variables

We use several CSS variables that you can override to customize your site. You can create multiple classes that set these variables and switch between them to create multiple themes. When overriding color variables, be sure to use the light-dark() CSS function in order to preserve the light/dark theme functionality.

This is a reference of all the variables you can set on the root <html> element. There are a few more that are used with specific components or utility classes; these are grouped together at the bottom, in addition to being mentioned in the documentation for their respective class or component.

Contents:

§ Colors

--bg: Page background.
--fg: The text color.
--link-fg: The color used for hyperlinks. Defaults to --accent.
--muted-fg: Text color for disabled or de-emphasized elements. It's important that this color is readable against all of the background colors.
--faded-fg: Text for disabled interactive components.
--graphical-fg: Graphical elements like borders. Not text.
--box-bg: Background for blocks: cards, admonitions etc.
--interactive-bg: Background for interactive elements.
--pressed-interactive-bg: Background for interactive elements with aria-pressed=true or aria-expanded=true.
--accent: Accent color. It's important that this color is readable against all of the background colors.
--muted-accent: Less vivid version of accent color. Will not be used for text.

§ Colorways

--plain-fg: Foreground color for the .plain colorway.
--info-fg: Foreground color for the .info colorway.
--ok-fg: Foreground color for the .ok colorway.
--bad-fg: Foreground color for the .bad colorway.
--warn-fg: Foreground color for the .warn colorway.
--plain-graphical-fg: Graphical elements (i.e. borders) color for the .plain colorway.
--info-graphical-fg: Graphical elements (i.e. borders) color for the .info colorway.
--ok-graphical-fg: Graphical elements (i.e. borders) color for the .ok colorway.
--bad-graphical-fg: Graphical elements (i.e. borders) color for the .bad colorway.
--warn-graphical-fg: Graphical elements (i.e. borders) color for the .warn colorway.
--plain-bg: Background color for the .plain colorway.
--info-bg: Background color for the .info colorway.
--ok-bg: Background color for the .ok colorway.
--bad-bg: Background color for the .bad colorway.
--warn-bg: Background color for the .warn colorway.

§ Lengths

~~--rhythm~~: ~~Vertical rhythm, line height.~~ Deprecated: Will be removed in version 2.0. Set a value for the line-height property on the html element instead.
--line-length: Maximum line length for prose.

§ Borders

--border-width: Shortcut for uniform border widths on various .box related components. Defaults to unset.
--border-block-start-width: Width of the "top" border. Defaults to --border-width if it is set, otherwise 1px.
--border-block-end-width: Width of the "bottom" border. Defaults to --border-width if it is set, otherwise 1px.
--border-inline-start-width: Width of the "left" border. Defaults to --border-width if it is set, otherwise 1px.
--border-inline-end-width: Width of the "right" border. Defaults to --border-width if it is set, otherwise 1px.
--border-style: Shortcut for uniform border styles on various .box related components. Defaults to unset.
--border-block-start-style: Style of the "top" border. Defaults to --border-style if it is set, otherwise 1px.
--border-block-end-style: Style of the "bottom" border. Defaults to --border-style if it is set, otherwise 1px.
--border-inline-start-style: Style of the "left" border. Defaults to --border-style if it is set, otherwise 1px.
--border-inline-end-style: Style of the "right" border. Defaults to --border-style if it is set, otherwise 1px.
--border-radius: Border radius for various .box related components. Accepts any valid CSS value, e.g. 1em 2em or 50% 20% / 10% 40%. Defaults to 0.2rem.
--interactive-border-width: Border width used in buttons, inputs, etc. Must be a single value; defaults to 1px.
--interactive-border-style: Border style used in buttons, inputs, etc. Must be a single value; defaults to solid.
--interactive-border-radius: Border radius used in buttons, inputs, etc. Must be a single value; defaults to 0.2rem.
--tab-border-radius: Border radius for the ARIA tabs component. Must be a single value; defaults to 0.4em.

§ Button Shadows

--shadow: The value for the box-shadow property on buttons.
--shadow-focus: The value for the box-shadow property on button with :hover or :focus-visible state.
--shadow-active: The value for the box-shadow property on button with :active state.
--shadow-disabled: The value for the box-shadow property on button with :disabled state.
--pressed-shadow: The value for the box-shadow property on buttons with aria-pressed=true or aria-expanded=true.
--pressed-shadow-focus: The value for the box-shadow property on buttons with aria-pressed=true or aria-expanded=true in the :hover or :focus-visible state.
--pressed-shadow-active: The value for the box-shadow property on buttons with aria-pressed=true or aria-expanded=true in the :active state.

§ Fonts

--main-font

The main font family for text.

--secondary-font

A secondary text font. It's a good idea to specify a sans-serif font as it will be used for buttons and captions.

--display-font

A display font used for headings.

--mono-font

Monospace font for code, preformatted text, computer input and output.

Tip: Browsers shrink monospace fonts. You can suppress this behavior by specifying monospace twice:

--mono-font: "Cascadia Code", monospace, monospace

§ Markers

--breadcrumb-page: The default separator for breadcrumbs.
--breadcrumb-step: The separator for breadcrumbs that use aria-current=step.

§ Density

--density: The amount of space between elements (i.e. gaps between paragraphs, padding of boxes), as a multiplier of the root line height. See Utilities / Density.

§ Component-specific variables

--flex-switch-threshold: Sets the threshold at which .flex-switch switches from row to column. Default is 15ch.
--col-width: Sets the width of a column for .textcolumns. Default is 30ch.
--grid-row-width: Sets the width of a row in a .grid. Default is 1fr.
--grid-col-width: Sets the width of a column in a .grid. Default is 1fr.