refrakt.md

Docs

Runes

Themes

Extend

Project

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

Work

A discrete piece of implementation work with acceptance criteria, priority, complexity, and status tracking. Not a user story — a clear description of what needs to change. H2 headings create named sections for structured content like acceptance criteria, approach, and references.

Also available as {% task %}.

Ready work item

A work item ready for implementation with acceptance criteria and approach.

{% work id="RF-142" status="ready" priority="high" complexity="moderate" milestone="v0.5.0" tags="tint,theming" %}
# Implement tint rune dark mode support

The tint rune currently handles single-scheme colour tokens. It needs to support dual light/dark definitions.

## Acceptance Criteria
- [ ] Tint rune accepts light and dark content sections
- [ ] Identity transform emits data-tint-dark when dark values present
- [ ] Theme CSS swaps tokens in prefers-color-scheme: dark
- [ ] Inline tints without dark values fall back to page tokens
- [ ] Inspector audits contrast ratios for both variants

## Approach
The identity transform parses light/dark headings within the tint child rune body. Dark values are emitted as `--tint-dark-*` CSS custom properties alongside the light values.
{% /work %}
<article data-rune="work" data-rune-fields="{&quot;id&quot;:&quot;RF-142&quot;,&quot;status&quot;:&quot;ready&quot;,&quot;priority&quot;:&quot;high&quot;,&quot;complexity&quot;:&quot;moderate&quot;,&quot;assignee&quot;:&quot;&quot;,&quot;milestone&quot;:&quot;v0.5.0&quot;,&quot;source&quot;:&quot;&quot;,&quot;supersedes&quot;:&quot;&quot;,&quot;pr&quot;:&quot;&quot;,&quot;tags&quot;:&quot;tint,theming&quot;,&quot;created&quot;:&quot;2026-07-23&quot;,&quot;modified&quot;:&quot;2026-07-23&quot;}">
  <header data-name="title">
    <h1 id="implement-tint-rune-dark-mode-support">Implement tint rune dark mode support</h1>
  </header>
  <div data-name="blurb">
    <p>The tint rune currently handles single-scheme colour tokens. It needs to support dual light/dark definitions.</p>
  </div>
  <div data-name="body">
    <section data-name="acceptance-criteria">
      <h2 id="acceptance-criteria">Acceptance Criteria</h2>
      <ul>
        <li>[ ] Tint rune accepts light and dark content sections</li>
        <li>[ ] Identity transform emits data-tint-dark when dark values present</li>
        <li>[ ] Theme CSS swaps tokens in prefers-color-scheme: dark</li>
        <li>[ ] Inline tints without dark values fall back to page tokens</li>
        <li>[ ] Inspector audits contrast ratios for both variants</li>
      </ul>
    </section>
    <section data-name="approach">
      <h2 id="approach">Approach</h2>
      <p>
        The identity transform parses light/dark headings within the tint child rune body. Dark values are emitted as
        <code>--tint-dark-*</code>
        CSS custom properties alongside the light values.
      </p>
    </section>
  </div>
</article>
RF-142ready

Implement tint rune dark mode support

The tint rune currently handles single-scheme colour tokens. It needs to support dual light/dark definitions.

Priority
high
Complexity
moderate
Milestone
v0.5.0
Created
Modified
tinttheming

Acceptance Criteria

  • Tint rune accepts light and dark content sections
  • Identity transform emits data-tint-dark when dark values present
  • Theme CSS swaps tokens in prefers-color-scheme: dark
  • Inline tints without dark values fall back to page tokens
  • Inspector audits contrast ratios for both variants

Approach

The identity transform parses light/dark headings within the tint child rune body. Dark values are emitted as --tint-dark-* CSS custom properties alongside the light values.

