LLM Best Practices

Custom Property

2 min read

View markdown source

Definition

A CSS custom property is any property whose name begins with two hyphens (--). Its value is an arbitrary token sequence. The value is consumed by the var() function with an optional fallback: var(--color-primary, navy). Custom properties inherit through the DOM like color and font-size; setting --spacing-base: 8px on :root makes it available everywhere unless overridden on a descendant.

Custom properties are resolved at computed-value time, not parse time, so their value can change at runtime (via JavaScript element.style.setProperty('--hue', '220')) or in a media query or container query, enabling runtime theming without class toggling.

Unlike Sass variables, custom properties are live in the browser. A prefers-color-scheme media query can swap the entire theme by redefining a handful of custom properties on :root, and every var() reference updates automatically.

Custom properties follow the standard cascade rules (specificity, then source order) like regular properties.

When it applies

Use custom properties for design tokens (colors, spacing, border radius, typography). Define them on :root for global values; override on a component root for scoped values. Prefer @property to declare typed custom properties (color, length, integer) when you need transitions or type safety.

Example

:root {
  --color-bg: #fff;
  --color-text: #111;
  --radius-card: 8px;
}
 
@media (prefers-color-scheme: dark) {
  :root { --color-bg: #111; --color-text: #fff; }
}
 
.card {
  background: var(--color-bg);
  color: var(--color-text);
  border-radius: var(--radius-card);
}
  • cascade - custom properties inherit and cascade like standard properties.
  • specificity - specificity determines which custom property declaration wins.
  • has-selector - style container queries read custom property values via :has() patterns.
  • container-query - @container style() queries check custom property values.
  • tailwind - Tailwind 4 uses CSS custom properties for its design tokens.

Citing this term

See Custom Property (llmbestpractices.com/glossary/custom-property).

Graph View

Backlinks