Plan›Spec

plan

Spec

Specification document with status tracking, versioning, and cross-referencing

Install

  1. Add the package: npm install @refrakt-md/plan
  2. Add it to the plugins array in refrakt.config.json: "plugins": ["@refrakt-md/plan"]

About the plugin and its runes

Source

import Markdoc from '@markdoc/markdoc';
const { Tag } = Markdoc;
import {
	createContentModelSchema,
	createComponentRenderable,
	renderNodes,
	fieldMetas,
} from '@refrakt-md/runes';
import { stripHorizontalRules } from '../util.js';
import { VALID_STATUS } from '../commands/enums.js';

export const specSections = { title: 'title', blurb: 'description', body: 'body' } as const;

export const spec = createContentModelSchema({
	sections: specSections,
	provides: ['prose'],
	attributes: {
		id: { type: String, required: true, description: 'Unique identifier (e.g., "SPEC-008").' },
		status: {
			type: String,
			required: false,
			matches: [...VALID_STATUS.spec],
			description:
				'Current status: draft, review, accepted, implemented, shipped, superseded, or deprecated.',
		},
		version: { type: String, required: false, description: 'Spec version (e.g., "1.0", "1.2").' },
		supersedes: { type: String, required: false, description: 'ID of the spec this replaces.' },
		'released-in': {
			type: String,
			required: false,
			description:
				'Release version this spec shipped in (semver, e.g. "v0.11.4"). Required when status="shipped".',
		},
		tags: { type: String, required: false, description: 'Comma-separated labels.' },
		created: {
			type: String,
			required: false,
			description: 'Creation date (ISO 8601). Defaults to file creation date from git.',
		},
		modified: {
			type: String,
			required: false,
			description: 'Last modified date (ISO 8601). Defaults to file modification date from git.',
		},
	},
	contentModel: {
		type: 'sequence',
		fields: [
			{ name: 'title', match: 'heading', optional: false },
			{ name: 'summary', match: 'paragraph', optional: true, greedy: true },
			{ name: 'body', match: 'any', optional: true, greedy: true },
		],
	},
	transform(resolved, attrs, config) {
		const titleNodes = renderNodes(resolved.title, config);
		const summaryNodes = renderNodes(resolved.summary, config);
		const bodyNodes = renderNodes(resolved.body, config);

		const title = titleNodes.wrap('header');
		const blurb = summaryNodes.count() > 0 ? summaryNodes.wrap('div').next() : undefined;
		const contentChildren: any[] = [];
		if (bodyNodes.count() > 0) {
			contentChildren.push(...stripHorizontalRules(bodyNodes.toArray()));
		}
		const bodyDiv = new Tag('div', {}, contentChildren);

		return createComponentRenderable({
			rune: 'spec',
			tag: 'article',
			properties: fieldMetas(attrs, config, {
				id: '',
				status: 'draft',
				version: '',
				supersedes: '',
				'released-in': '',
				tags: '',
				created: { from: ['attrs.created', 'file.created'], default: '' },
				modified: { from: ['attrs.modified', 'file.modified'], default: '' },
			}),
			refs: {
				title: title.tag('header'),
				blurb,
				body: bodyDiv,
			},
			children: [title.next(), ...(blurb ? [blurb] : []), bodyDiv],
		});
	},
});

View plugins/plan/src/tags/spec.ts on GitHub

Wraps a specification document, giving it status tracking, versioning, and entity registry integration. Specs are the source of truth for what the software should do. The body is intentionally freeform — specs vary widely in shape.

Accepted specification

A spec in accepted status with a version number and scope summary.

{% spec id="SPEC-9008" status="accepted" version="1.2" tags="tint,theming" %}
# Tint Rune

Section-level color context override via CSS custom properties.

## Problem

A page has a single color context. Some sections need a different palette — a dark hero, a branded callout, a seasonal promotion. Currently there is no way to override color tokens within a section scope.

## Solution

`tint` sets the colors of the rune it is placed in. An author names one of the theme's tints, or gives colors inline, and everything inside the rune uses them.
{% /spec %}
<article data-rune="spec" data-rune-fields="{&quot;id&quot;:&quot;SPEC-9008&quot;,&quot;status&quot;:&quot;accepted&quot;,&quot;version&quot;:&quot;1.2&quot;,&quot;supersedes&quot;:&quot;&quot;,&quot;released-in&quot;:&quot;&quot;,&quot;tags&quot;:&quot;tint,theming&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <header data-name="title">
    <h1 id="tint-rune">Tint Rune</h1>
  </header>
  <div data-name="blurb">
    <p>Section-level color context override via CSS custom properties.</p>
  </div>
  <div data-name="body">
    <h2 id="problem">Problem</h2>
    <p>A page has a single color context. Some sections need a different palette — a dark hero, a branded callout, a seasonal promotion. Currently there is no way to override color tokens within a section scope.</p>
    <h2 id="solution">Solution</h2>
    <p>
      <code>tint</code>
      sets the colors of the rune it is placed in. An author names one of the theme's tints, or gives colors inline, and everything inside the rune uses them.
    </p>
  </div>