<article class="rf-work rf-work--RF-142 rf-work--ready rf-work--high rf-work--moderate" data-id="RF-142" data-status="ready" data-priority="high" data-complexity="moderate" data-assignee="" data-milestone="v0.5.0" data-source="" data-supersedes="" data-pr="" data-tags="tint,theming" data-created="2026-07-23" data-modified="2026-07-23" data-rune="work" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-work__eyebrow">
    <span data-meta-type="id">RF-142</span>
    <span class="rf-badge" data-meta-type="status" data-meta-sentiment="neutral" data-align="end">ready</span>
  </div>
  <header data-name="title" class="rf-work__title" data-section="title">
    <h1 id="implement-tint-rune-dark-mode-support">Implement tint rune dark mode support</h1>
  </header>
  <div data-name="blurb" class="rf-work__blurb" data-section="description">
    <p>The tint rune currently handles single-scheme colour tokens. It needs to support dual light/dark definitions.</p>
  </div>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-work__metadata">
    <div data-name="row" data-field="priority" class="rf-work__row">
      <dt data-meta-label="">Priority</dt>
      <dd>
        <span class="rf-badge" data-meta-type="category" data-meta-sentiment="caution">high</span>
      </dd>
    </div>
    <div data-name="row" data-field="complexity" class="rf-work__row">
      <dt data-meta-label="">Complexity</dt>
      <dd data-meta-type="quantity">moderate</dd>
    </div>
    <div data-name="row" data-field="milestone" class="rf-work__row">
      <dt data-meta-label="">Milestone</dt>
      <dd>
        <span class="rf-badge" data-meta-type="tag">v0.5.0</span>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-work__row">
      <dt data-meta-label="">Created</dt>
      <dd data-meta-type="temporal">
        <time datetime="2026-07-23">2026-07-23</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-work__row">
      <dt data-meta-label="">Modified</dt>
      <dd data-meta-type="temporal">
        <time datetime="2026-07-23">2026-07-23</time>
      </dd>
    </div>
  </dl>
  <div data-name="tags" data-zone="tags" data-zone-layout="bar" class="rf-work__tags">
    <span class="rf-badge" data-meta-type="tag">tint</span>
    <span class="rf-badge" data-meta-type="tag">theming</span>
  </div>
  <div data-name="body" class="rf-work__body" data-section="body">
    <section data-name="acceptance-criteria" class="rf-work__acceptance-criteria">
      <h2 id="acceptance-criteria">Acceptance Criteria</h2>
      <ul>
        <li data-checked="unchecked">Tint rune accepts light and dark content sections</li>
        <li data-checked="unchecked">Identity transform emits data-tint-dark when dark values present</li>
        <li data-checked="unchecked">Theme CSS swaps tokens in prefers-color-scheme: dark</li>
        <li data-checked="unchecked">Inline tints without dark values fall back to page tokens</li>
        <li data-checked="unchecked">Inspector audits contrast ratios for both variants</li>
      </ul>
    </section>
    <section data-name="approach" class="rf-work__approach">
      <h2 id="approach">Approach</h2>
      <p>
        The identity transform parses light/dark headings within the tint child rune body. Dark values are emitted as 
        <code>--tint-dark-*</code>
         CSS custom properties alongside the light values.
      </p>
    </section>
  </div>
</article>

Blocked work item

A work item blocked by a dependency.

{% work id="RF-215" status="blocked" priority="medium" complexity="complex" assignee="alice" %}
# Alignment system migration

Migrate all runes from manual alignment classes to the new alignment system.

## Acceptance Criteria
- [ ] All runes use alignment utilities instead of manual classes
- [ ] No visual regressions in existing content
- [ ] Migration guide published
{% /work %}
<article data-rune="work" data-rune-fields="{&quot;id&quot;:&quot;RF-215&quot;,&quot;status&quot;:&quot;blocked&quot;,&quot;priority&quot;:&quot;medium&quot;,&quot;complexity&quot;:&quot;complex&quot;,&quot;assignee&quot;:&quot;alice&quot;,&quot;milestone&quot;:&quot;&quot;,&quot;source&quot;:&quot;&quot;,&quot;supersedes&quot;:&quot;&quot;,&quot;pr&quot;:&quot;&quot;,&quot;tags&quot;:&quot;&quot;,&quot;created&quot;:&quot;2026-07-23&quot;,&quot;modified&quot;:&quot;2026-07-23&quot;}">
  <header data-name="title">
    <h1 id="alignment-system-migration">Alignment system migration</h1>
  </header>
  <div data-name="blurb">
    <p>Migrate all runes from manual alignment classes to the new alignment system.</p>
  </div>
  <div data-name="body">
    <section data-name="acceptance-criteria">
      <h2 id="acceptance-criteria">Acceptance Criteria</h2>
      <ul>
        <li>[ ] All runes use alignment utilities instead of manual classes</li>
        <li>[ ] No visual regressions in existing content</li>
        <li>[ ] Migration guide published</li>
      </ul>
    </section>
  </div>
</article>
RF-215blocked

Alignment system migration

Migrate all runes from manual alignment classes to the new alignment system.

Priority
medium
Complexity
complex
Assignee
alice
Created
Modified

Acceptance Criteria

  • All runes use alignment utilities instead of manual classes
  • No visual regressions in existing content
  • Migration guide published
