MishkaCmsCore.Runtime.PageBuilder.Tokens (Mishka CMS Core v0.0.1)

Copy Markdown View Source

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.

Summary

Functions

declarations(source)

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

list(site_id)

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

put(actor, site_id, key, value, site_name \\ nil)

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

without_theme_block(source)

The same CSS with its @theme mapping blocks removed.

Functions

declarations(source)

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

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

list(site_id)

@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(actor, site_id, key, value, site_name \\ nil)

@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(source)

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

The same CSS with its @theme mapping blocks removed.