note
This rune is part of @refrakt-md/plan. Install with npm install @refrakt-md/plan and add "@refrakt-md/plan" to the plugins array in your refrakt.config.json.
Decision
Architecture decision record. Captures the context, options considered, the decision made, the rationale, and the consequences. The most important rune in the package for AI-native workflows — without decision records, every AI session starts from zero context.
Also available as {% adr %}.
Accepted decision
A fully documented architecture decision record.
{% decision id="ADR-007" status="accepted" date="2026-03-11" tags="tint,css" %}
# Use CSS custom properties for tint token injection
## Context
Tint runes need to override colour tokens within a section scope. The solution must work without JavaScript and cascade through nested elements.
## Options Considered
1. **CSS custom properties on the container** — inline styles setting `--tint-*` tokens, theme bridges via `var()` fallbacks.
2. **Generated CSS classes per tint combination** — build step creates per-tint classes. Avoids inline styles but combinatorial explosion.
3. **JavaScript runtime token injection** — behaviour script reads data attributes and sets styles. Most flexible but requires JS.
## Decision
CSS custom properties via inline styles on the container element.
## Rationale
Custom properties cascade naturally through the DOM subtree without JavaScript. Themes opt into tint support by including bridge CSS. The `--tint-*` namespace avoids collisions with theme-internal tokens.
## Consequences
- Themes must include the tint bridge CSS
- Inline styles cannot use media queries — dark mode handled separately
- Inspector must audit tint token contrast ratios
{% /decision %}<article data-rune="decision" data-rune-fields="{"id":"ADR-007","status":"accepted","date":"2026-03-11","supersedes":"","source":"","tags":"tint,css","created":"2026-09-13","modified":"2026-09-13"}">
<header data-name="title">
<h1 id="use-css-custom-properties-for-tint-token-injection">Use CSS custom properties for tint token injection</h1>
</header>
<div data-name="body">
<section data-name="context">
<h2 id="context">Context</h2>
<p>Tint runes need to override colour tokens within a section scope. The solution must work without JavaScript and cascade through nested elements.</p>
</section>
<section data-name="options-considered">
<h2 id="options-considered">Options Considered</h2>
<ol>
<li>
<strong marker="**">CSS custom properties on the container</strong>
— inline styles setting
<code>--tint-*</code>
tokens, theme bridges via
<code>var()</code>
fallbacks.
</li>
<li>
<strong marker="**">Generated CSS classes per tint combination</strong>
— build step creates per-tint classes. Avoids inline styles but combinatorial explosion.
</li>
<li>
<strong marker="**">JavaScript runtime token injection</strong>
— behaviour script reads data attributes and sets styles. Most flexible but requires JS.
</li>
</ol>
</section>
<section data-name="decision">
<h2 id="decision">Decision</h2>
<p>CSS custom properties via inline styles on the container element.</p>
</section>
<section data-name="rationale">
<h2 id="rationale">Rationale</h2>
<p>
Custom properties cascade naturally through the DOM subtree without JavaScript. Themes opt into tint support by including bridge CSS. The
<code>--tint-*</code>
namespace avoids collisions with theme-internal tokens.
</p>
</section>
<section data-name="consequences">
<h2 id="consequences">Consequences</h2>
<ul>
<li>Themes must include the tint bridge CSS</li>
<li>Inline styles cannot use media queries — dark mode handled separately</li>
<li>Inspector must audit tint token contrast ratios</li>
</ul>
</section>
</div>
</article>ADR-007accepted
Use CSS custom properties for tint token injection
Context
Tint runes need to override colour tokens within a section scope. The solution must work without JavaScript and cascade through nested elements.
Decision
CSS custom properties via inline styles on the container element.
Rationale
Custom properties cascade naturally through the DOM subtree without JavaScript. Themes opt into tint support by including bridge CSS. The --tint-* namespace avoids collisions with theme-internal tokens.
Consequences
- Themes must include the tint bridge CSS
- Inline styles cannot use media queries — dark mode handled separately
- Inspector must audit tint token contrast ratios
<article class="rf-decision rf-decision--ADR-007 rf-decision--accepted" data-id="ADR-007" data-status="accepted" data-date="2026-03-11" data-supersedes="" data-source="" data-tags="tint,css" data-created="2026-09-13" data-modified="2026-09-13" data-rune="decision" data-density="full">
<div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-decision__eyebrow">
<span data-meta-type="id">ADR-007</span>
<span class="rf-badge" data-meta-type="status" data-meta-sentiment="positive" data-align="end">accepted</span>
</div>
<header data-name="title" class="rf-decision__title" data-section="title">
<h1 id="use-css-custom-properties-for-tint-token-injection">Use CSS custom properties for tint token injection</h1>
</header>
<dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-decision__metadata">
<div data-name="row" data-field="date" class="rf-decision__row">
<dt data-meta-label="">Date</dt>
<dd data-meta-type="temporal">
<time datetime="2026-03-11">2026-03-11</time>
</dd>
</div>
<div data-name="row" data-field="created" class="rf-decision__row">
<dt data-meta-label="">Created</dt>
<dd data-meta-type="temporal">
<time datetime="2026-09-13">2026-09-13</time>
</dd>
</div>
<div data-name="row" data-field="modified" class="rf-decision__row">
<dt data-meta-label="">Modified</dt>
<dd data-meta-type="temporal">
<time datetime="2026-09-13">2026-09-13</time>
</dd>
</div>
</dl>
<div data-name="tags" data-zone="tags" data-zone-layout="bar" class="rf-decision__tags">
<span class="rf-badge" data-meta-type="tag">tint</span>
<span class="rf-badge" data-meta-type="tag">css</span>
</div>
<div data-name="body" class="rf-decision__body" data-section="body">
<section data-name="context" class="rf-decision__context">
<h2 id="context">Context</h2>
<p>Tint runes need to override colour tokens within a section scope. The solution must work without JavaScript and cascade through nested elements.</p>
</section>
<section data-name="options-considered" class="rf-decision__options-considered">
<h2 id="options-considered">Options Considered</h2>
<ol>
<li>
<strong marker="**">CSS custom properties on the container</strong>
— inline styles setting
<code>--tint-*</code>
tokens, theme bridges via
<code>var()</code>
fallbacks.
</li>
<li>
<strong marker="**">Generated CSS classes per tint combination</strong>
— build step creates per-tint classes. Avoids inline styles but combinatorial explosion.
</li>
<li>
<strong marker="**">JavaScript runtime token injection</strong>
— behaviour script reads data attributes and sets styles. Most flexible but requires JS.
</li>
</ol>
</section>
<section data-name="decision" class="rf-decision__decision">
<h2 id="decision">Decision</h2>
<p>CSS custom properties via inline styles on the container element.</p>
</section>
<section data-name="rationale" class="rf-decision__rationale">
<h2 id="rationale">Rationale</h2>
<p>
Custom properties cascade naturally through the DOM subtree without JavaScript. Themes opt into tint support by including bridge CSS. The
<code>--tint-*</code>
namespace avoids collisions with theme-internal tokens.
</p>
</section>
<section data-name="consequences" class="rf-decision__consequences">
<h2 id="consequences">Consequences</h2>
<ul>
<li>Themes must include the tint bridge CSS</li>
<li>Inline styles cannot use media queries — dark mode handled separately</li>
<li>Inspector must audit tint token contrast ratios</li>
</ul>
</section>
</div>
</article>Proposed decision
A decision still under review.
{% decision id="ADR-015" status="proposed" date="2026-03-18" %}
# Adopt content model validation at parse time
## Context
Currently content model violations are only caught during transform. Earlier validation would improve error messages.
## Decision
Move validation to a post-parse AST pass.
{% /decision %}<article data-rune="decision" data-rune-fields="{"id":"ADR-015","status":"proposed","date":"2026-03-18","supersedes":"","source":"","tags":"","created":"2026-09-13","modified":"2026-09-13"}">
<header data-name="title">
<h1 id="adopt-content-model-validation-at-parse-time">Adopt content model validation at parse time</h1>
</header>
<div data-name="body">
<section data-name="context">
<h2 id="context">Context</h2>
<p>Currently content model violations are only caught during transform. Earlier validation would improve error messages.</p>
</section>
<section data-name="decision">
<h2 id="decision">Decision</h2>
<p>Move validation to a post-parse AST pass.</p>
</section>
</div>
</article>ADR-015proposed
Adopt content model validation at parse time
Context
Currently content model violations are only caught during transform. Earlier validation would improve error messages.
Decision
Move validation to a post-parse AST pass.
<article class="rf-decision rf-decision--ADR-015 rf-decision--proposed" data-id="ADR-015" data-status="proposed" data-date="2026-03-18" data-supersedes="" data-source="" data-tags="" data-created="2026-09-13" data-modified="2026-09-13" data-rune="decision" data-density="full">
<div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-decision__eyebrow">
<span data-meta-type="id">ADR-015</span>
<span class="rf-badge" data-meta-type="status" data-meta-sentiment="neutral" data-align="end">proposed</span>
</div>
<header data-name="title" class="rf-decision__title" data-section="title">
<h1 id="adopt-content-model-validation-at-parse-time">Adopt content model validation at parse time</h1>
</header>
<dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-decision__metadata">
<div data-name="row" data-field="date" class="rf-decision__row">
<dt data-meta-label="">Date</dt>
<dd data-meta-type="temporal">
<time datetime="2026-03-18">2026-03-18</time>
</dd>
</div>
<div data-name="row" data-field="created" class="rf-decision__row">
<dt data-meta-label="">Created</dt>
<dd data-meta-type="temporal">
<time datetime="2026-09-13">2026-09-13</time>
</dd>
</div>
<div data-name="row" data-field="modified" class="rf-decision__row">
<dt data-meta-label="">Modified</dt>
<dd data-meta-type="temporal">
<time datetime="2026-09-13">2026-09-13</time>
</dd>
</div>
</dl>
<div data-name="body" class="rf-decision__body" data-section="body">
<section data-name="context" class="rf-decision__context">
<h2 id="context">Context</h2>
<p>Currently content model violations are only caught during transform. Earlier validation would improve error messages.</p>
</section>
<section data-name="decision" class="rf-decision__decision">
<h2 id="decision">Decision</h2>
<p>Move validation to a post-parse AST pass.</p>
</section>
</div>
</article>Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Identifier (e.g., "ADR-007"). |
status | "proposed" | "accepted" | "rejected" | "superseded" | "deprecated" | — | Decision status: proposed, accepted, rejected, superseded, or deprecated. |
date | string | — | Date decided (ISO 8601). |
supersedes | string | — | ID of the decision this replaces. |
source | string | — | Comma-separated IDs of specs or other entities this decision informs. |
tags | string | — | Comma-separated labels. |
created | string | — | Creation date (ISO 8601). Defaults to file creation date from git. |
modified | string | — | Last modified date (ISO 8601). Defaults to file modification date from git. |
Universal attributes
bg
The background layer (SPEC-088): image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.
| Attribute | Type | Required | Description |
|---|---|---|---|
bg | string | — | Background preset applied to this block |
bg-from | string | — | Gradient start colour — a semantic token name (→ var(--rf-color-*)) |
bg-gradient | "to-t" | "to-b" | "to-l" | "to-r" | "to-tr" | "to-br" | "to-bl" | "to-tl" | — | Gradient direction (bounded named set) |
bg-gradient-type | "linear" | "radial" | "conic" | — | Gradient type |
bg-to | string | — | Gradient end colour — a semantic token name |
bg-via | string | — | Optional middle gradient stop — a semantic token name |
scrim | "top" | "bottom" | "left" | "right" | "none" | — | Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim |
scrim-blur | "none" | "sm" | "md" | "lg" | — | Frost scrim blur amount |
scrim-strength | "sm" | "md" | "lg" | — | Gradient scrim strength |
scrim-tone | "dark" | "light" | — | Whether the scrim darkens (for light text) or lightens (for dark text) |
scrim-type | "gradient" | "frost" | — | Scrim treatment: gradient (default) or frost (backdrop blur) |
dropcap
Per-instance drop-cap opt-in (SPEC-108).
| Attribute | Type | Required | Description |
|---|---|---|---|
dropcap | boolean | — | Style the opening letter of a prose body as a drop cap (SPEC-108). Honoured only when the body reads as prose; ignored otherwise. |
elevation
The chrome/depth ladder (SPEC-107). The skin maps each rung to a chrome bundle by attribute, so there is no BEM class.
| Attribute | Type | Required | Description |
|---|---|---|---|
elevation | "sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg" | — | Surface depth on the SPEC-107 ladder (sunken→overlay); none/sm/md/lg are deprecated aliases |
inset
Internal padding override.
| Attribute | Type | Required | Description |
|---|---|---|---|
inset | "flush" | "tight" | "default" | "loose" | "breathe" | — | Inner padding of this block |
motion
Scroll-reveal entrance (SPEC-105). The author declares the character, the theme owns the choreography, a behaviour owns the timing.
| Attribute | Type | Required | Description |
|---|---|---|---|
reveal | "none" | "fade" | "slide" | "scale" | "blur" | — | Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography |
stagger | boolean | — | Cascade this block's items in as it reveals (no-op on single-child runes) |
prominence
Header emphasis (SPEC-107). Scales a rune's page-section header; the skin maps it to a type register by attribute, so there is no BEM class.
| Attribute | Type | Required | Description |
|---|---|---|---|
prominence | "quiet" | "normal" | "prominent" | "display" | — | Section-header emphasis (only on page-section-header family runes) |
reading
Editorial register for body text (SPEC-108). The author picks the register; the theme owns the magnitude.
| Attribute | Type | Required | Description |
|---|---|---|---|
reading | "fine" | "ui" | "prose" | — | Reading register for this block’s body (SPEC-108): fine | ui | prose. The theme owns the editorial treatment. |
spacing
Block-level rhythm override.
| Attribute | Type | Required | Description |
|---|---|---|---|
spacing | "flush" | "tight" | "default" | "loose" | "breathe" | — | Vertical spacing above and below this block |
substrate
Generated pattern fills (SPEC-087). Markers only — the engine sets the attributes and cell/opacity custom properties, CSS draws the pattern.
| Attribute | Type | Required | Description |
|---|---|---|---|
substrate | "dots" | "grid" | "lines" | "cross" | "checker" | "none" | — | Generated surface pattern |
substrate-fill | "inherit" | "inset" | — | Surface fill the pattern sits on (full colour stays with tint) |
substrate-opacity | "sm" | "md" | "lg" | — | Pattern ink strength |
substrate-size | "sm" | "md" | "lg" | — | Pattern cell size |
substrate-target | "self" | "media" | — | Which surface the pattern fills (overrides the rune/theme default) |
tint
Per-rune colour override (SPEC-053): a named tint from the theme registry, with inline per-token overrides layered on top.
| Attribute | Type | Required | Description |
|---|---|---|---|
tint | string | — | Color tint preset applied to this block |
tint-mode | "auto" | "dark" | "light" | — | Whether the tint adapts to auto, dark, or light mode |
width
The track a block rune occupies.
| Attribute | Type | Required | Description |
|---|---|---|---|
width | "compact" | "narrow" | "content" | "wide" | "full" | — | Maximum width constraint for this block |
| Not available | Why |
|---|---|
| frame | this rune declares neither a `frameTarget` nor a media section |