Color roles

Classes

A role is part of the color key: fg-text-muted reads --color-text-muted through the color namespace. Every color family accepts role keys, including bg-text-link and outline-line-control; the role name does not restrict the property.

Values

Light and Dark are the two arguments of each preset light-dark() value. They are selected by the element’s used color scheme, not by the class prefix or the operating system alone.

Text

Surface

Line

The local color scheme selects the value

fg-text-muted emits color: var(--color-text-muted). Its preset value uses light-dark(var(--color-zinc-60), var(--color-zinc-40)): light selects the first color, dark the second. The class and generated rule stay the same.

The used color scheme selects the first or second color. Both specimens keep fg-text-muted and bg-surface-base; the local scheme changes their computed colors.

Text description

1. fg-text-muted generates color: var(--color-text-muted). Its preset token contains light-dark(var(--color-zinc-60), var(--color-zinc-40)).
2. The light specimen uses the first argument, --color-zinc-60. The dark specimen uses the second, --color-zinc-40.
3. Both specimens use bg-surface-base and the same text class. The colored leaders identify the two arguments; they are annotations, not the resulting text colors.
4. The local used color scheme selects the branch. The comparison does not imply that system media queries follow a manual local theme.

The preset enables color-scheme: light dark on the root. Its data-theme="light" and data-theme="dark" selectors can choose a scheme on the root, a nested region or a shadow host. Native CSS performs the selection; switching schemes does not require regenerating this utility.

The @dark and @light class suffixes test the system preference. A manual data-theme choice does not activate those media queries. Use the mode contract for selector-based conditions.

A role supplies a color, not a component or a contrast guarantee for every background. Inverse surfaces have a paired inverse text role. Divider and subtle lines are decorative; control lines identify boundaries. Recheck the actual pair when changing a surface, opacity or token value.

See Variables and modes and native light-dark() selection.

Usage

Build a card from roles: a raised surface, a divider line, and strong, body and muted text.

<article class="… b(1) b-solid b-line-divider bg-surface-raised">  <h3 class="… fg-text-strong">Make space for ideas</h3>  <p class="… fg-text-body">A steady rhythm keeps the focus on the content.</p>  <p class="… bt(1) bt-solid bt-line-divider fg-text-muted">4 min read</p></article>

@layer theme {  :root,  :host {    --color-zinc-30: oklch(78% .0025 265);    --color-zinc-40: oklch(68.6% .0028 265);    --color-zinc-60: oklch(48.6% .003 265);    --color-zinc-70: oklch(39.8% .0028 265);    --color-zinc-90: oklch(24.6% .0022 265);    --color-zinc-100: oklch(15% .0016 265)  }  :root,  :host {    --color-surface-raised: light-dark(var(--color-white), var(--color-zinc-90));    --color-line-divider: light-dark(oklch(0% 0 none / .12), oklch(100% 0 none / .12));    --color-text-body: light-dark(var(--color-zinc-70), var(--color-zinc-30));    --color-text-strong: light-dark(var(--color-zinc-100), var(--color-white));    --color-text-muted: light-dark(var(--color-zinc-60), var(--color-zinc-40))  }  :root,  :host {    --color-white: oklch(100% 0 none)  }}@layer utilities {  .bg-surface-raised {    background-color: var(--color-surface-raised)  }  .b-line-divider {    border-color: var(--color-line-divider)  }  .bt-line-divider {    border-top-color: var(--color-line-divider)  }  .b-solid {    border-style: solid  }  .bt-solid {    border-top-style: solid  }  .b\(1\) {    border-width: calc(1 * 1px)  }  .bt\(1\) {    border-top-width: calc(1 * 1px)  }  .fg-text-body {    color: var(--color-text-body)  }  .fg-text-muted {    color: var(--color-text-muted)  }  .fg-text-strong {    color: var(--color-text-strong)  }}

Customize

Add a role with one value per color scheme: --color-text-brand creates fg-text-brand.

@theme {  --color-text-brand: light-dark(    var(--color-indigo-60),    var(--color-indigo-30)  );}

@layer theme {  :root,  :host {    --color-indigo-30: oklch(70.2% .1611 282.9);    --color-indigo-60: oklch(50.06% .2906 282)  }  :root,  :host {    --color-text-brand: light-dark(var(--color-indigo-60), var(--color-indigo-30))  }}@layer utilities {  .fg-text-brand {    color: var(--color-text-brand)  }}

See theme directives and Color.