refrakt.md

Docs

Runes

Themes

Extend

Project

Plan›Bug
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.

Bug

Bug report with structured reproduction steps. Separate from work items because bugs have different required sections (reproduction steps, expected/actual behaviour) and different status values. H2 headings create named sections.

Confirmed bug

A bug confirmed with reproduction steps and environment details.

{% bug id="RF-201" status="confirmed" severity="major" %}
# Showcase bleed breaks with overflow:hidden parent

## Steps to Reproduce
1. Create a feature section with a parent that has `overflow: hidden`
2. Add a showcase with `bleed="top"` inside the feature
3. Observe the rendered output

## Expected
Showcase extends above the section boundary with visible displacement.

## Actual
Showcase is clipped at the section edge.

## Environment
- Browser: Chrome 122, Firefox 124
- Theme: default
- refrakt.md: v0.4.2
{% /bug %}
<article data-rune="bug" data-rune-fields="{&quot;id&quot;:&quot;RF-201&quot;,&quot;status&quot;:&quot;confirmed&quot;,&quot;severity&quot;:&quot;major&quot;,&quot;assignee&quot;:&quot;&quot;,&quot;milestone&quot;:&quot;&quot;,&quot;source&quot;:&quot;&quot;,&quot;pr&quot;:&quot;&quot;,&quot;tags&quot;:&quot;&quot;,&quot;created&quot;:&quot;2026-09-13&quot;,&quot;modified&quot;:&quot;2026-09-13&quot;}">
  <header data-name="title">
    <h1 id="showcase-bleed-breaks-with-overflowhidden-parent">Showcase bleed breaks with overflow:hidden parent</h1>
  </header>
  <div data-name="body">
    <section data-name="steps-to-reproduce">
      <h2 id="steps-to-reproduce">Steps to Reproduce</h2>
      <ol>
        <li>
          Create a feature section with a parent that has
          <code>overflow: hidden</code>
        </li>
        <li>
          Add a showcase with
          <code>bleed=&quot;top&quot;</code>
          inside the feature
        </li>
        <li>Observe the rendered output</li>
      </ol>
    </section>
    <section data-name="expected">
      <h2 id="expected">Expected</h2>
      <p>Showcase extends above the section boundary with visible displacement.</p>
    </section>
    <section data-name="actual">
      <h2 id="actual">Actual</h2>
      <p>Showcase is clipped at the section edge.</p>
    </section>
    <section data-name="environment">
      <h2 id="environment">Environment</h2>
      <ul>
        <li>Browser: Chrome 122, Firefox 124</li>
        <li>Theme: default</li>
        <li>refrakt.md: v0.4.2</li>
      </ul>
    </section>
  </div>
</article>
RF-201confirmed

Showcase bleed breaks with overflow:hidden parent

Severity
major
Created
Modified

Steps to Reproduce

  1. Create a feature section with a parent that has overflow: hidden
  2. Add a showcase with bleed="top" inside the feature
  3. Observe the rendered output

Expected

Showcase extends above the section boundary with visible displacement.

Actual

Showcase is clipped at the section edge.

Environment

  • Browser: Chrome 122, Firefox 124
  • Theme: default
  • refrakt.md: v0.4.2
<article class="rf-bug rf-bug--RF-201 rf-bug--confirmed rf-bug--major" data-id="RF-201" data-status="confirmed" data-severity="major" data-assignee="" data-milestone="" data-source="" data-pr="" data-tags="" data-created="2026-09-13" data-modified="2026-09-13" data-rune="bug" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-bug__eyebrow">
    <span data-meta-type="id">RF-201</span>
    <span class="rf-badge" data-meta-type="status" data-meta-sentiment="caution" data-align="end">confirmed</span>
  </div>
  <header data-name="title" class="rf-bug__title" data-section="title">
    <h1 id="showcase-bleed-breaks-with-overflowhidden-parent">Showcase bleed breaks with overflow:hidden parent</h1>
  </header>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-bug__metadata">
    <div data-name="row" data-field="severity" class="rf-bug__row">
      <dt data-meta-label="">Severity</dt>
      <dd>
        <span class="rf-badge" data-meta-type="category" data-meta-sentiment="caution">major</span>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-bug__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-bug__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-bug__body" data-section="body">
    <section data-name="steps-to-reproduce" class="rf-bug__steps-to-reproduce">
      <h2 id="steps-to-reproduce">Steps to Reproduce</h2>
      <ol>
        <li>
          Create a feature section with a parent that has 
          <code>overflow: hidden</code>
        </li>
        <li>
          Add a showcase with 
          <code>bleed=&quot;top&quot;</code>
           inside the feature
        </li>
        <li>Observe the rendered output</li>
      </ol>
    </section>
    <section data-name="expected" class="rf-bug__expected">
      <h2 id="expected">Expected</h2>
      <p>Showcase extends above the section boundary with visible displacement.</p>
    </section>
    <section data-name="actual" class="rf-bug__actual">
      <h2 id="actual">Actual</h2>
      <p>Showcase is clipped at the section edge.</p>
    </section>
    <section data-name="environment" class="rf-bug__environment">
      <h2 id="environment">Environment</h2>
      <ul>
        <li>Browser: Chrome 122, Firefox 124</li>
        <li>Theme: default</li>
        <li>refrakt.md: v0.4.2</li>
      </ul>
    </section>
  </div>
