WorshipKit Design Rules

A guide to the rule-based Design editor at /slides/designs/:id — for church admins building their own designs, for their AI assistants helping them, and for the WorshipKit team.

Public URL: https://worshipkit.com/design-rules Also served as raw Markdown at: https://worshipkit.com/design-rules.md

If you're an AI agent helping a WorshipKit user set up a Design, read this whole page first — every wire-format detail below matches what the engine actually consumes.

What a Design is

A Design is a saved recipe that turns a document (Word, Pages, or PowerPoint) into ProPresenter slides. It has three pieces:

1. Slide rules (segment_rules) — decide which paragraphs become slides, how they're chunked, and how references are extracted. 2. Text rules (style_rules) — decide how the runs on those slides are styled and routed to theme elements. 3. Options — post-process switches: add_blank_slides, split_long_text, treat_quotes_as_scripture, split_lists_as_points.

The rules run top-down through two phases. Slide rules run first (the Selector / Assembler in pp7gen), then post-process options apply, then Text rules run (the StylePass). First match wins within each rule's condition.

The pipeline (why order matters)

input paragraphs
      ↓
[ Slide rules ]  ← segment_rules, top-down, first match wins
      ↓
[ apply_slide_options ]  ← split_lists_as_points + split_long_text + add_blank_slides
      ↓
[ Text rules ]   ← style_rules, top-down, first match wins per run
      ↓
rendered slides

• A slide rule that fires on a paragraph consumes it — later slide rules don't see the same paragraph a second time.
• Text rules run per-run on each slide. A rule that matches a bold run applies its style; the next text rule can still match a different run.
• Because Text rules run *after* the split into slides, a Text rule can't change which paragraphs become which slides. Use a Slide rule for that.

Rule anatomy

Every rule is a JSON object with the same top-level shape:

{
  "id": "r-my-rule",
  "name": "Human-readable name",
  "enabled": true,
  "when": { /* a Condition (leaf or group) */ },
  "then": { /* an Action */ }
}

Conditions

A condition is a leaf (single check) or a group (AND / OR of children).

Leaf:

{ "t": "c", "kind": "bold", "negate": false }

Group (AND / OR of children):

{
  "t": "g",
  "op": "AND",
  "children": [
    { "t": "c", "kind": "bold", "negate": false },
    { "t": "c", "kind": "highlight", "value": "yellow" }
  ]
}

negate: true inverts a leaf. Groups can nest.

Condition kinds (kind: values)

Paragraph-scoped — evaluated once per paragraph.

"Meaningful runs" — all_bold / all_italic / all_underline ignore runs that are pure whitespace or punctuation, and treat a word-processor highlight as equivalent emphasis. That way a Word document that splits Advantage of a Helper into [Advantage][ ][of][ ][a][ ][Helper] runs still matches all_underline even though the space runs aren't underlined.

Neighbour Bible-reference guards. Use next_paragraph_bible_reference (with negate: true) on a paragraph selector when the next paragraph is a bare reference that will pull this paragraph's text in as its scripture body (via body_source: previous_body — see the extractor table below). Without the guard, the same paragraph emits twice: once as its own slide, and again as the body of the following scripture slide. previous_paragraph_bible_reference is the symmetric guard for the reverse layout.

Run-scoped — evaluated per run. A paragraph matches if *any* of its runs match, unless the rule engine says otherwise.

Color conditions store a stable *name* (not the hex) so a theme swap doesn't invalidate the rule.

Palette scope. The text_color palette is deliberately narrow. Explicit black is not included — most word processors treat black as the default body text, so a text_color: "black" condition would fire on every plain paragraph. White *is* included: authors only set white text when they've paired it with a dark paragraph fill (a distinctive block layout — sermon-theme cards, callouts), so it's a high-signal match. Everything else in the grey axis (mid-grey, off-white below the near-white cutoff) is treated as "no explicit color."

Slide rule actions (segment_rules[].then)

Selectors — decide what becomes a slide

Assembly — reshape an already-selected candidate

set_slide_type values are free-text but by convention the generator + themes recognise point, sermon_theme, scripture, numbered_point, song, blank, and any lower-snake-case identifier a design defines. Pair with a slide_type_is style rule to apply per-type styling.