<article class="rf-work rf-work--RF-215 rf-work--blocked rf-work--medium rf-work--complex" data-id="RF-215" data-status="blocked" data-priority="medium" data-complexity="complex" data-assignee="alice" data-milestone="" data-source="" data-supersedes="" data-pr="" data-tags="" data-created="2026-07-23" data-modified="2026-07-23" data-rune="work" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-work__eyebrow">
    <span data-meta-type="id">RF-215</span>
    <span class="rf-badge" data-meta-type="status" data-meta-sentiment="negative" data-align="end">blocked</span>
  </div>
  <header data-name="title" class="rf-work__title" data-section="title">
    <h1 id="alignment-system-migration">Alignment system migration</h1>
  </header>
  <div data-name="blurb" class="rf-work__blurb" data-section="description">
    <p>Migrate all runes from manual alignment classes to the new alignment system.</p>
  </div>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-work__metadata">
    <div data-name="row" data-field="priority" class="rf-work__row">
      <dt data-meta-label="">Priority</dt>
      <dd>
        <span class="rf-badge" data-meta-type="category" data-meta-sentiment="neutral">medium</span>
      </dd>
    </div>
    <div data-name="row" data-field="complexity" class="rf-work__row">
      <dt data-meta-label="">Complexity</dt>
      <dd data-meta-type="quantity">complex</dd>
    </div>
    <div data-name="row" data-field="assignee" class="rf-work__row">
      <dt data-meta-label="">Assignee</dt>
      <dd>
        <span class="rf-badge" data-meta-type="tag">alice</span>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-work__row">
      <dt data-meta-label="">Created</dt>
      <dd data-meta-type="temporal">
        <time datetime="2026-07-23">2026-07-23</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-work__row">
      <dt data-meta-label="">Modified</dt>
      <dd data-meta-type="temporal">
        <time datetime="2026-07-23">2026-07-23</time>
      </dd>
    </div>
  </dl>
  <div data-name="body" class="rf-work__body" data-section="body">
    <section data-name="acceptance-criteria" class="rf-work__acceptance-criteria">
      <h2 id="acceptance-criteria">Acceptance Criteria</h2>
      <ul>
        <li data-checked="unchecked">All runes use alignment utilities instead of manual classes</li>
        <li data-checked="unchecked">No visual regressions in existing content</li>
        <li data-checked="unchecked">Migration guide published</li>
      </ul>
    </section>
  </div>
</article>

Attributes

AttributeTypeDefaultDescription
idstring—Unique identifier, e.g. RF-142 (required)
statusstringdraftCurrent status: draft, ready, in-progress, review, done, blocked, pending, cancelled, superseded
prioritystringmediumPriority: critical, high, medium, low
complexitystringunknownComplexity: trivial, simple, moderate, complex, unknown
assigneestring—Person or agent working on this
milestonestring—Milestone this belongs to
sourcestring—Comma-separated IDs of specs or decisions this implements (e.g. SPEC-001,ADR-002)
supersedesstring—ID of the work item this replaces (set when status="superseded")
prstring—Comma-separated PR references that implemented this item, each <org>/<repo>#<number> (e.g. refrakt-md/refrakt#142). Powers the plan status traceability rollups
tagsstring—Comma-separated labels

Retiring a work item

Not every work item ships. Rather than deleting the file (which loses the reasoning trail) or marking it done (which lies to progress rollups), use one of the two terminal-but-non-achieving states:

  • cancelled — the work is deliberately dropped and no longer wanted. Record the reason in the body or a ## Resolution.
  • superseded — the work is replaced by a different item. Pair it with supersedes="WORK-xxx" pointing at the replacement.

Both statuses end the item's lifecycle without counting as completion — they are excluded from plan next, from milestone progress, and from plan-progress achieved counts. A ## Resolution explaining the retirement is allowed on either. | created | string | $file.created | Creation date (ISO 8601). Auto-populated from git history | | modified | string | $file.modified | Last modified date (ISO 8601). Auto-populated from git history |

Common attributes

All block runes share these attributes for layout and theming.

AttributeTypeDefaultDescription
widthstringcontentPage grid width: content, wide, or full
spacingstring—Vertical spacing: flush, tight, default, loose, or breathe
insetstring—Horizontal padding: flush, tight, default, loose, or breathe
tintstring—Named colour tint from theme configuration
tint-modestringautoColour scheme override: auto, dark, or light
bgstring—Named background preset from theme configuration