> ## Documentation Index
> Fetch the complete documentation index at: https://substrate.docs.unknowncreatives.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Markup Opt-In: data-ucs and data-mode

> Every element that uses Substrate's solved colors must opt into the cascade with data-ucs and select an intent role with data-mode. This page is the contract for those two attributes.

**This step is required.** The [runtime call sequence](/integration#the-runtime-call-sequence) writes solved values to `:root`, but no element picks them up automatically — each one opts in. Two attributes are the entire contract:

```html theme={null}
<div data-ucs data-mode="brand">Solved brand surface</div>
<div data-ucs data-mode="danger">Solved danger surface</div>
```

**`data-ucs`** opts the element into the Substrate cascade. It takes no value.

**`data-mode`** is the element's **mode list** — a space-separated set of tokens matched with `~=`, so tokens compose orthogonally: `data-mode="danger card frosted"` is a danger-intent card with a frosted material. One attribute carries the full per-element mode composition:

| Token class           | Examples                                                             | What it activates                                                                    |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Semantic intent roles | `brand`, `danger`, any custom intent                                 | Points the `--intent-*` indirection at that intent's solved primitives               |
| Component roles       | `card`, `panel`, `inset`                                             | Role-scoped component styles — the [Surface component](/surface-component) sets one  |
| Component states      | state tokens from a [component's config](/component-config/overview) | The generated state-layer rules                                                      |
| Component modes       | modes defined in a [component's config](/component-config/overview)  | That mode's property values and deltas                                               |
| Brand preset levels   | `dark`, `compact`, … (whatever the brand names in `presets`)         | That level's **property deltas**, applied discretely instead of slider interpolation |
| Materials             | `frosted`, … (per brand `materials`)                                 | The material's backdrop-filter, alpha, and noise treatment                           |
| `fluid`               | `fluid`                                                              | Gates the fluid type rules                                                           |

The conventional intent roles are `brand`, `neutral`, `danger`, `warning`, `success`, `info`, and `beta`, with brand-specific roles generated alongside them; the kernel's mode resolver accumulates every active token's effects in order (system modes first, component modes second).

<Warning>
  One thing `data-mode` does **not** carry: the preference axes themselves. A brand preset token like `dark` applies that level's *property deltas*, but the resolver explicitly excludes `scheme` and `contrast-factor` from token effects — light/dark position and contrast remain preference values on the vector, and there is still no theme attribute in Substrate.
</Warning>

## Attributes the runtime writes

You author `data-ucs` and `data-mode`; the runtime owns the rest:

| Attribute           | Written by                  | Role                                                                                  |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------- |
| `data-brand`        | `syncBrandToCssVars`        | Identifies the active brand on the root — what generated per-brand CSS scopes against |
| `data-cvd-achromat` | `syncPrefsToCssVars`        | Activates the achromat pattern overlays                                               |
| `data-cvd-sim`      | CVD simulation devtool only | Never set it in production markup                                                     |

## Styling with the solved values

Your own CSS composes from the same primitives the attributes activate — see [Web](/platforms/web#using-it-in-your-css) for the `calc()` composition patterns, and the [Color Token Reference](/reference/color-tokens) for every variable an intent produces.

<CardGroup cols={2}>
  <Card title="Runtime & Imports" icon="plug" href="/integration">
    The required call sequence that writes the values these attributes consume.
  </Card>

  <Card title="Surface Component" icon="layer-group" href="/surface-component">
    Required when a surface nests inside another — re-solves contrast locally.
  </Card>
</CardGroup>