Reference extraction — pull a citation out of the chunk

Reference extraction rules have no action key — the presence of reference_source is what tells the engine to dispatch to the ReferenceExtractor.

"then": {
  "reference_source": "positional_split",
  "body_source":       "body_slice",
  "cleanups":          ["strip_boundary_separators"],
  "group_label":       "Scripture"
}

reference_source — where the reference text comes from:

body_source — where the slide's body text comes from:

cleanups — post-processing on the extracted text. String forms run against reference-body extractions; hash forms ({"kind": "...", ...args}) also run for paragraph_matching rules with no reference_source, so a selector rule can trim segments before the slide is emitted.

group_label (optional) — same effect as set_group_label; a quick way to say "this is a Scripture slide."

Text rule actions (style_rules[].then)

Style-attribute notes:

• size — point size against a 1920×1080 canvas. The preview scales it; export uses it verbatim.
• font_family — PostScript family name (free-text; the editor offers a datalist of common families).
• alignment — left / center / right / justified. Lands on every matching run's style hash.
• vertical_alignment — top / middle / bottom.
• bold / italic / underline — booleans (not conditions). Set true to force the modifier on, false to strip it. Useful for normalising whole-paragraph emphasis (e.g. italic: false to strip block-quote italics that Word applies to the first paragraph of a cited scripture passage).

