Visual identity: per-language typography + accent geometry; new deck-design subagent

The decks rendered fine geometrically but had the AI-generated look —
default Calibri on every run, plain blank backgrounds, no accent
shapes. python-pptx supports both: setting a real font family on
every run, and adding decorative rectangles to every slide. We were
doing neither.

autopapertoppt/exporters/pptx.py
  * `_FONT_FAMILIES` table keyed by language → (latin, east_asian).
    Inter is the Latin face across all 14 supported languages; the
    east-asian slot fills in Microsoft JhengHei UI (zh-tw) / YaHei UI
    (zh-cn) / Yu Gothic UI (ja) / Malgun Gothic (ko) / Nirmala UI (hi).
  * `_apply_typography(prs, language)` post-build pass walks every
    slide -> shape -> paragraph -> run and writes both `<a:latin>`
    and `<a:ea typeface=...>` XML. PowerPoint consults a SEPARATE
    East-Asian font slot for CJK code points; leaving it unset would
    have made CJK characters render in the host's default
    (PMingLiU / SimSun / etc.) which doesn't match Inter.
  * `_decorate_with_accents(prs)` post-build pass:
      - Cover slide: a 0.4" × full-height navy band on the left
        (`accent_left`).
      - Every other slide: a 0.08" × full-width navy bar at y=0
        (`accent_top`).
    Both shapes are sent to the back of z-order via spTree.insert(2)
    so text content sits above them. Both carry semantic shape names
    so pptx_edit.update_slide(...) and pptx_edit.delete_slide(...)
    can target them.

