refrakt.md

Docs

Runes

Themes

Extend

Project

Storytelling›Realm
note

This rune is part of @refrakt-md/storytelling. Install with npm install @refrakt-md/storytelling and add "@refrakt-md/storytelling" to the plugins array in your refrakt.config.json.

Realm

Location and place profiles for worldbuilding. Headings within the rune become named sections, and the first image is extracted as a scene illustration.

Basic usage

Describe a location with sections for geography, features, or history.

{% realm name="Rivendell" type="sanctuary" scale="settlement" parent="Eriador" media-position="start" %}
![Rivendell](https://assets.refrakt.md/realm-rivendell.png)

The Last Homely House East of the Sea.

## Geography

A hidden valley in the foothills of the Misty Mountains.

## Notable Features

- Hall of Fire
- Council chamber
- Extensive libraries
{% /realm %}
<article data-field="content-section" data-rune="realm" typeof="Place" data-rune-fields="{&quot;realmType&quot;:&quot;sanctuary&quot;,&quot;scale&quot;:&quot;settlement&quot;,&quot;tags&quot;:&quot;&quot;,&quot;parent&quot;:&quot;Eriador&quot;,&quot;media-position&quot;:&quot;start&quot;}">
  <div data-name="scene">
    <img src="https://assets.refrakt.md/realm-rivendell.png" alt="Rivendell" property="image">
  </div>
  <meta content="sanctuary" property="additionalType">
  <span data-name="name" property="name">Rivendell</span>
  <div data-name="body">
    <p>The Last Homely House East of the Sea.</p>
  </div>
  <div data-name="sections">
    <div data-field="section" data-rune="realm-section">
      <span data-name="name">Geography</span>
      <div data-name="body">
        <p>A hidden valley in the foothills of the Misty Mountains.</p>
      </div>
    </div>
    <div data-field="section" data-rune="realm-section">
      <span data-name="name">Notable Features</span>
      <div data-name="body">
        <ul>
          <li>Hall of Fire</li>
          <li>Council chamber</li>
          <li>Extensive libraries</li>
        </ul>
      </div>
    </div>
  </div>
</article>
Rivendell
Rivendell
Type
sanctuary
Scale
settlement

The Last Homely House East of the Sea.

Geography

A hidden valley in the foothills of the Misty Mountains.

Notable Features
  • Hall of Fire
  • Council chamber
  • Extensive libraries
<article data-field="content-section" typeof="Place" class="rf-realm rf-realm--sanctuary rf-realm--settlement rf-realm--Eriador" data-realm-type="sanctuary" data-scale="settlement" data-tags="" data-parent="Eriador" data-media-position="start" data-elevation="flat" data-rune="realm" data-density="full">
  <div data-name="scene" class="rf-realm__scene" data-section="media" data-media="cover" data-guest-fit="clip">
    <img src="https://assets.refrakt.md/realm-rivendell.png" alt="Rivendell" property="image" />
  </div>
  <div data-name="content" class="rf-realm__content">
    <header data-name="preamble" class="rf-realm__preamble" data-section="preamble">
      <span data-name="name" property="name" class="rf-realm__name" data-section="title">Rivendell</span>
    </header>
    <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-realm__metadata">
      <div data-name="row" data-field="realmType" class="rf-realm__row">
        <dt data-meta-label="">Type</dt>
        <dd>
          <span class="rf-badge" data-meta-type="category">sanctuary</span>
        </dd>
      </div>
      <div data-name="row" data-field="scale" class="rf-realm__row">
        <dt data-meta-label="">Scale</dt>
        <dd>
          <span class="rf-badge" data-meta-type="category">settlement</span>
        </dd>
      </div>
    </dl>
    <div data-name="body" class="rf-realm__body" data-section="body">
      <p>The Last Homely House East of the Sea.</p>
    </div>
    <div data-name="sections" class="rf-realm__sections">
      <div data-field="section" class="rf-realm-section" data-rune="realm-section" data-density="full">
        <span data-name="name" class="rf-realm-section__name">Geography</span>
        <div data-name="body" class="rf-realm-section__body" data-section="body">
          <p>A hidden valley in the foothills of the Misty Mountains.</p>
        </div>
      </div>
      <div data-field="section" class="rf-realm-section" data-rune="realm-section" data-density="full">
        <span data-name="name" class="rf-realm-section__name">Notable Features</span>
        <div data-name="body" class="rf-realm-section__body" data-section="body">
          <ul>
            <li>Hall of Fire</li>
            <li>Council chamber</li>
            <li>Extensive libraries</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
  <meta content="sanctuary" property="additionalType" />
</article>

Realm types

Use the type attribute to categorize your locations.

{% realm name="The Undercroft" type="dungeon" scale="complex" media-position="start" %}
![The Undercroft](https://assets.refrakt.md/realm-the-undercroft.png)

## Overview

A sprawling network of tunnels beneath the old city, home to smugglers and worse.

## Dangers

- Flooded passages
- Collapsing ceilings
- Cave spiders
{% /realm %}
<article data-field="content-section" data-rune="realm" typeof="Place" data-rune-fields="{&quot;realmType&quot;:&quot;dungeon&quot;,&quot;scale&quot;:&quot;complex&quot;,&quot;tags&quot;:&quot;&quot;,&quot;parent&quot;:&quot;&quot;,&quot;media-position&quot;:&quot;start&quot;}">
  <div data-name="scene">
    <img src="https://assets.refrakt.md/realm-the-undercroft.png" alt="The Undercroft" property="image">
  </div>
  <meta content="dungeon" property="additionalType">
  <span data-name="name" property="name">The Undercroft</span>
  <div data-name="sections">
    <div data-field="section" data-rune="realm-section">
      <span data-name="name">Overview</span>
      <div data-name="body">
        <p>A sprawling network of tunnels beneath the old city, home to smugglers and worse.</p>
      </div>
    </div>
    <div data-field="section" data-rune="realm-section">
      <span data-name="name">Dangers</span>
      <div data-name="body">
        <ul>
          <li>Flooded passages</li>
          <li>Collapsing ceilings</li>
          <li>Cave spiders</li>
        </ul>
      </div>
    </div>
  </div>
</article>
The Undercroft
The Undercroft
Type
dungeon
Scale
complex
Overview

A sprawling network of tunnels beneath the old city, home to smugglers and worse.

Dangers
  • Flooded passages
  • Collapsing ceilings
  • Cave spiders
<article data-field="content-section" typeof="Place" class="rf-realm rf-realm--dungeon rf-realm--complex" data-realm-type="dungeon" data-scale="complex" data-tags="" data-parent="" data-media-position="start" data-elevation="flat" data-rune="realm" data-density="full">
  <div data-name="scene" class="rf-realm__scene" data-section="media" data-media="cover" data-guest-fit="clip">
    <img src="https://assets.refrakt.md/realm-the-undercroft.png" alt="The Undercroft" property="image" />
  </div>
  <div data-name="content" class="rf-realm__content">
    <header data-name="preamble" class="rf-realm__preamble" data-section="preamble">
      <span data-name="name" property="name" class="rf-realm__name" data-section="title">The Undercroft</span>
    </header>
    <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-realm__metadata">
      <div data-name="row" data-field="realmType" class="rf-realm__row">
        <dt data-meta-label="">Type</dt>
        <dd>
          <span class="rf-badge" data-meta-type="category">dungeon</span>
        </dd>
      </div>
      <div data-name="row" data-field="scale" class="rf-realm__row">
        <dt data-meta-label="">Scale</dt>
        <dd>
          <span class="rf-badge" data-meta-type="category">complex</span>
        </dd>
      </div>
    </dl>
    <div data-name="sections" class="rf-realm__sections">
      <div data-field="section" class="rf-realm-section" data-rune="realm-section" data-density="full">
        <span data-name="name" class="rf-realm-section__name">Overview</span>
        <div data-name="body" class="rf-realm-section__body" data-section="body">
          <p>A sprawling network of tunnels beneath the old city, home to smugglers and worse.</p>
        </div>
      </div>
      <div data-field="section" class="rf-realm-section" data-rune="realm-section" data-density="full">
        <span data-name="name" class="rf-realm-section__name">Dangers</span>
        <div data-name="body" class="rf-realm-section__body" data-section="body">
          <ul>
            <li>Flooded passages</li>
            <li>Collapsing ceilings</li>
            <li>Cave spiders</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
  <meta content="dungeon" property="additionalType" />
</article>

Attributes

realm

AttributeTypeRequiredDescription
namestring✓Display name shown in the realm header.
typestring—Kind of location (e.g. city, forest, dungeon, plane, continent).
scalestring—Geographic scope of the realm (e.g. room, district, region, world).
tagsstring—Comma-separated keywords for filtering and cross-referencing.
parentstring—Name of the containing realm for hierarchical nesting.

Inherited from the split layout preset

AttributeTypeRequiredDescription
media-position"top" | "bottom" | "start" | "end" | "cover"—Where the media zone sits relative to the content: above (top), below (bottom), or beside (start/end)
media-ratio"1/3" | "2/5" | "1/2" | "3/5" | "2/3"—Media zone’s share of the row width when media is beside content (start/end)
valign"top" | "center" | "bottom" | "stretch"—Cross-axis alignment when media is beside content (start/end); applies to the shorter zone
collapse"sm" | "md" | "lg" | "never"—Breakpoint at which side-by-side layouts collapse to a single stacked column

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.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—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-tostring—Gradient end colour — a semantic token name
bg-viastring—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).

AttributeTypeRequiredDescription
dropcapboolean—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.

AttributeTypeRequiredDescription
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
frame

Surface chrome (SPEC-086): a named preset from the theme registry with inline `frame-*` overrides layered on top.

AttributeTypeRequiredDescription
framestring—Named frame preset presenting this block's media surface
frame-anchorstring—Crop focal point when the guest is cut (object-position)
frame-aspectstring—Aspect ratio of the framed media, e.g. "16/9"
frame-displace"top" | "bottom" | "end" | "bottom-end" | "top-end"—Edge/corner the framed guest moves toward
frame-displace-mode"peek" | "bleed"—How displacement renders: `peek` (default) translates the guest visually inside its frame target; `bleed` uses negative margin on the media zone so following layout pulls up — extends past a section like a hero without leaving a gap above
frame-offset"none" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl"—Displacement distance (non-linear named scale: sm…xl ride the block-spacing tokens, 2xl/3xl/4xl step up to section-spacing for bleed-mode displacements that clear a section edge)
frame-overflow"clip" | "bleed"—How the frame handles a guest whose content is wider than it: `clip` (default) keeps it inside the rounded frame; `bleed` runs an overflowing guest out to the layout edge on a narrow viewport so it reads as cropped by the screen (a bleed host only — hero/feature)
frame-oversizestring—How far the guest exceeds its slot (scale factor)
frame-placestring—Guest-box alignment in the slot (e.g. "left top")
frame-shadow"none" | "sm" | "md" | "lg"—Silhouette drop-shadow strength for the framed media
inset

Internal padding override.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
tintstring—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.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block

realm-section

AttributeTypeRequiredDescription
namestring✓

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.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—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-tostring—Gradient end colour — a semantic token name
bg-viastring—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).

AttributeTypeRequiredDescription
dropcapboolean—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—Cascade this block's items in as it reveals (no-op on single-child runes)
reading

Editorial register for body text (SPEC-108). The author picks the register; the theme owns the magnitude.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
tintstring—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.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
framethis rune declares neither a `frameTarget` nor a media section
prominencethis rune has no page-section header

Layout attributes

A realm's scene field (the image at the top of each section) is the media zone; media-position controls where it sits relative to the content. Beside layouts (start/end) collapse to a stack at narrow widths.

AttributeTypeDefaultDescription
media-positionstringtopWhere the scene sits: top, bottom, start (left), end (right)
media-ratiostring—Scene's share of the row when beside content (start/end): 1/3, 2/5, 1/2, 3/5, 2/3
valignstring—Cross-axis alignment when scene is beside content: top, center, bottom, stretch
collapsestring—Breakpoint at which beside layouts collapse to a stack: sm, md, lg, never