# `MishkaCmsCore.Runtime.PageBuilder.Tokens`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.1/lib/mishka_cms_core/runtime/page_builder/tokens.ex#L5)

The design tokens a site actually renders from — read out of, and written back into, its own
stylesheet rows.

## Where a token lives

A site's CSS is not one file. `Stylesheet` rows — global ones and the site's own — are merged by
`MishkaCmsCore.Runtime.Compilers.TailwindCompiler` into a single compiled sheet, ordered
`app_base → theme → base → custom` and then by priority. The first two are injected BEFORE class
generation, because that is where the tokens are declared and Tailwind needs them to exist before
it resolves `bg-danger-light`.

Inside a `:theme` row the shape the kit ships is two blocks:

    :root { --danger-light: #de1135; … }        ← the values
    @theme { --color-danger-light: var(--danger-light); … }   ← the Tailwind names

So a token IS a custom-property declaration in a `:root` block, and changing one changes every
component on the site that resolves through it. That is what makes this worth editing visually
rather than through a text area: `--danger-light` is referenced by every danger variant of every
component, and nothing else in the editor can express "make danger warmer".

## What this module does NOT do

It does not invent tokens, and it does not touch the `@theme` block. A name that is not already
declared has no meaning to the compiled CSS, and rewriting the mapping block would decouple the
Tailwind colour from the value it points at. Adding a genuinely new token is a stylesheet edit,
which the Stylesheets admin page already owns.

# `declarations`

```elixir
@spec declarations(String.t()) :: [{String.t(), String.t()}]
```

The token declarations in a blob of CSS, in source order.

# `list`

```elixir
@spec list(String.t() | nil) :: [
  MishkaCmsCore.Runtime.PageBuilder.Marketplace.Token.t()
]
```

Every token the site declares, newest sheet last so a site row overrides a global one.

`usage` counts how many other declarations reference the token — `--danger-hover-light:
var(--danger-light)` counts once — which is what the Studio dims an unused token by.

# `put`

```elixir
@spec put(map() | nil, String.t() | nil, String.t(), String.t(), String.t() | nil) ::
  {:ok, MishkaCmsCore.Runtime.PageBuilder.Marketplace.Token.t()}
  | {:error, term()}
```

Sets a token's value in the sheet that declares it, as `actor`, and recompiles the site's CSS.

Refuses a name the site does not already declare: a token nothing resolves through is a line of
dead CSS, and silently adding one would look like it worked. The write is the builder's own, so
it is made by whoever may open a builder rather than by the stylesheet area alone; with no actor
it is refused.

# `without_theme_block`

```elixir
@spec without_theme_block(String.t()) :: String.t()
```

The same CSS with its `@theme` mapping blocks removed.

---

*Consult [api-reference.md](api-reference.md) for complete listing*