refrakt.md

Docs Runes Plan Blog Changelog

note

This rune is part of @refrakt-md/plan. Install with npm install @refrakt-md/plan and add "@refrakt-md/plan" to the packages 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">
  <meta content="RF-142" data-field="id">
  <meta content="ready" data-field="status">
  <meta content="high" data-field="priority">
  <meta content="moderate" data-field="complexity">
  <meta content="" data-field="assignee">
  <meta content="v0.5.0" data-field="milestone">
  <meta content="tint,theming" data-field="tags">
  <meta content="2026-04-10" data-field="created">
  <meta content="2026-04-10" data-field="modified">
  <header data-name="title">
    <h1 id="implement-tint-rune-dark-mode-support">Implement tint rune dark mode support</h1>
  </header>
  <div data-name="body">
    <div>
      <p>The tint rune currently handles single-scheme colour tokens. It needs to support dual light/dark definitions.</p>
    </div>
    <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>
ID:RF-142Status:readyPriority:highComplexity:moderateMilestone:v0.5.0

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.

<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-milestone="v0.5.0" data-tags="tint,theming" data-created="2026-04-10" data-modified="2026-04-10" data-rune="work" data-density="full">
  <div data-name="header" class="rf-work__header" data-section="header">
    <span data-name="id-badge" data-meta-type="id" data-meta-rank="primary" class="rf-work__id-badge">
      <span data-meta-label="" data-meta-label-hidden="">ID:</span>
      <span data-meta-value="">RF-142</span>
    </span>
    <span data-name="status-badge" data-meta-type="status" data-meta-rank="primary" data-meta-sentiment="neutral" class="rf-work__status-badge">
      <span data-meta-label="" data-meta-label-hidden="">Status:</span>
      <span data-meta-value="">ready</span>
    </span>
    <span data-name="priority-badge" data-meta-type="category" data-meta-rank="primary" data-meta-sentiment="caution" class="rf-work__priority-badge">
      <span data-meta-label="">Priority:</span>
      <span data-meta-value="">high</span>
    </span>
    <span data-name="complexity-badge" data-meta-type="quantity" data-meta-rank="secondary" class="rf-work__complexity-badge">
      <span data-meta-label="">Complexity:</span>
      <span data-meta-value="">moderate</span>
    </span>
    <span data-name="milestone-badge" data-meta-type="tag" data-meta-rank="secondary" class="rf-work__milestone-badge">
      <span data-meta-label="">Milestone:</span>
      <span data-meta-value="">v0.5.0</span>
    </span>
    <time data-name="created-badge" data-meta-type="temporal" data-meta-rank="secondary" class="rf-work__created-badge">
      <span data-meta-label="">Created:</span>
      <span data-meta-value="">2026-04-10</span>
    </time>
    <time data-name="modified-badge" data-meta-type="temporal" data-meta-rank="secondary" class="rf-work__modified-badge">
      <span data-meta-label="">Modified:</span>
      <span data-meta-value="">2026-04-10</span>
    </time>
  </div>
  <div data-name="body" class="rf-work__body" data-section="body">
    <meta content="RF-142" data-field="id" />
    <meta content="ready" data-field="status" />
    <meta content="high" data-field="priority" />
    <meta content="moderate" data-field="complexity" />
    <meta content="" data-field="assignee" />
    <meta content="v0.5.0" data-field="milestone" />
    <meta content="tint,theming" data-field="tags" />
    <meta content="2026-04-10" data-field="created" />
    <meta content="2026-04-10" data-field="modified" />
    <header data-name="title" class="rf-work__title">
      <h1 id="implement-tint-rune-dark-mode-support">Implement tint rune dark mode support</h1>
    </header>
    <div data-name="body" class="rf-work__body" data-section="body">
      <div>
        <p>The tint rune currently handles single-scheme colour tokens. It needs to support dual light/dark definitions.</p>
      </div>
      <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>
  </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">
  <meta content="RF-215" data-field="id">
  <meta content="blocked" data-field="status">
  <meta content="medium" data-field="priority">
  <meta content="complex" data-field="complexity">
  <meta content="alice" data-field="assignee">
  <meta content="" data-field="milestone">
  <meta content="" data-field="tags">
  <meta content="2026-04-10" data-field="created">
  <meta content="2026-04-10" data-field="modified">
  <header data-name="title">
    <h1 id="alignment-system-migration">Alignment system migration</h1>
  </header>
  <div data-name="body">
    <div>
      <p>Migrate all runes from manual alignment classes to the new alignment system.</p>
    </div>
    <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>
