Plan Runes

contentModel: {
  type: 'sequence',
  fields: [
    { name: 'title', match: 'heading', optional: false,
      template: '# Specification Title',
      description: 'Spec headline' },
    { name: 'summary', match: 'blockquote', optional: true,
      template: '> Brief description of scope and purpose.',
      description: 'Scope summary' },
    { name: 'body', match: 'any', optional: true, greedy: true,
      description: 'Full specification content — prose, diagrams, examples, code' },
  ],
}

{% spec id="SPEC-008" status="accepted" version="1.2" tags="tint,theming" %}

# Tint Rune

> Section-level colour context override via CSS custom properties.

## Problem

A page has a single colour context...

## Solution

`tint` is a core rune that overrides colour tokens within its parent
rune's scope...

{% /spec %}

contentModel: {
  type: 'sequence',
  fields: [
    { name: 'title', match: 'heading', optional: false,
      template: '# Work item title',
      description: 'What needs to be done' },
    { name: 'description', match: 'paragraph', optional: true, greedy: true,
      template: 'Description of what needs to change and why.',
      description: 'Context and motivation' },
    {
      name: 'sections',
      type: 'sections',
      sectionHeading: 'heading:2',
      knownSections: {
        'Acceptance Criteria': {
          alias: ['Criteria', 'AC', 'Done When'],
          type: 'sequence',
          fields: [
            { name: 'criteria', match: 'list', optional: false },
          ],
        },
        'Edge Cases': {
          alias: ['Exceptions', 'Corner Cases'],
          type: 'sequence',
          fields: [
            { name: 'cases', match: 'list', optional: false },
          ],
        },
        'Approach': {
          alias: ['Technical Notes', 'Implementation Notes', 'How'],
          type: 'sequence',
          fields: [
            { name: 'approach', match: 'any', optional: true, greedy: true },
          ],
        },
        'References': {
          alias: ['Refs', 'Related', 'Context'],
          type: 'sequence',
          fields: [
            { name: 'refs', match: 'list', optional: true },
          ],
        },
        'Verification': {
          alias: ['Test Cases', 'Tests'],
          type: 'sequence',
          fields: [
            { name: 'verification', match: 'any', optional: true, greedy: true },
          ],
        },
      },
      sectionModel: {
        type: 'sequence',
        fields: [
          { name: 'body', match: 'any', optional: true, greedy: true },
        ],
      },
    },
  ],
}

