{
  "layer": "grammar",
  "title": "Pick a block and compose the card",
  "spec": "supercard",
  "version": "3.2.0",
  "era": "atlas",
  "spec_revision": "05290259e680",
  "summary": "The seven-beat narrative spine (Hook → Evidence → Mechanism → Comparison → Counter → Application → Close), the single block-selection procedure (10 ordered steps that walk the decision tree, precedence, density budget, prose rules, anti-patterns, gates), and the V3.1+ rules (G-7–G-11) woven into the decision tree itself.",
  "source": "10-GOVERNANCE/GRAMMAR-block-composition.md",
  "provenance": [
    {
      "file": "10-GOVERNANCE/GRAMMAR-block-composition.md",
      "updated": "2026-05-16",
      "version": "3.2.0",
      "sha256": "8f1e220326076c6d1564cfd3e1b43681624a42354ce6b126625dddd4684d522e"
    }
  ],
  "data": {
    "seven_beat_spine": [
      {
        "n": 1,
        "name": "Hook",
        "role": "card-in-hero. The Postcard inheritance. One screenshot conveys the entire essence."
      },
      {
        "n": 2,
        "name": "Evidence",
        "role": "why this matters. Stat callout, stat grid, bar chart."
      },
      {
        "n": 3,
        "name": "Mechanism",
        "role": "how it works. Process, diagram, definition, code."
      },
      {
        "n": 4,
        "name": "Comparison",
        "role": "what it's NOT. Comparison block, slope chart, table."
      },
      {
        "n": 5,
        "name": "Counter",
        "role": "honest steelman. Anti-pattern, opposing quote, distribution."
      },
      {
        "n": 6,
        "name": "Application",
        "role": "so what / how to act. Checklist, principle, FAQ."
      },
      {
        "n": 7,
        "name": "Close",
        "role": "bottom line. Key takeaway or pull-quote."
      }
    ],
    "block_selection_procedure": [
      {
        "step": 1,
        "name": "Shape-first match",
        "action": "run the decision tree below; record the first branch that matches (subject to precedence)."
      },
      {
        "step": 2,
        "name": "Apply precedence",
        "action": "if the unit matched multiple branches, use the precedence list to pick one and only one block."
      },
      {
        "step": 3,
        "name": "Apply length-variant filter",
        "action": "drop candidates whose `length_variants` (in `INDEX-block-library`) don't include the card's target length."
      },
      {
        "step": 4,
        "name": "Apply lifecycle filter",
        "action": "Core/Stable only. Experimental requires an explicit ask from the user."
      },
      {
        "step": 5,
        "name": "Apply mode's block bias",
        "action": "favour the modes table's `block_bias` blocks where the choice is otherwise a tie."
      },
      {
        "step": 6,
        "name": "Apply density budget (G-9)",
        "action": "count the beat's anchor and content blocks so far. If adding the candidate would violate the 1:2–1:4 anchor-to-content ratio, or exceed 2 same-type consecutive anchors, or exceed 4 consecutive content blocks, recast or swap. Insert a mid-beat asterism rest (G-10) instead when the limit is 4 content blocks and a switch isn't warranted."
      },
      {
        "step": 7,
        "name": "Apply prose rules (G-7, G-8) if the result is a prose block",
        "action": "every `standard-text`, `faq` answer, and `code` block opens with a 2–6-word bolded lead-clause (that bolded run *is* the block's one emphasis). Split at 75 words or 4 sentences."
      },
      {
        "step": 8,
        "name": "Apply block-specific V3.1 rules",
        "action": "`stat-callout` requires a verbal anchor; `table` with ≥ 4 data rows requires a `**Takeaway**` row (G-11); `pull-quote` requires attribution; `code` requires a bolded gloss."
      },
      {
        "step": 9,
        "name": "Apply anti-pattern check",
        "action": "run the unit against the anti-patterns table below. Any match → re-cast."
      },
      {
        "step": 10,
        "name": "Run constraint gates",
        "action": "at draft completion, the card runs the gates in `PIPELINE § Stage 4`. Block selection inputs to gates G1, G2, G7, G8."
      }
    ],
    "decision_tree_precedence": [
      {
        "rank": 1,
        "family": "Numeric",
        "rule": "if the unit has a focal number, treat it as numeric. (A \"list of don'ts\" with a count is still anti-pattern, not stat-grid; numbers are *load-bearing* iff the number itself is the takeaway.)"
      },
      {
        "rank": 2,
        "family": "Comparative",
        "rule": "if the unit is fundamentally A-vs-B (parallel items on a shared axis), treat it as comparative."
      },
      {
        "rank": 3,
        "family": "Sequential",
        "rule": "if order matters (dated, stepwise, causal chain), treat it as sequential."
      },
      {
        "rank": 4,
        "family": "Distributional",
        "rule": "if the unit shows shape across a population, treat it as distributional."
      },
      {
        "rank": 5,
        "family": "Definitional",
        "rule": "if the unit names a term, a numbered rule, code, or an equation."
      },
      {
        "rank": 6,
        "family": "Editorial structural",
        "rule": "dividers, asterism rests, loft-cards, footnotes. These are *furniture*, not content; resort to them only when their structural job is the point."
      },
      {
        "rank": 7,
        "family": "Editorial prose",
        "rule": "anti-pattern, checklist, FAQ, pull-quote, table, key-takeaway. The catalogued prose containers."
      },
      {
        "rank": 8,
        "family": "Standard text",
        "rule": "the residual fallback."
      }
    ],
    "note": "Beats are authoring scaffolding. The rendered card labels each section with the beat NAME only — never the Beat N index or the BLOCK-* id. Full decision tree, adjacency rules, density budget (G-9), prose rules (G-7/G-8), asterism rest (G-10), table takeaway-row (G-11), and the anti-patterns table are in doc_markdown. A numeric worked example of the procedure is in the example layer."
  },
  "see_also": [
    "blocks",
    "lengths",
    "principles",
    "example"
  ],
  "doc_markdown": "# GRAMMAR — Block Composition\n\n| key | value |\n|---|---|\n| id | GRAMMAR-block-composition |\n| type | governance |\n| era | atlas |\n| version | 3.2.0 |\n| owner | derick |\n| updated | 2026-05-16 |\n\nHow blocks combine into a Supercard. PRINCIPLES says *what we're doing*; this doc says *how to assemble it*. The block-selection procedure (below) is the single composed routine an agent walks for every section.\n\n---\n\n## The seven-beat narrative spine\n\nEvery Supercard moves through some subset of these beats, in order:\n\n1. **Hook** — card-in-hero. The Postcard inheritance. One screenshot conveys the entire essence.\n2. **Evidence** — why this matters. Stat callout, stat grid, bar chart.\n3. **Mechanism** — how it works. Process, diagram, definition, code.\n4. **Comparison** — what it's NOT. Comparison block, slope chart, table.\n5. **Counter** — honest steelman. Anti-pattern, opposing quote, distribution.\n6. **Application** — so what / how to act. Checklist, principle, FAQ.\n7. **Close** — bottom line. Key takeaway or pull-quote.\n\n**Length scaling:**\n\n- **Mini (5–8 blocks)** — Beats 1, 2, 3, 6, 7 only. One block per beat.\n- **Standard (10–14 blocks)** — All 7 beats, mostly single block per beat.\n- **XL (18–25 blocks)** — All 7 beats, multi-block per beat with internal rhythm.\n\nNever run more than 3 long sections in a row. Section dividers mark beat boundaries only — chapter breaks, not paragraph breaks. Above 25 blocks → split into a multi-part Supercard.\n\n**Beats are authoring scaffolding, not public labels.** The markdown card names each section by beat *and* block type (`Beat 7 · Close` / `BLOCK-pull-quote`) — that is authoring metadata, and it stays in the markdown. The *rendered* card labels each section with the beat **name only** (`CLOSE`); it never shows the `Beat N` index or the `BLOCK-*` id. A render is a shareable artifact — see `RENDERING-spec` § Output contract.\n\n## Block selection procedure (the one routine)\n\nFor each unit of content the breakdown produces, walk these steps **in order**. Each step is either a filter (eliminates candidates) or a transform (rewrites the unit). Don't skip; the steps depend on each other.\n\n1. **Shape-first match** — run the decision tree below; record the first branch that matches (subject to precedence).\n2. **Apply precedence** — if the unit matched multiple branches, use the precedence list to pick one and only one block.\n3. **Apply length-variant filter** — drop candidates whose `length_variants` (in `INDEX-block-library`) don't include the card's target length.\n4. **Apply lifecycle filter** — Core/Stable only. Experimental requires an explicit ask from the user.\n5. **Apply mode's block bias** — favour the modes table's `block_bias` blocks where the choice is otherwise a tie.\n6. **Apply density budget (G-9)** — count the beat's anchor and content blocks so far. If adding the candidate would violate the 1:2–1:4 anchor-to-content ratio, or exceed 2 same-type consecutive anchors, or exceed 4 consecutive content blocks, recast or swap. Insert a mid-beat asterism rest (G-10) instead when the limit is 4 content blocks and a switch isn't warranted.\n7. **Apply prose rules (G-7, G-8)** if the result is a prose block — every `standard-text`, `faq` answer, and `code` block opens with a 2–6-word bolded lead-clause (that bolded run *is* the block's one emphasis). Split at 75 words or 4 sentences.\n8. **Apply block-specific V3.1 rules** — `stat-callout` requires a verbal anchor; `table` with ≥ 4 data rows requires a `**Takeaway**` row (G-11); `pull-quote` requires attribution; `code` requires a bolded gloss.\n9. **Apply anti-pattern check** — run the unit against the anti-patterns table below. Any match → re-cast.\n10. **Run constraint gates** — at draft completion, the card runs the gates in `PIPELINE § Stage 4`. Block selection inputs to gates G1, G2, G7, G8.\n\nA worked numeric walk of this procedure on a Mini-mode card is in `EXAMPLE-mini-supercard`.\n\n## The decision tree (shape-first, text last)\n\nFor each section's content, run this in order. Stop at the first match, **subject to the precedence rules below**.\n\nIs the content primarily a NUMBER?\n\n- 1 number → Stat callout *(requires a verbal anchor sentence — V3.1+)*\n- 2-6 parallel → Stat grid\n- number over time → Sparkline (inline) or Line chart (full)\n- number vs threshold → Gauge / Bullet chart\n- number + context → Annotated single data point\n\nIs the content a COMPARISON of 2-3 things?\n\n- text comparison → Comparison block\n- numeric magnitude (vertical bars) → Column chart\n- numeric magnitude (horizontal bars) → Bar chart\n- change between two → Slope chart\n- 2D positioning → Scatter / quadrant\n- ranking → Dot plot\n\nIs the content a SERIES OF STEPS?\n\n- undated → Process / flow\n- dated → Timeline\n- continuous trend → Line chart\n- cumulative trend (under-curve volume matters) → Area chart\n\nIs the content a DISTRIBUTION?\n\n- frequency by bucket → Histogram\n- two-axis density → Heatmap\n- part-of-whole at fixed granularity → Waffle\n- repeated parallel patterns → Small multiples\n\n- Is the content a DEFINITION? → Definition block\n- Is the content a NUMBERED RULE? → Numbered principle\n- Is the content TECHNICAL/CODE? → Code *(requires a bolded gloss above the `<pre>` — V3.1+)*\n- Is the content MATHEMATICAL? → Equation\n\nIs the content STRUCTURAL FURNITURE (navigation/rest, not content)?\n\n- beat boundary → Section divider\n- mid-beat rest after every 4 content blocks in a beat of ≥ 5 → Asterism rest *(V3.1+; see G-10)*\n- elevated callout earning loft → Loft-card\n- aggregated sources → Footnote / source aggregator\n\nIs the content EDITORIAL PROSE (the residuals)?\n\n- Is the content a LIST OF DON'Ts? → Anti-pattern\n- Is the content a CHECKLIST of actions? → Checklist\n- Is the content a flashcard-style Q/A list? → Flashcard list\n- Is the content a FAQ-style question? → FAQ *(answer takes a bolded lead-clause — V3.1+)*\n- Is the content a verbatim lift from a source? → Pull quote / Quote-as-evidence\n- Is the content STRUCTURED ROWS/COLS? → Table (sparingly) *(≥ 4 rows requires a `**Takeaway**` row — V3.1+)*\n- Is the content an image with explanatory marks? → Annotated visual / Image with caption\n- Is the content a SYNTHESIS/TAKEAWAY? → Key takeaway\n\n(Default fallback) → Standard text block *(opens with a 2–6-word bolded lead-clause; ≤ 75 words, ≤ 4 sentences — V3.1+)*\n\nText is the **residual** category, not the first choice. The inverse of how most synthesis is drafted.\n\n## Decision tree precedence (when a unit matches more than one branch)\n\nThe tree says \"stop at the first match\" — but a dated list of don'ts hits SERIES OF STEPS, COMPARISON (don't vs. do), and the editorial anti-pattern branch all at once. Use this order when ambiguity remains. Higher branches win.\n\n1. **Numeric** — if the unit has a focal number, treat it as numeric. (A \"list of don'ts\" with a count is still anti-pattern, not stat-grid; numbers are *load-bearing* iff the number itself is the takeaway.)\n2. **Comparative** — if the unit is fundamentally A-vs-B (parallel items on a shared axis), treat it as comparative.\n3. **Sequential** — if order matters (dated, stepwise, causal chain), treat it as sequential.\n4. **Distributional** — if the unit shows shape across a population, treat it as distributional.\n5. **Definitional** — if the unit names a term, a numbered rule, code, or an equation.\n6. **Editorial structural** — dividers, asterism rests, loft-cards, footnotes. These are *furniture*, not content; resort to them only when their structural job is the point.\n7. **Editorial prose** — anti-pattern, checklist, FAQ, pull-quote, table, key-takeaway. The catalogued prose containers.\n8. **Standard text** — the residual fallback.\n\n**Explicit overrides:**\n\n- **List-of-don'ts → Anti-pattern**, even when sequential-looking — the editorial framing carries the load, not the order.\n- **Dated stat → Stat callout + caption** in Mini; **Sparkline / Line chart** in Standard/XL — Mini's density budget cannot afford a chart, so the time dimension goes into the caption.\n- **Numbered principle vs. Numbered rule list → Numbered principle** when the principles are independent and each is the single emphasis of its block; **Checklist** when the items are subordinate actions on one shared verb.\n- **Verbatim quote → Quote-as-evidence** in Beat 2 (Evidence) or Beat 5 (Counter); **Pull-quote** in Beat 7 (Close). Same shape, different anchoring role.\n- **Table → Key takeaway** when the table is < 4 rows and its verdict fits in one sentence — the table's furniture overhead isn't earned.\n- **Standard text** is *never* a tie-breaker. If two non-text branches matched, pick the higher one in the precedence list, even if standard-text would feel \"safer.\" Standard text is residual.\n\n## Adjacency rules\n\n**Default: no two adjacent blocks are identical.** Prevents monotony.\n\n**Two principled exceptions:**\n\n1. **Parallel comparison** — three stat callouts showing three metrics on the same dimension is small multiples, not duplication\n2. **Beat consistency** — three anti-patterns in a row inside Beat 5 is honest; varying the block type would be disingenuous\n\nTest for the exceptions: identical-block runs are OK only if they present parallel information the reader is meant to compare. If there's no comparative payoff, vary the type.\n\n## The redundancy filter\n\nBefore any block ships, ask: *what unique element does this add that's not in any other block on this Supercard?*\n\nIf the answer is \"nothing\" or \"restates the thesis,\" cut the block.\n\n## G-7. Bolded lead-clause on prose blocks (V3.1+)\n\nEvery `standard-text`, `faq` answer, and `code` block opens with a 2–6-word **bolded clause** that names the block's thesis.\n\n- The lead-clause MUST be a noun phrase or imperative — never a hedge, never an interjection (\"Well,\", \"So,\", \"It turns out\").\n- The lead-clause **is** the block's single emphasis (principle 2). No second bold run may appear in the same block.\n- Italics are reserved for titles of works and foreign terms; never for emphasis (Rello & Baeza-Yates 2016 — italics are the worst-performing style for dyslexic and ADHD readers).\n- `code` blocks satisfy this rule via a one-line bolded gloss above the `<pre>` (e.g., **`What this snippet does.`**), not by bolding inside the code itself.\n\n## G-8. Thought-group ramp inside prose blocks (V3.1+)\n\n`standard-text` blocks MUST NOT exceed **75 words** or **4 sentences**. Inside a block, sentences group into thought-groups (1–3 sentences each) separated by whitespace alone — never by rules, bullets, or chrome.\n\n| Spacing token | Use |\n|---|---|\n| default line-height (26pt at 17pt body) | within a thought-group |\n| 8pt margin-block | between thought-groups |\n| 16pt margin-block | between sub-paragraphs |\n\nA block that needs more than 75 words MUST be split into two `standard-text` blocks separated by a 24pt inter-block gap; each block carries its own bolded lead-clause.\n\n## G-9. Density budget per beat (V3.1+)\n\nEvery beat balances **anchor blocks** against **content blocks**:\n\n- **Anchor blocks** — stat-callout, pull-quote, key-takeaway, numbered-principle, table-with-takeaway-row.\n- **Content blocks** — standard-text, faq, code, table-without-takeaway.\n\nRules:\n\n1. Anchor-to-content ratio per beat MUST sit between **1:2** and **1:4**.\n2. No more than **2 consecutive anchors of the same type**. The third anchor MUST switch type or be re-cast as content.\n3. No more than **4 consecutive content blocks**. The fifth MUST be an anchor OR a mid-beat asterism rest (G-10).\n\n## G-10. Mid-beat asterism rest (V3.1+)\n\nBeats containing **≥ 5 blocks** MUST insert a centered asterism (`⁂`, U+2042) after the 4th block, and again after every additional 4 blocks within the same beat.\n\n- The asterism is a literal text glyph at body size and body weight. No rule, no box, no tint, no transform.\n- Vertical band: **32pt above, 32pt below** the glyph.\n- Asterisms do NOT count as blocks for density-budget purposes (G-9).\n- Beats with **≤ 4 blocks** MUST NOT use an asterism — inter-beat dividers do that work.\n- Why a glyph and not deep whitespace alone: whitespace by itself is ambiguous to ADHD readers and can read as \"the page didn't finish loading\" (Wichary on dinkus typography). A glyph signals intent.\n\n## G-11. Table takeaway-row requirement (V3.1+)\n\nAny `table` block with **≥ 4 data rows** MUST end with a bolded **Takeaway** row stating the comparison's verdict in one clause.\n\n- The takeaway row is what promotes a `table` from content block to anchor block (G-9).\n- Tables with < 4 data rows MAY omit the takeaway row if the block's title or surrounding text already states the verdict.\n- Visually: weight 600, no top border on the row, bottom border present.\n\n## Length budgets\n\n| Variant | Total blocks | Total scroll | Block height (typ.) | Hero card height |\n|---|---|---|---|---|\n| Mini | 5–8 | 3,000–5,000pt | 200–300pt | 600pt |\n| Standard | 10–14 | 5,000–8,000pt | 200–350pt | 700pt |\n| XL | 18–25 | 9,000–15,000pt | 200–400pt | 700pt |\n| (split above) | 25+ | — | — | — |\n\n## Loft / elevation budget\n\nHard cap: **1–3 elevated elements per Supercard.** The hero card is always one. Reserve the other 1–2 for the most important elevated callout and at most one mid-card breath. Everything else is flat.\n\n## Pre-publication screenshot test\n\nRun on every section, including the header. Five questions per section. Any \"no\" fails the section.\n\n1. Does the screenshot convey **one complete idea** alone?\n2. Can a stranger trace it back via the **corner glyph**?\n3. Does the first sentence stand **without prior context**?\n4. Is there **exactly one emphasized phrase** visible?\n5. Does the chosen **block variant earn its scroll**?\n\n## Anti-patterns (forbidden)\n\n| Anti-pattern | Why |\n|---|---|\n| Every block in a card shell | Chrome becomes noise |\n| Heavy drop shadows ≥15% opacity | Reads web-app, not editorial |\n| Color used for emphasis | Violates strict grayscale |\n| Charts where every bar is solid black | No signaling |\n| Pull quotes that paraphrase body | Must be verbatim lift |\n| Definition for context-obvious term | Filler — cut |\n| Padding sections that don't synthesize | Fail redundancy filter |\n| Forcing a chart when prose would do | False precision |\n| Comparison block for non-parallel items | Category error |\n| Process block for non-sequential steps | Implies false causality |\n| Section divider between every section | Should mark beats only |\n| Above 25 blocks in one Supercard | Split into multi-part |\n| Stat-callout without a verbal anchor (V3.1+) | A bare number can't be parsed under cognitive load — frame it in one sentence |\n| Three consecutive `standard-text` blocks in one beat (V3.1+) | Wall-of-text collapse — interrupt with an anchor or asterism |\n| Table of ≥ 4 rows without a takeaway row (V3.1+) | Readers extract no thesis from raw rows under scan — close with a bolded verdict |\n| Italics used for emphasis (V3.1+) | Italics are worst-performing for dyslexic/ADHD readers — emphasis is bold-only |\n| All-caps body runs longer than 4 words (V3.1+) | Disables word-shape recognition — restrict to micro-folio and ≤ 4-word kickers |\n| Justified text (V3.1+) | Uneven word-spacing rivers disrupt tracking — body MUST be left-aligned, ragged-right |\n| Two or more bolded runs in one block (V3.1+) | Destroys the single-emphasis signal — one bold per block, renderer errors |\n| Deep whitespace alone as a section break (V3.1+) | Reads as \"page didn't finish loading\" — mid-beat rests use the asterism, not raw whitespace |\n| Stacking ≥ 3 anchor blocks of the same type (V3.1+) | Checkerboard fatigue — the third anchor MUST switch type |\n| `standard-text` block exceeding 75 words (V3.1+) | Crosses chunk-collapse threshold — split into two blocks with their own lead-clauses |\n| Cover header elements outside R-13 (running brand-mark folio, mode badge, date eyebrow, context-chip strip, second eyebrow restating the micro-folio's beat name) (V3.1+) | Random labels load the cover with chrome instead of meaning — the cover permits exactly four elements (micro-folio, title, dek, hero), see RENDERING § R-13 |\n| Section eyebrow on a beat's first block when the top-edge micro-folio is present (V3.1+) | Pure duplication — the folio already says `BEAT 3 · MECHANISM · 4 / 7`; a separate `MECHANISM` eyebrow 12pt below adds no information (R-10) |\n| A label longer than 4 words anywhere on the card (V3.1+) | A label that needs five words is a sentence pretending to be a label — promote to the dek/lead-clause or cut (R-14) |\n| A label whose only function is to \"balance\" another label (V3.1+) | Symmetry isn't a reason; load-bearing is — if the second label answers no question the reader is asking, cut it (R-14) |\n| A context-chip strip (`A · B · C` of three or more orphan chips) used where one dek/lead-clause sentence would integrate the same facts (V3.1+) | Three orphan chips force three parses; prose forces one — labels integrate facts, they don't list them (R-14) |\n| A label nested inside an already-labeled container (folio under a beat-name eyebrow under a section header) (V3.1+) | Three labels, one job — the typographic hierarchy alone should resolve it (R-14) |\n| Inconsistent labeling — a label kind that appears on some sections and not others without a structural reason (V3.1+) | Inconsistency reads as bug, not intent; either every comparable section earns the label or none do (R-14) |\n",
  "see_also_urls": [
    "https://berafoot.com/spec/blocks.json",
    "https://berafoot.com/spec/lengths.json",
    "https://berafoot.com/spec/principles.json",
    "https://berafoot.com/spec/example.json"
  ],
  "mirror_urls": [
    {
      "name": "berafoot",
      "url": "https://berafoot.com/spec/grammar.json"
    },
    {
      "name": "vercel",
      "url": "https://supercard-seven.vercel.app/spec/grammar.json"
    }
  ]
}