Object Variable

An object variable groups key-value pairs under a single name. The syntax is one; but it is used for two different purposes:

• CSS property object — keys are CSS property names, full expansion can be done with var(--obj)
• Token object — keys are custom token names, always accessed with var(--obj.key)

The compiler handles both the same way. The distinction is in the purpose of the key contents.

---

Definition

Defined with the --name: { key: value; key: value; }; syntax.

/* CSS property object */
--cardBase: { color: #fff; font-size: 16px; };

/* Token object */
--colors: { brand: #2060ff; muted: #6b7280; surface: #f4f6fb; };

---

CSS Property Object

Keys consist of valid CSS property names. All properties of the object are expanded to where it is called with var(--obj).

--cardBase: { color: #1a1a2e; font-size: 16px; padding: 16px; };

.card {
  var(--cardBase);
  margin: 8px;
}

Generated CSS:

.card {
  color: #1a1a2e;
  font-size: 16px;
  padding: 16px;
  margin: 8px;
}

A specific key of the object can also be accessed:

--cardBase: { color: #1a1a2e; font-size: 16px; padding: 16px; };

.card-compact {
  color: var(--cardBase.color);
  font-size: var(--cardBase.fontSize);
}

Generated CSS:

.card-compact {
  color: #1a1a2e;
  font-size: 16px;
}

---

Full Expansion Inside Nesting

CSS property objects can also be used with nested blocks:

--primary: #2060ff;
--cardBase: { color: #fff; font-size: 16px; };

.card {
  var(--cardBase);

  .title {
    color: var(--primary);
  }

  .body {
    font-size: 14px;
  }
}

Generated CSS:

:root {
  --primary: #2060ff;
}

.card {
  color: #fff;
  font-size: 16px;
}

.card .title {
  color: var(--primary);
}

.card .body {
  font-size: 14px;
}

In this example var(--cardBase) does full expansion inside the parent block; nested selectors come out as normal child selectors.

---

Token Object

Keys are custom token names, not CSS property names. For this type of object, full expansion with var(--obj) should not be done — it produces invalid CSS. It must always be accessed with var(--obj.key) syntax.

--colors: { brand: #2060ff; muted: #6b7280; surface: #f4f6fb; };

.btn {
  background: var(--colors.brand);
  color: var(--colors.surface);
}

.label {
  color: var(--colors.muted);
}

Generated CSS:

.btn {
  background: #2060ff;
  color: #f4f6fb;
}

.label {
  color: #6b7280;
}

Avoid full expansion

If var(--colors) is written in a token object, key names are interpreted as CSS properties and invalid CSS is produced:

/* Wrong usage — full expansion with var(--colors) */
.btn {
  brand: #2060ff;
  muted: #6b7280;
  surface: #f4f6fb;
}

Always use var(--obj.key) for token objects.

Object variables do not take selector scope

Object variables are compile-time maps. :root.dark { --theme: {...}; } does not produce a scoped dark-theme override; the last --theme value becomes the global compile-time value.

--theme: { fg: #111; bg: #fff; };

:root.dark {
  --theme: { fg: #eee; bg: #000; };
}

.card {
  color: var(--theme.fg);
  background: var(--theme.bg);
}

The generated CSS does not include :root.dark; .card receives the last object values directly:

.card {
  color: #eee;
  background: #000;
}

For runtime themes, use scalar CSS custom properties instead of object variables:

--theme-fg: #111;
--theme-bg: #fff;

html.dark {
  --theme-fg: #eee;
  --theme-bg: #000;
}

---

Key Normalization

camelCase and kebab-case are cross-resolved in key access. Both access forms work regardless of which form you used in the definition.

Written in definition	Access form
font-size	var(--obj.fontSize)
lineHeight	var(--obj.lineHeight)
border-radius	var(--obj.borderRadius)

--typography: { background: #acacac; lineHeight: 1.5; letter-spacing: 0.01em; };

.body-text {
  background: var(--typography.background);
  line-height: var(--typography.lineHeight);
  letter-spacing: var(--typography.letterSpacing);
}

Generated CSS:

.body-text {
  background: #acacac;
  line-height: 1.5;
  letter-spacing: 0.01em;
}

---

Numeric Keys

Keys can also be numbers or a mix of number and letter.

--tone: { 100: #f8faff; 200: #dbe9ff; 900: #0a1628; };

.bg-light {
  background: var(--tone.100);
}

.bg-dark {
  background: var(--tone.900);
}

Generated CSS:

.bg-light {
  background: #f8faff;
}

.bg-dark {
  background: #0a1628;
}

Alphanumeric keys like 200a, 2xl are also supported:

--space: { 1: 4px; 2: 8px; 2xl: 24px; };

.gap-2xl {
  gap: var(--space.2xl);
}

Key generation inside object body with @for is also possible:

--factor: 2;
--range: [1-4];

--spacing: {
  @for(i, var(--range)) {
    ${i}: ${i * var(--factor)}px;
  }
};

.space-2 {
  margin: var(--spacing.2);
}

Generated CSS:

.space-2 {
  margin: 4px;
}

Note

This support is only for the @for(...) { key:value; } form inside object body. @if, elseif, else, and @fun are not supported inside object body.

---

Access to Object Items Inside Array

The same dot access syntax applies to object items inside an array variable.

--breakpoints: [
  { name: sm; size: 640px },
  { name: md; size: 768px }
];

.container {
  max-width: var(--breakpoints[0].size);
}

Generated CSS:

.container {
  max-width: 640px;
}

Note

For array variables and looping over an array of objects with @for, go to the Array Variable page.

---

CSS Property Object or Token Object?

	CSS Property Object	Token Object
Key content	CSS property name	Custom token name
var(--obj) full expansion	✓ Valid	✗ Produces invalid CSS
var(--obj.key) access	✓ Valid	✓ Valid
Typical usage	Shared style set	Design tokens (colors, spacing…)