scripts/_overflow_check.py
  Decorative rectangles have empty text_frames; the existing
  _estimate_wrapped_height_emu inflates an empty frame to ~1
  line-height (~0.2") which false-flagged the 0.08" accent bar.
  Skip when text_frame.text is empty.

.claude/agents/deck-design.md
  New subagent owning visual identity — typography rules per language,
  brand palette discipline, accent geometry expectations, master-slide
  contract, and the anti-patterns that make a deck obviously
  machine-generated (default Calibri, plain blank backgrounds,
  centred-only covers, all-text body slides).

CLAUDE.md + .claude/agents/slide-deck-rules.md
  CLAUDE.md table gains a 10th row pointing at deck-design.
  slide-deck-rules.md adds a "scope split" note clarifying that the
  sibling deck-design subagent owns visual identity while this one
  stays focused on geometry / overflow / content caps.

tests/test_exporters.py + tests/test_pptx_edit.py
  Three tests assumed `slide.shapes[0]` is the title. With accent
  rectangles now sitting at index 0, they crash on empty text_frames.
  Replaced with a `_slide_text(slide, name)` helper that finds the
  shape by its semantic name — which the project already pins as a
  contract elsewhere.

Re-rendered the 4 zh-tw speculative-decoding decks:
  xia2024unlocking-zh-tw      20 slides, 156 shapes, overflow PASS
  spector2023accelerating     21 slides, 164 shapes, overflow PASS
  xu2024edgellm               22 slides, 172 shapes, overflow PASS
  svirschevski2024specexec    21 slides, 164 shapes, overflow PASS

Cover title verified to carry latin='Inter' + east-asian
'Microsoft JhengHei UI'. Content slide 3 carries `accent_top` shape.

510/510 pytest pass; ruff clean.

Author: JE-Chen

.claude/agents/deck-design.md

@@ -0,0 +1,142 @@
+---
+name: deck-design
+description: Visual-design rules for the pptx exporter — typography (per-language font stack), brand palette, accent geometry, master-slide expectations, and the anti-patterns that make a deck obviously machine-generated (default Calibri, blank backgrounds, centered-only covers, text-only walls). Use BEFORE any change to `autopapertoppt/exporters/pptx.py`'s visual surface, when authoring a new template file under `assets/template/`, or when investigating a "this deck looks AI-made" complaint. Read-only audit + design reference.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the deck-design auditor for AutoPaperToPPT. The sibling
+`slide-deck-rules` subagent owns *geometry / overflow* (15-pt headers,
+7.05" footer guard, `_BULLETS_PER_CELL_MAX`, etc.); this agent owns
+*visual identity* — typography, colour, accent shapes, master-slide
+structure, anti-tells.
+
+When a generated deck looks like every other LLM output (default Calibri,
+white background, plain centred title, text-only body slides, no visual
+breathing room), the geometry is probably fine but the visual identity
+is missing. That's what this agent guards.
+
+## Visual identity contract
+
+### Typography (per-language font stack)
+
+Default Calibri / Arial is the single biggest "AI-generated" tell.
+The exporter MUST set a typeface on every run.
+
+| Language | Primary font (Latin) | East-Asian (`<a:ea>`) | Fallback rationale |
+|---|---|---|---|
+| en, es, fr, de, pt, it, vi, id | Inter (or Calibri Light) | — | Inter ships free + on most modern Windows / Office installs; degrades gracefully |
+| zh-tw | Inter (Latin) | Microsoft JhengHei UI | Win TW default; cleaner than PMingLiU |
+| zh-cn | Inter (Latin) | Microsoft YaHei UI | Win CN default; cleaner than SimSun |
+| ja | Inter (Latin) | Yu Gothic UI | Win JP default; modern look |
+| ko | Inter (Latin) | Malgun Gothic | Win KR default |
+| ru | Inter (Latin) | — | Inter has full Cyrillic |
+| hi | Inter (Latin) | Nirmala UI | Win Devanagari default |
+
+Implementation pattern (`autopapertoppt/exporters/pptx.py`):
+- Module-level `_FONT_FAMILIES: dict[str, tuple[str, str | None]]` keyed
+  by language → `(latin_family, east_asian_family)`.
+- `_apply_typography(prs, language)` post-build pass walks every slide,
+  every shape with a text frame, every run; sets `<a:latin typeface=...>`
+  AND `<a:ea typeface=...>` on the run's XML. Both slots matter —
+  setting only `run.font.name` (the Latin slot) leaves CJK chars
+  rendered in PowerPoint's default East Asian font.
+
+### Colour palette
+
+Already pinned in `pptx.py`:
+
+| Constant | RGB | Use |
+|---|---|---|
+| `_BRAND_DARK` | `#1F3A66` (deep navy) | Primary text + accent bar |
+| `_BRAND_ACCENT` | `#C0392B` (warm red) | KPI highlights, hover-style emphasis |
+| `_BRAND_GREY` | `#555555` | Metadata, secondary text |
+| `_BRAND_LIGHT` | `#AAAAAA` | Rule lines, dividers |
+
+Do NOT introduce new brand colours casually — every additional colour
+fights for attention. Reuse the four above unless the user explicitly
+adds one.
+
+### Accent geometry (the "this is a designed deck" tell)
+
+Every content slide gets a thin top accent bar:
+- Position: `left=0, top=0, width=_SLIDE_WIDTH (13.333"), height=Inches(0.08)`
+- Fill: `_BRAND_DARK` solid
+- Name: `accent_top` (semantic name so `pptx_edit` can target it)
+
+The cover slide gets a left vertical band:
+- Position: `left=0, top=0, width=Inches(0.4), height=_SLIDE_HEIGHT (7.5")`
+- Fill: `_BRAND_DARK` solid
+- Name: `accent_left`
+- Cover textboxes shift right by `Inches(0.4)` worth of margin to clear it.
+
+Section-divider slides may use a larger top band (`height=Inches(0.6)`)
+with the section title overlaid in light text — but this is optional
+and only for runs > 4 papers.
+
+### Master-slide expectations
+
+A real template (`assets/template/thesis-style.pptx`, when added) would
+ship master + 4-6 layouts. As long as the exporter still uses
+`prs.slide_layouts[6]` (blank), the visual identity comes from the
+programmatic accent bar + typography pass. Either path is acceptable
+provided every slide ends up with:
+1. A consistent font family per language (no Calibri default).
+2. An accent geometry (top bar / cover band / section band) at fixed
+   positions across slides.
+3. Page numbers in `_BRAND_GREY` (already set).
+4. The semantic shape names listed in `slide-deck-rules.md`.
+
+## Anti-patterns (instant "AI-generated" tells)
+
+- Plain `prs.slide_layouts[6]` (blank) with no programmatic accent. Every
+  slide looks the same vacant white.
+- `run.font.name` left unset — PowerPoint falls back to Calibri 11pt.
+  This is the single biggest tell.
+- Centred-only cover slide — typography style that screams "default
+  PowerPoint template". A left-band + left-aligned title reads as
+  designed.
+- New colours added per-slide. Brand discipline matters — four colours
+  total, no exceptions.
+- Title slide includes the search query verbatim ("Paper Survey:
+  speculative decoding LLM inference") as the title. That's a
+  metadata string, not a deck title — wrap it in `_cover_title(...)`
+  which lowercases + applies title-case + adds a period (or a
+  language-appropriate suffix).
+- Body slides that are pure bullets. Mix at least 2 layouts:
+  bullet list + KPI block + table + figure / diagram. The `figures=`
+  field in `PaperSummary` is mandatory exactly because pure-text decks
+  look generated. See [paper-summary-author](paper-summary-author.md).
+- Identical line-height across heading + body. Headings should have
+  tighter line-height than body.
+
+## How to audit a deck
+
+1. Open `<deck>.pptx` in PowerPoint (or `python-pptx`'s reader).
+2. Check the FIRST run's `run.font.name` on the cover title. If `None`
+   or `Calibri`, the typography pass didn't run.
+3. Check slide 2 (a content slide) for a shape named `accent_top` at
+   `y=0`. If missing, the accent pass didn't run.
+4. Check the cover slide for `accent_left`. If missing, the left band
+   is gone.
+5. Scan slides 3..N for visual variety: bullet density vs KPI vs table
+   vs figure. If every slide is text-only, the `figures=` step was
+   skipped.
+6. If a font family is set but PowerPoint still shows Calibri on
+   CJK glyphs, the `<a:ea>` XML override isn't being written — only
+   the Latin font slot was.
+
+## Reporting format
+
+```
+deck-design — <deck path>
+[1] Typography (latin + east-asian) .......... PASS / FAIL — <note>
+[2] Top accent bar on content slides ......... PASS / FAIL — <count missing>
+[3] Cover-slide left band .................... PASS / FAIL
+[4] Brand palette discipline (≤ 4 colours) ... PASS / FAIL
+[5] Visual variety (bullets / KPI / table /
+    figure mix) .............................. PASS / FAIL — <ratio>
+[6] No "Paper Survey: <raw-query>" leak
+    on cover ................................. PASS / FAIL
+
+Verdict: PASS / PASS with notes / FAIL
+```

.claude/agents/slide-deck-rules.md

@@ -6,6 +6,15 @@ tools: Read, Grep, Glob
 
 You are the slide-deck rules reference for AutoPaperToPPT. When invoked, return the relevant rule(s) for the change being made and flag any direct violations you can spot in the diff. The actual overflow inspection lives in the sibling `slide-overflow-check` subagent — don't re-implement it here.
 
+**Scope split** — this agent owns *geometry* and *content safety*
+(slide dimensions, footer guard, truncation caps, per-slide content
+caps, semantic shape names, i18n keys, rendering-tier dispatch). The
+sibling `deck-design` subagent owns *visual identity* (typography per
+language, brand palette, accent geometry, "looks AI-generated"
+anti-patterns). Both apply to any change to
+`autopapertoppt/exporters/pptx.py` — consult the appropriate one for
+the concern at hand.
+
 ## Slide Deck Rules
 
 The pptx exporter is the most visually-sensitive surface in the project. Several non-obvious rules keep its output safe for a thesis-defence audience.

CLAUDE.md

@@ -4,8 +4,8 @@
 > recent Aider, and several other tools auto-load `AGENTS.md`; keep them in
 > sync when you change rules. Detailed rules now live in `.claude/agents/`
 > as subagents (`code-quality-reviewer`, `compliance-auditor`,
-> `slide-deck-rules`, `env-vars`, `language-vocabulary-check`, plus the
-> task-running agents `dod-verify`, `paper-summary-author`,
+> `slide-deck-rules`, `deck-design`, `env-vars`, `language-vocabulary-check`,
+> plus the task-running agents `dod-verify`, `paper-summary-author`,
 > `post-author-audit`, `slide-overflow-check`).
 
 ## Project Overview
@@ -114,6 +114,7 @@ window open during an IEEE / Scholar / paywalled-PDF step, the path is broken
 | Design patterns, SOLID, performance, async, unit tests, full linter rule set | `code-quality-reviewer` |
 | Core-vs-source-plugin boundary, network safety, browser-automation hard rule, path safety, suppression conventions, bandit skip config | `compliance-auditor` |
 | pptx exporter geometry, rendering tiers, truncation caps, semantic shape names, i18n, LLM-as-agent vs Python pipeline | `slide-deck-rules` |
+| pptx visual identity (typography per language, brand palette, accent geometry, master-slide expectations, "looks AI-generated" anti-patterns) | `deck-design` |
 | Env vars + Python / `.venv` toolchain reference | `env-vars` |
 | Definition-of-Done gate runner | `dod-verify` |
 | LLM-as-agent thesis-style authoring (PDF → rich PaperSummary) | `paper-summary-author` |

autopapertoppt/exporters/pptx.py

@@ -35,7 +35,9 @@
 
 from pptx import Presentation
 from pptx.dml.color import RGBColor
+from pptx.enum.shapes import MSO_SHAPE
 from pptx.enum.text import MSO_AUTO_SIZE, PP_ALIGN
+from pptx.oxml.ns import qn
 from pptx.util import Emu, Inches, Pt
 
 from autopapertoppt.core.constants import EXPORT_PPTX
@@ -107,6 +109,36 @@
 _BRAND_ACCENT = RGBColor(0xC0, 0x39, 0x2B)
 _BRAND_GREY = RGBColor(0x55, 0x55, 0x55)
 _BRAND_LIGHT = RGBColor(0xAA, 0xAA, 0xAA)
+
+# Per-language typography. (latin_family, east_asian_family). The Latin
+# family also covers Cyrillic / Greek / Devanagari via Inter; the
+# east-asian slot is what PowerPoint consults for CJK code points, so
+# leaving it `None` would let PowerPoint pick a default that doesn't
+# match the Latin choice. See ``deck-design`` agent doc for the
+# full rationale. Inter degrades gracefully to Calibri on hosts without
+# Inter installed.
+_FONT_FAMILIES: dict[str, tuple[str, str | None]] = {
+    "en":     ("Inter", None),
+    "es":     ("Inter", None),
+    "fr":     ("Inter", None),
+    "de":     ("Inter", None),
+    "pt":     ("Inter", None),
+    "it":     ("Inter", None),
+    "vi":     ("Inter", None),
+    "id":     ("Inter", None),
+    "ru":     ("Inter", None),
+    "hi":     ("Inter", "Nirmala UI"),
+    "zh-tw":  ("Inter", "Microsoft JhengHei UI"),
+    "zh-cn":  ("Inter", "Microsoft YaHei UI"),
+    "ja":     ("Inter", "Yu Gothic UI"),
+    "ko":     ("Inter", "Malgun Gothic"),
+}
+_DEFAULT_FONT_FAMILY: tuple[str, str | None] = ("Inter", None)
+
+# Accent geometry (set on every content slide by the typography /
+# accent pass so a stock blank layout still reads as a designed deck).
+_ACCENT_TOP_HEIGHT = Inches(0.08)
+_ACCENT_LEFT_WIDTH = Inches(0.4)
 _BRAND_RULE = RGBColor(0xCC, 0xCC, 0xCC)
 _RQ_BOX_FILL = RGBColor(0xF3, 0xF6, 0xFA)
 _RQ_BOX_BORDER = RGBColor(0x1F, 0x3A, 0x66)
@@ -266,6 +298,11 @@ def _build(
             )
         # Page numbers are stamped AFTER trim so they reflect the final total.
         _stamp_page_numbers(prs, ctx.language)
+        # Visual identity passes — applied last so they affect every shape
+        # placed by every builder (including page numbers). See the
+        # ``deck-design`` subagent doc for rationale.
+        _apply_typography(prs, ctx.language)
+        _decorate_with_accents(prs)
         return prs
 
 
@@ -1606,3 +1643,105 @@ def _stamp_page_numbers(prs: Presentation, language: str) -> None:
             font_pt=_FOOTER_PT, colour=_BRAND_LIGHT,
             align=PP_ALIGN.RIGHT,
         )
+
+
+# ---------------------------------------------------------------------------
+# Visual identity passes — typography + accent geometry
+# ---------------------------------------------------------------------------
+
+
+def _apply_typography(prs: Presentation, language: str) -> None:
+    """Set Latin + East-Asian font on every run across every slide.
+
+    Default Calibri is the biggest "AI-generated deck" tell. We walk
+    every shape post-build and write both ``<a:latin>`` and ``<a:ea>``
+    typeface XML on every run — leaving the east-asian slot at the
+    PowerPoint default would make CJK chars render in a font that
+    doesn't match the Latin choice.
+    """
+    latin, east_asian = _FONT_FAMILIES.get(language, _DEFAULT_FONT_FAMILY)
+    for slide in prs.slides:
+        for shape in slide.shapes:
+            if not shape.has_text_frame:
+                continue
+            for paragraph in shape.text_frame.paragraphs:
+                for run in paragraph.runs:
+                    run.font.name = latin
+                    if east_asian:
+                        _set_east_asian_typeface(run, east_asian)
+
+
+def _set_east_asian_typeface(run, family: str) -> None:
+    """Write the ``<a:ea typeface=...>`` element on a run's rPr.
+
+    python-pptx's ``run.font.name`` setter only writes the Latin
+    typeface (``<a:latin>``). PowerPoint consults a SEPARATE
+    east-asian slot when laying out CJK code points; this helper
+    fills it.
+    """
+    r_pr = run._r.get_or_add_rPr()
+    existing = r_pr.find(qn("a:ea"))
+    if existing is not None:
+        r_pr.remove(existing)
+    ea = r_pr.makeelement(qn("a:ea"), {"typeface": family}, nsmap=None)
+    r_pr.append(ea)
+
+
+def _decorate_with_accents(prs: Presentation) -> None:
+    """Place the accent shapes (cover left band, top bar on content slides).
+
+    Idempotent: if the shapes already exist from a previous build pass
+    (rare but possible in tests that re-run ``_build``), they're left in
+    place — a name match suppresses re-add. The shapes are sent to the
+    back of the slide's z-order so they sit BEHIND any text on the slide.
+    """
+    for index, slide in enumerate(prs.slides):
+        if index == 0:
+            _add_cover_left_band(slide)
+        else:
+            _add_top_accent_bar(slide)
+
+
+def _add_cover_left_band(slide) -> None:
+    if _has_named_shape(slide, "accent_left"):
+        return
+    shape = slide.shapes.add_shape(
+        MSO_SHAPE.RECTANGLE,
+        Emu(0), Emu(0),
+        _ACCENT_LEFT_WIDTH, _SLIDE_HEIGHT,
+    )
+    shape.name = "accent_left"
+    shape.line.fill.background()
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = _BRAND_DARK
+    _send_shape_to_back(shape, slide)
+
+
+def _add_top_accent_bar(slide) -> None:
+    if _has_named_shape(slide, "accent_top"):
+        return
+    shape = slide.shapes.add_shape(
+        MSO_SHAPE.RECTANGLE,
+        Emu(0), Emu(0),
+        _SLIDE_WIDTH, _ACCENT_TOP_HEIGHT,
+    )
+    shape.name = "accent_top"
+    shape.line.fill.background()
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = _BRAND_DARK
+    _send_shape_to_back(shape, slide)
+
+
+def _has_named_shape(slide, name: str) -> bool:
+    return any(shape.name == name for shape in slide.shapes)
+
+
+def _send_shape_to_back(shape, slide) -> None:
+    """Move ``shape`` to be the first child of ``spTree`` (= back of z-order)."""
+    sp_tree = slide.shapes._spTree
+    sp = shape._element
+    sp_tree.remove(sp)
+    # spTree's first two children are nvGrpSpPr + grpSpPr (group metadata);
+    # everything after that is a shape in z-order. Insert at index 2 so the
+    # band lands BEHIND every text shape but the metadata stays intact.
+    sp_tree.insert(2, sp)

scripts/_overflow_check.py

@@ -72,6 +72,12 @@ def _inspect(pptx_path: Path) -> list[tuple[int, str, str, int, int]]:
         for shape in slide.shapes:
             if not shape.has_text_frame:
                 continue
+            # Decorative shapes (`accent_top`, `accent_left`, etc.) have
+            # an empty text_frame; estimating wrapped text on an empty
+            # frame inflates to ~1 line-height which would false-flag
+            # the 0.08" top accent bar. Skip when no actual text.
+            if not (shape.text_frame.text or "").strip():
+                continue
             name = shape.name or "?"
             top = shape.top or 0
             height = shape.height or 0