</article>
SPEC-9008accepted

Tint Rune

Section-level color context override via CSS custom properties.

tinttheming

Problem

A page has a single color context. Some sections need a different palette — a dark hero, a branded callout, a seasonal promotion. Currently there is no way to override color tokens within a section scope.

Solution

tint sets the colors of the rune it is placed in. An author names one of the theme's tints, or gives colors inline, and everything inside the rune uses them.

<article class="rf-spec rf-spec--SPEC-9008 rf-spec--accepted rf-spec--1.2" data-id="SPEC-9008" data-status="accepted" data-version="1.2" data-supersedes="" data-released-in="" data-tags="tint,theming" data-created="2026-11-11" data-modified="2026-11-11" data-rune="spec" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-spec__eyebrow">
    <span data-meta-type="id" data-field="id">SPEC-9008</span>
    <span data-meta-type="status" data-meta-sentiment="positive" data-align="end" data-field="status">accepted</span>
  </div>
  <header data-name="title" class="rf-spec__title" data-section="title">
    <h1 id="tint-rune">Tint Rune</h1>
  </header>
  <div data-name="blurb" class="rf-spec__blurb" data-section="description">
    <p>Section-level color context override via CSS custom properties.</p>
  </div>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-spec__metadata">
    <div data-name="row" data-field="version" class="rf-spec__row">
      <dt data-meta-label="">Version</dt>
      <dd>
        <span data-meta-type="tag">1.2</span>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-spec__row">
      <dt data-meta-label="">Created</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-spec__row">
      <dt data-meta-label="">Modified</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
  </dl>
  <div data-name="tags" data-zone="tags" data-zone-layout="bar" class="rf-spec__tags">
    <span data-meta-type="tag" data-field="tags">tint</span>
    <span data-meta-type="tag" data-field="tags">theming</span>
  </div>
  <div data-name="body" class="rf-spec__body" data-section="body">
    <h2 id="problem">Problem</h2>
    <p>A page has a single color context. Some sections need a different palette — a dark hero, a branded callout, a seasonal promotion. Currently there is no way to override color tokens within a section scope.</p>
    <h2 id="solution">Solution</h2>
    <p>
      <code>tint</code>
       sets the colors of the rune it is placed in. An author names one of the theme's tints, or gives colors inline, and everything inside the rune uses them.
    </p>
  </div>
</article>

How Markdown is read

You writeIt becomes
A headingThe spec's title
The paragraphs right after itThe spec's summary
Everything after themThe body, in the order written

Draft specification

A minimal spec in draft status.

{% spec id="SPEC-9012" status="draft" %}
# Dependency Graph Visualisation

Render entity relationships as an interactive graph.

This spec is not yet written. It will cover the visual representation of cross-references between specs, work items, and decisions.
{% /spec %}
<article data-rune="spec" data-rune-fields="{&quot;id&quot;:&quot;SPEC-9012&quot;,&quot;status&quot;:&quot;draft&quot;,&quot;version&quot;:&quot;&quot;,&quot;supersedes&quot;:&quot;&quot;,&quot;released-in&quot;:&quot;&quot;,&quot;tags&quot;:&quot;&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <header data-name="title">
    <h1 id="dependency-graph-visualisation">Dependency Graph Visualisation</h1>
  </header>
  <div data-name="blurb">
    <p>Render entity relationships as an interactive graph.</p>
    <p>This spec is not yet written. It will cover the visual representation of cross-references between specs, work items, and decisions.</p>
  </div>
  <div data-name="body"></div>
</article>
SPEC-9012draft

Dependency Graph Visualisation

Render entity relationships as an interactive graph.

This spec is not yet written. It will cover the visual representation of cross-references between specs, work items, and decisions.

<article class="rf-spec rf-spec--SPEC-9012 rf-spec--draft" data-id="SPEC-9012" data-status="draft" data-version="" data-supersedes="" data-released-in="" data-tags="" data-created="2026-11-11" data-modified="2026-11-11" data-rune="spec" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-spec__eyebrow">
    <span data-meta-type="id" data-field="id">SPEC-9012</span>
    <span data-meta-type="status" data-meta-sentiment="neutral" data-align="end" data-field="status">draft</span>
  </div>
  <header data-name="title" class="rf-spec__title" data-section="title">
    <h1 id="dependency-graph-visualisation">Dependency Graph Visualisation</h1>
  </header>
  <div data-name="blurb" class="rf-spec__blurb" data-section="description">
    <p>Render entity relationships as an interactive graph.</p>
    <p>This spec is not yet written. It will cover the visual representation of cross-references between specs, work items, and decisions.</p>
  </div>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-spec__metadata">
    <div data-name="row" data-field="created" class="rf-spec__row">
      <dt data-meta-label="">Created</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-spec__row">
      <dt data-meta-label="">Modified</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
  </dl>
  <div data-name="body" class="rf-spec__body" data-section="body"></div>
</article>

Superseded specification