ID:RF-215Status:blockedPriority:mediumComplexity:complexAssignee: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
<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-created="2026-04-10" data-modified="2026-04-10" data-rune="work" data-density="full">
  <div data-name="header" class="rf-work__header" data-section="header">
    <span data-name="id-badge" data-meta-type="id" data-meta-rank="primary" class="rf-work__id-badge">
      <span data-meta-label="" data-meta-label-hidden="">ID:</span>
      <span data-meta-value="">RF-215</span>
    </span>
    <span data-name="status-badge" data-meta-type="status" data-meta-rank="primary" data-meta-sentiment="negative" class="rf-work__status-badge">
      <span data-meta-label="" data-meta-label-hidden="">Status:</span>
      <span data-meta-value="">blocked</span>
    </span>
    <span data-name="priority-badge" data-meta-type="category" data-meta-rank="primary" data-meta-sentiment="neutral" class="rf-work__priority-badge">
      <span data-meta-label="">Priority:</span>
      <span data-meta-value="">medium</span>
    </span>
    <span data-name="complexity-badge" data-meta-type="quantity" data-meta-rank="secondary" class="rf-work__complexity-badge">
      <span data-meta-label="">Complexity:</span>
      <span data-meta-value="">complex</span>
    </span>
    <span data-name="assignee-badge" data-meta-type="tag" data-meta-rank="secondary" class="rf-work__assignee-badge">
      <span data-meta-label="">Assignee:</span>
      <span data-meta-value="">alice</span>
    </span>
    <time data-name="created-badge" data-meta-type="temporal" data-meta-rank="secondary" class="rf-work__created-badge">
      <span data-meta-label="">Created:</span>
      <span data-meta-value="">2026-04-10</span>
    </time>
    <time data-name="modified-badge" data-meta-type="temporal" data-meta-rank="secondary" class="rf-work__modified-badge">
      <span data-meta-label="">Modified:</span>
      <span data-meta-value="">2026-04-10</span>
    </time>
  </div>
  <div data-name="body" class="rf-work__body" data-section="body">
    <meta content="RF-215" data-field="id" />
    <meta content="blocked" data-field="status" />
    <meta content="medium" data-field="priority" />
    <meta content="complex" data-field="complexity" />
    <meta content="alice" data-field="assignee" />
    <meta content="" data-field="milestone" />
    <meta content="" data-field="tags" />
    <meta content="2026-04-10" data-field="created" />
    <meta content="2026-04-10" data-field="modified" />
    <header data-name="title" class="rf-work__title">
      <h1 id="alignment-system-migration">Alignment system migration</h1>
    </header>
    <div data-name="body" class="rf-work__body" data-section="body">
      <div>
        <p>Migrate all runes from manual alignment classes to the new alignment system.</p>
      </div>
      <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>
  </div>
</article>

Attributes

AttributeTypeDefaultDescription
idstring—Unique identifier, e.g. RF-142 (required)
statusstringdraftCurrent status: draft, ready, in-progress, review, done, blocked
prioritystringmediumPriority: critical, high, medium, low
complexitystringunknownComplexity: trivial, simple, moderate, complex, unknown
assigneestring—Person or agent working on this
milestonestring—Milestone this belongs to
tagsstring—Comma-separated labels
createdstring$file.createdCreation date (ISO 8601). Auto-populated from git history
modifiedstring$file.modifiedLast 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