CEFR Coursebook Layout

Overview

Generate fixed-A4 (210×297 mm) English coursebook units with CEFR-graded vocabulary,
Chinese micro-glosses (ruby), and academic-word (AVL) Ac tags. Two unit types are
supported:

• Reading unit — passage + sidebar vocab cards + multiple-choice questions + answer key.
• Cloze unit (完形填空) — gapped passage + word bank (A–O) sidebar + answer key +
  定位解析 (per-blank explanations) + vocabulary/phrase review.

The layout is battle-tested across multiple units; the stylesheet and templates already
encode every layout fix from prior iterations (see references/pitfalls.md).

When to use

• User pastes an English passage and asks for an annotated worksheet / 精读 / 完形填空 unit.
• User wants print-ready A4 PDF handouts with CEFR badges and Chinese meanings.
• User says "make a layout like the previous unit" / "生成类似的排版".
• Paired tightly with the cefr-vocab-verify skill (verify badge levels before render).

Design system (load-bearing constants)

Read references/layout.css for the full stylesheet; the essentials:

• Pages: .page{width:210mm;height:297mm;padding:18mm 18mm 18mm 20mm;overflow:hidden}
  inside .book{width:210mm}. @page{size:A4;margin:0} for print.
• Grid: .content{grid-template-columns:6.2fr 3.8fr;gap:8mm} (reading : sidebar).
• Ruby gloss: <ruby><span class="common">word</span><rt>中文</rt></ruby> (meaning BELOW word).
• Highlights: .common (theme), .b1 (gold), .ac (purple, AVL), .phrase, .awl.
• Level badges: <span class="level a2|b1|b2|c1|ac">…</span>. Colors:
  A2 green, B1 gold, B2 blue, C1 rose, Ac purple.
• Overflow safety: .content/.exam use flex:0 1 auto; footer uses margin-top:auto;
  .exam{overflow:hidden}. Target = 0 px page + inner overflow on every page.
• Explanation items (定位解析): two-column grid — label in a 13 mm nowrap column, text
  in the second column. Never use absolute positioning for the label (it collides).

Workflow

1. Scaffold. Copy the matching template from assets/ into the working outputs/ dir:
   - reading unit → assets/reading-unit-template.html
   - cloze unit → assets/cloze-unit-template.html
   Replace {{PLACEHOLDERS}}. Inline references/layout.css into the <style> block (or
   @import it and keep layout.css beside the HTML). Keep the overflow-probe <script>
   at the end of <body>.

2. Annotate. Tag each target word with a highlight class + level badge. For academic
   (AVL) lemmas add .ac + <span class="level ac">Ac</span>. See badge rules below.

3. Verify badges. Run the cefr-vocab-verify skill on the unit HTML. Fix any ≥2-level
   single-word deviations (hard red flags come from CEFR-J + Octanove only; cefrpy is soft).
   Add Ac only to AVL-confirmed lemmas.

4. Measure overflow. Run scripts/measure_overflow.py UNIT.html. All pages must report
   pageOverflow=0 and innerOverflow=0. If not, trim content or move it to a new page
   (see pitfalls §1–§3). Re-run until clean.

5. Render PDF. Print to A4 via headless Chrome
   (--headless --print-to-pdf=UNIT.pdf --no-pdf-header-footer) or the browser print dialog.
   Optionally also export a UNIT_preview.png for the user.

6. Deliver. Present the HTML (live preview) and/or the PDF with present_files.

CEFR / Ac badge rules

• One badge per word; if a word is both leveled and academic, render both pills
  (e.g. crucial → B2 + Ac).
• Ac (purple) only on AVL-confirmed lemmas (check avl.json in cefr-vocab-verify).
  Do NOT tag word families just because a base form looks academic
  (economist, financial, retirement, security are absent from AVL core → no Ac).
• Chinese meaning goes below the word via <ruby><rt>, never inline after it.
• Keep the legend (.legend) consistent with the badges actually used on the page.

Common pitfalls (summary)

Full detail + root causes in references/pitfalls.md. Quick list:

• Cloze word bank overflow → put the FULL A–O list in the page-1 sidebar (single column).
• Page-2 overlap → flex:0 1 auto + footer margin-top:auto + .exam{overflow:hidden};
  split heavy content across pages 2–3.
• 定位解析 label collides with text → two-column grid, never absolute positioning.
• Lead-in box → a <div class="lead">, never nested inside a <p>; place in the sidebar.
• Always measure 0 px overflow before PDF export.

Resources

• references/layout.css — the canonical, reusable A4 stylesheet (single source of truth).
• references/pitfalls.md — every layout bug found during iteration + its fix.
• assets/reading-unit-template.html — skeleton for a reading unit.
• assets/cloze-unit-template.html — skeleton for a cloze / 完形填空 unit.
• scripts/measure_overflow.py — headless-Chrome per-page overflow checker (0 px target).