{% 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 so that tinted sections look
correct regardless of the user's colour scheme preference.

## 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` media query
- [ ] Inline tints without dark values fall back to page tokens in dark mode
- [ ] Inspector audits contrast ratios for both light and dark tint variants

## Edge Cases
- Tint with only dark values and `mode="dark"` — should work without light section
- Nested tints — inner tint should override outer tint's dark values
- Sandbox inside tinted section — should inherit dark tint tokens

## Approach
The identity transform parses `## Light` / `## Dark` headings within the
tint child rune body using the sections content model pattern. Dark values
are emitted as `--tint-dark-*` CSS custom properties alongside the light
values. The theme's base CSS swaps them via `@media (prefers-color-scheme: dark)`.

> Depends on {% ref "RF-138" /%}

## References
- {% ref "SPEC-008" /%} (Tint Rune Specification)
- {% ref "ADR-007" /%} (CSS custom properties for token injection)

## Verification
```markdoc
{% recipe name="Test" %}
{% tint %}
## Light
- background: #fdf6e3
## Dark
- background: #2a2118
{% /tint %}
{% /recipe %}
```

Expected: `data-tint-dark` attribute present, both `--tint-background`
and `--tint-dark-background` in inline style.

{% /work %}

contentModel: {
  type: 'sequence',
  fields: [
    { name: 'title', match: 'heading', optional: false,
      template: '# Bug title' },
    {
      name: 'sections',
      type: 'sections',
      sectionHeading: 'heading:2',
      knownSections: {
        'Steps to Reproduce': {
          alias: ['Reproduction', 'Steps', 'Repro'],
          type: 'sequence',
          fields: [
            { name: 'steps', match: 'list:ordered', optional: false },
          ],
        },
        'Expected': {
          alias: ['Expected Behaviour'],
          type: 'sequence',
          fields: [
            { name: 'expected', match: 'any', optional: false, greedy: true },
          ],
        },
        'Actual': {
          alias: ['Actual Behaviour'],
          type: 'sequence',
          fields: [
            { name: 'actual', match: 'any', optional: false, greedy: true },
          ],
        },
        'Environment': {
          alias: ['Env'],
          type: 'sequence',
          fields: [
            { name: 'environment', match: 'list', optional: false },
          ],
        },
      },
      sectionModel: {
        type: 'sequence',
        fields: [
          { name: 'body', match: 'any', optional: true, greedy: true },
        ],
      },
    },
  ],
}

{% 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 %}

contentModel: {
  type: 'sequence',
  fields: [
    { name: 'title', match: 'heading', optional: false,
      template: '# Decision title' },
    {
      name: 'sections',
      type: 'sections',
      sectionHeading: 'heading:2',
      knownSections: {
        'Context': {
          type: 'sequence',
          fields: [
            { name: 'context', match: 'any', optional: false, greedy: true },
          ],
        },
        'Options Considered': {
          alias: ['Options', 'Alternatives'],
          type: 'sequence',
          fields: [
            { name: 'options', match: 'any', optional: false, greedy: true },
          ],
        },
        'Decision': {
          type: 'sequence',
          fields: [
            { name: 'decision', match: 'any', optional: false, greedy: true },
          ],
        },
        'Rationale': {
          alias: ['Reasoning', 'Why'],
          type: 'sequence',
          fields: [
            { name: 'rationale', match: 'any', optional: false, greedy: true },
          ],
        },
        'Consequences': {
          alias: ['Impact', 'Trade-offs'],
          type: 'sequence',
          fields: [
            { name: 'consequences', match: 'any', optional: false, greedy: true },
          ],
        },
      },
      sectionModel: {
        type: 'sequence',
        fields: [
          { name: 'body', match: 'any', optional: true, greedy: true },
        ],
      },
    },
  ],
}

{% decision id="ADR-007" status="accepted" date="2026-03-11" source="SPEC-024" tags="tint,css" %}

# Use CSS custom properties for tint token injection

## Context
Tint runes need to override colour tokens within a section scope.
The solution must work without JavaScript and cascade through nested elements.

## Options Considered
1. **CSS custom properties on the container** — inline styles setting `--tint-*`
   tokens, theme bridges via `var()` fallbacks.
2. **Generated CSS classes per tint combination** — build step creates
   per-tint classes. Avoids inline styles but combinatorial explosion.
3. **JavaScript runtime token injection** — behaviour script reads data
   attributes and sets styles. Most flexible but requires JS.

## Decision
CSS custom properties via inline styles on the container element.

## Rationale
Custom properties cascade naturally through the DOM subtree without
JavaScript. Themes opt into tint support by including bridge CSS.
The `--tint-*` namespace avoids collisions with theme-internal tokens.

## Consequences
- Themes must include the tint bridge CSS
- Inline styles cannot use media queries — dark mode handled separately
- Inspector must audit tint token contrast ratios

{% /decision %}

contentModel: {
  type: 'sequence',
  fields: [
    { name: 'title', match: 'heading', optional: true },
    { name: 'goals', match: 'list', optional: true,
      template: '- Goal one\n- Goal two\n- Goal three',
      description: 'What this milestone delivers' },
    { name: 'notes', match: 'paragraph', optional: true, greedy: true,
      description: 'Context, retrospective notes, lessons learned' },
  ],
}

{% milestone name="v0.5.0" target="2026-03-29" status="active" %}

# v0.5.0 — Layout & Tint

- Complete alignment system migration
- Ship tint rune with dark mode support
- Publish layout spec as site documentation
- Resolve showcase bleed overflow bug

{% /milestone %}

{% backlog filter="status:ready priority:high" %}
{% backlog filter="milestone:v0.5.0" sort="priority" group="status" %}
{% backlog filter="assignee:bjorn status:in-progress" %}
{% backlog filter="tags:tint" show="work" %}