A spec that has been replaced by a newer version.

{% spec id="SPEC-9003" status="superseded" version="1.0" supersedes="SPEC-9001" %}
# Original Token System

First-generation design token architecture.

This specification has been superseded. See the current token system specification for the active design.
{% /spec %}
<article data-rune="spec" data-rune-fields="{&quot;id&quot;:&quot;SPEC-9003&quot;,&quot;status&quot;:&quot;superseded&quot;,&quot;version&quot;:&quot;1.0&quot;,&quot;supersedes&quot;:&quot;SPEC-9001&quot;,&quot;released-in&quot;:&quot;&quot;,&quot;tags&quot;:&quot;&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <header data-name="title">
    <h1 id="original-token-system">Original Token System</h1>
  </header>
  <div data-name="blurb">
    <p>First-generation design token architecture.</p>
    <p>This specification has been superseded. See the current token system specification for the active design.</p>
  </div>
  <div data-name="body"></div>
</article>
SPEC-9003superseded

Original Token System

First-generation design token architecture.

This specification has been superseded. See the current token system specification for the active design.

<article class="rf-spec rf-spec--SPEC-9003 rf-spec--superseded rf-spec--1.0 rf-spec--SPEC-9001" data-id="SPEC-9003" data-status="superseded" data-version="1.0" data-supersedes="SPEC-9001" data-released-in="" data-tags="" data-created="2026-11-11" data-modified="2026-11-11" data-rune="spec" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-spec__eyebrow">
    <span data-meta-type="id" data-field="id">SPEC-9003</span>
    <span data-meta-type="status" data-meta-sentiment="caution" data-align="end" data-field="status">superseded</span>
  </div>
  <header data-name="title" class="rf-spec__title" data-section="title">
    <h1 id="original-token-system">Original Token System</h1>
  </header>
  <div data-name="blurb" class="rf-spec__blurb" data-section="description">
    <p>First-generation design token architecture.</p>
    <p>This specification has been superseded. See the current token system specification for the active design.</p>
  </div>
  <dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-spec__metadata">
    <div data-name="row" data-field="version" class="rf-spec__row">
      <dt data-meta-label="">Version</dt>
      <dd>
        <span data-meta-type="tag">1.0</span>
      </dd>
    </div>
    <div data-name="row" data-field="supersedes" class="rf-spec__row">
      <dt data-meta-label="">Supersedes</dt>
      <dd>
        <span data-meta-type="id">SPEC-9001</span>
      </dd>
    </div>
    <div data-name="row" data-field="created" class="rf-spec__row">
      <dt data-meta-label="">Created</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
    <div data-name="row" data-field="modified" class="rf-spec__row">
      <dt data-meta-label="">Modified</dt>
      <dd>
        <time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
      </dd>
    </div>
  </dl>
  <div data-name="body" class="rf-spec__body" data-section="body"></div>
</article>

Lifecycle: accepted → implemented → shipped

accepted means the team agreed to build the spec. Two further states close the loop between agreement and availability:

  • implemented — every work item that sources this spec is done and the code is in main. refrakt plan status suggests this flip once all linked work is done.
  • shipped — released to users in an npm version. Pair it with released-in="vX.Y.Z"; plan validate errors on a shipped spec that lacks it.

Attributes

AttributeTypeRequiredDescription
idstring✓Unique identifier (e.g., "SPEC-008").
status"draft" | "review" | "accepted" | "implemented" | "shipped" | "superseded" | "deprecated"—Current status: draft, review, accepted, implemented, shipped, superseded, or deprecated.
versionstring—Spec version (e.g., "1.0", "1.2").
supersedesstring—ID of the spec this replaces.
released-instring—Release version this spec shipped in (semver, e.g. "v0.11.4"). Required when status="shipped".
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: 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.

AttributeTypeRequiredDescription
dropcapboolean—Style the opening letter of a prose body as a drop cap. Honoured only when the body reads as prose; ignored otherwise.
elevation

How far the rune sits off the page, from sunken to overlay. The theme decides what each step looks like.

AttributeTypeRequiredDescription
elevation"sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg"—Surface depth, from sunken to overlay. Deprecated: none, sm, md and lg (read as flat, raised, raised and floating)
inset

Internal padding override.

AttributeTypeRequiredDescription
inset"flush" | "tight" | "default" | "loose" | "breathe"—Inner padding of this block
motion

Scroll-reveal entrance. You choose its character; the theme decides how it moves.

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. Scales a rune's header, or its featured quotation; the theme decides the type size for each step.

AttributeTypeRequiredDescription
prominence"quiet" | "normal" | "prominent" | "display" | "marquee"—Emphasis of a page-section header or a featured quotation (only on runes that have one)
reading

Editorial register for body text. You pick the register; the theme decides how it looks.

AttributeTypeRequiredDescription
reading"fine" | "ui" | "prose"—Reading register for this block’s body: fine | ui | prose. The theme sets how each one looks.
spacing

Block-level rhythm override.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills behind the content, drawn by the theme.

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: 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