</article>

Critical bug

A critical severity bug requiring immediate attention.

{% bug id="RF-305" status="reported" severity="critical" %}
# Build fails when no rune packages configured

## Steps to Reproduce
1. Create a new refrakt project
2. Remove all entries from packages array
3. Run `npm run build`

## Expected
Build succeeds with only core runes.

## Actual
Build crashes with undefined reference error.
{% /bug %}
<article data-rune="bug" data-rune-fields="{&quot;id&quot;:&quot;RF-305&quot;,&quot;status&quot;:&quot;reported&quot;,&quot;severity&quot;:&quot;critical&quot;,&quot;assignee&quot;:&quot;&quot;,&quot;milestone&quot;:&quot;&quot;,&quot;source&quot;:&quot;&quot;,&quot;pr&quot;:&quot;&quot;,&quot;tags&quot;:&quot;&quot;,&quot;created&quot;:&quot;2026-09-13&quot;,&quot;modified&quot;:&quot;2026-09-13&quot;}">
  <header data-name="title">
    <h1 id="build-fails-when-no-rune-packages-configured">Build fails when no rune packages configured</h1>
  </header>
  <div data-name="body">
    <section data-name="steps-to-reproduce">
      <h2 id="steps-to-reproduce">Steps to Reproduce</h2>
      <ol>
        <li>Create a new refrakt project</li>
        <li>Remove all entries from packages array</li>
        <li>
          Run
          <code>npm run build</code>
        </li>
      </ol>
    </section>
    <section data-name="expected">
      <h2 id="expected">Expected</h2>
      <p>Build succeeds with only core runes.</p>
    </section>
    <section data-name="actual">
      <h2 id="actual">Actual</h2>
      <p>Build crashes with undefined reference error.</p>
    </section>
  </div>
</article>
RF-305reported

Build fails when no rune packages configured

Severity
critical
Created
Modified

Steps to Reproduce

  1. Create a new refrakt project
  2. Remove all entries from packages array
  3. Run npm run build

Expected

Build succeeds with only core runes.

Actual

Build crashes with undefined reference error.

<article class="rf-bug rf-bug--RF-305 rf-bug--reported rf-bug--critical" data-id="RF-305" data-status="reported" data-severity="critical" data-assignee="" data-milestone="" data-source="" data-pr="" data-tags="" data-created="2026-09-13" data-modified="2026-09-13" data-rune="bug" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-bug__eyebrow">
    <span data-meta-type="id">RF-305</span>
    <span class="rf-badge" data-meta-type="status" data-meta-sentiment="neutral" data-align="end">reported</span>
  </div>
  <header data-name="title" class="rf-bug__title" data-section="title">
    <h1 id="build-fails-when-no-rune-packages-configured">Build fails when no rune packages configured</h1>
  </header>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-bug__metadata">
    <div data-name="row" data-field="severity" class="rf-bug__row">
      <dt data-meta-label="">Severity</dt>
      <dd>
        <span class="rf-badge" data-meta-type="category" data-meta-sentiment="negative">critical</span>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-bug__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-bug__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-bug__body" data-section="body">
    <section data-name="steps-to-reproduce" class="rf-bug__steps-to-reproduce">
      <h2 id="steps-to-reproduce">Steps to Reproduce</h2>
      <ol>
        <li>Create a new refrakt project</li>
        <li>Remove all entries from packages array</li>
        <li>
          Run 
          <code>npm run build</code>
        </li>
      </ol>
    </section>
    <section data-name="expected" class="rf-bug__expected">
      <h2 id="expected">Expected</h2>
      <p>Build succeeds with only core runes.</p>
    </section>
    <section data-name="actual" class="rf-bug__actual">
      <h2 id="actual">Actual</h2>
      <p>Build crashes with undefined reference error.</p>
    </section>
  </div>
</article>

Attributes

AttributeTypeRequiredDescription
idstring✓Unique identifier.
status"reported" | "confirmed" | "in-progress" | "fixed" | "wontfix" | "duplicate"—Current status: reported, confirmed, in-progress, fixed, wontfix, or duplicate.
severity"critical" | "major" | "minor" | "cosmetic"—Impact level: critical, major, minor, or cosmetic.
assigneestring—Person or agent working on this.
milestonestring—Milestone for the fix.
sourcestring—Comma-separated IDs of specs or decisions this item implements.
prstring—Comma-separated PR references that fixed this bug (e.g. "refrakt-md/refrakt#142").
tagsstring—Comma-separated labels.
createdstring—Creation date (ISO 8601). Defaults to file creation date from git.
modifiedstring—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.

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)
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
Not availableWhy
framethis rune declares neither a `frameTarget` nor a media section