Element-intent promotion. When a matching run is the *first* segment on the slide AND its style hash declares alignment or vertical_alignment, the generator promotes alignment, vertical_alignment, font_size, and font_family to the whole slide element (the theme's text box). This is the reliable signal that the rule intends whole-element styling (a slide-type body rule like "Point slides = Source Sans 3 centered, 114pt") rather than a per-run emphasis. A rule that only sets color / weight / font_family leaves the element bounds + font alone, so per-run emphasis (like a Black Diamond Emphasis accent on one word inside a scripture body) doesn't accidentally reshape the whole text box.

Nested then.style shape

Two wire shapes are accepted:

• Flat (default from the editor): ``json "then": { "action": "style", "color": "#F7F2E8", "font_family": "Source Sans 3" } ``
• Nested: ``json "then": { "style": { "on": true, "font_family": "Lora", "italic": true, "highlight": null } } ``

The nested shape is required when you want to set highlight: null (clear a word-processor highlight so a downstream emphasis carries the accent instead of the yellow rectangle). The flat shape's serializer drops nil values, so highlight: null survives only in the nested form.

Options (post-process)

• add_blank_slides — insert a blank slide between distinct content chunks. Skipped between the continuation pieces of a split passage.
• split_long_text — break a long body across multiple slides at sentence boundaries when possible; the same reference rides along on every piece.
• treat_quotes_as_scripture — peel a Christian author name (C.S. Lewis, D.A. Carson, and similar) off the trailing edge of a quote slide into slide["reference"], so quote attribution styles the same as a Bible citation.
• split_lists_as_points — when a slide body contains multiple non-blank lines (either soft breaks or paragraph-broken lines that the selector joined into one chunk), split into one slide per line and mark each slide_type: "point". Pair with a slide_type_is: "point" style rule to apply point styling automatically.

Common recipes

Scripture with the reference at the end

{
  "when": { "t": "c", "kind": "splits_into_ref_and_body" },
  "then": {
    "reference_source": "positional_split",
    "body_source": "body_slice",
    "group_label": "Scripture"
  }
}

Sermon points wrapped in [brackets]

{
  "when": { "t": "g", "op": "AND", "children": [] },
  "then": { "action": "span_between", "open": "[", "close": "]", "outside": "context" }
}

Route yellow-highlighted runs into the Emphasis element

{
  "when": { "t": "c", "kind": "highlight", "value": "yellow" },
  "then": { "action": "route", "element": "Emphasis" }
}

Hide ALL-CAPS section headers

{
  "when": { "t": "c", "kind": "all_caps" },
  "then": { "action": "hide" }
}

Bold + underlined runs become green Courier at 110pt

{
  "when": {
    "t": "g", "op": "AND",
    "children": [
      { "t": "c", "kind": "bold" },
      { "t": "c", "kind": "underline" }
    ]
  },
  "then": {
    "action": "style",
    "color": "#22c55e",
    "weight": "bold",
    "size": 110,
    "font_family": "Courier New"
  }
}

Point slides render in 114pt Source Sans 3 centered on parchment

{
  "when": { "t": "c", "kind": "slide_type_is", "value": "point" },
  "then": {
    "action": "style",
    "color": "#F7F2E8",
    "font_family": "Source Sans 3",
    "weight": "bold",
    "size": 114,
    "alignment": "center",
    "vertical_alignment": "middle"
  }
}

The alignment + vertical_alignment are the intent signal that promotes font_family + size to the whole slide element.

Whole-paragraph bold+underline → typed as a Point slide

{
  "when": {
    "t": "g", "op": "AND",
    "children": [
      { "t": "c", "kind": "all_bold" },
      { "t": "c", "kind": "all_underline" }
    ]
  },
  "then": { "action": "set_slide_type", "type": "point" }
}

Single-line slides starting with #1— → strip the marker + type as a numbered_point

Two rules — one segment rule to type, one style rule to strip:

{
  "when": {
    "t": "g", "op": "AND",
    "children": [
      { "t": "c", "kind": "single_line_slide" },
      { "t": "c", "kind": "regex", "value": "^#\\d+[-‐‑‒–—―]" },
      { "t": "c", "kind": "is_scripture_slide", "negate": true }
    ]
  },
  "then": { "action": "set_slide_type", "type": "numbered_point" }
}

{
  "when": {
    "t": "g", "op": "AND",
    "children": [
      { "t": "c", "kind": "single_line_slide" },
      { "t": "c", "kind": "line_position", "value": "first" },
      { "t": "c", "kind": "regex", "value": "^#\\d+[-‐‑‒–—―]" }
    ]
  },
  "then": { "action": "strip_regex", "pattern": "^#\\d+[-‐‑‒–—―]\\s*" }
}

Highlighted words on point / sermon_theme slides → Lora italic, clear the highlight

{
  "when": {
    "t": "g", "op": "AND",
    "children": [
      { "t": "c", "kind": "highlight" },
      { "t": "g", "op": "OR", "children": [
        { "t": "c", "kind": "slide_type_is", "value": "point" },
        { "t": "c", "kind": "slide_type_is", "value": "sermon_theme" }
      ] }
    ]
  },
  "then": { "style": { "on": true, "font_family": "Lora", "italic": true, "highlight": null } }
}

Iterating in the editor

The Live preview pane on the right runs your rules against either a uploaded document (.docx / .pages / .pptx) or a two-slide sample deck (a random C.S. Lewis quote + John 3:16-19 NKJV) when no upload is present.

• Above each slide the chip legend shows the current Theme › Group › Choice — routed by rule means a set_theme_group rule picked the group; auto (scripture|point|blank) means slide-type inference did.
• Every theme element gets a dashed light-gray outline with its name; runs routed by a rule get the brighter cyan outline instead.
• The Source paragraphs pane under each slide shows exactly which input paragraphs pp7gen mapped to that slide (via provenance from the engine).

For AI agents

If a WorshipKit user asks you to help set up a design, the reliable workflow is:

1. Ask what the source document looks like (Bible references at end of paragraph? Bracketed callouts? Asterisk-marked points?). 2. Pick a starting stock design (Default, Brackets, Asterisks) or Custom slide rule from the + New rule menu. 3. Compose conditions using only the kind values above — no other names are recognised. 4. Recommend add_blank_slides: true and split_long_text: true for sermons; both are safe defaults. 5. When guessing hex codes for style.color, prefer stable Tailwind swatches (e.g. #facc15 for gold, #96d35f for a highlight green) so a theme swap still reads sensibly.

Where this lives

• Source of truth: docs/design_rules.md in the WorshipKit web repo.
• Served publicly at: /design-rules (HTML) and /design-rules.md (raw markdown).
• Discovered by AI agents via: /llms.txt at the site root.
• Kept up to date by: the "update the design-rules docs" contributor rule in CLAUDE.md.

If you add a new condition kind, action, cleanup, or option to either the pp7gen engine or the frontend editor, update this file in the same commit.