@chengzhao-dev/dsh-quarto-book 0.4.3 → 0.6.0

package/skills/designing-theme/scripts/checking-layout.py

@@ -63,14 +63,14 @@ def active_palette_name(quarto_text=""):
 SHARED_CHECKS = [
     ("body line-height 1.75", "line-height: 1.75"),
     ("content width", "--content-width: 840px"),
-    ("code font 16px", "--code-font-size: 1rem"),
-    ("code line-height 1.75", "--code-line-height: 1.75"),
+    ("code font 15px", "--code-font-size: 0.9375rem"),
+    ("code line-height 1.7", "--code-line-height: 1.7"),
     ("code title padding token", "--code-title-padding"),
     ("ui font stack", '--ui-font: "LXGW Bright Medium"'),
     ("cjk font fallback", '"LXGW Bright Medium"'),
     ("code font stack", '--mono-font: "LXGW Bright Code"'),
     ("bright code family", '"LXGW Bright Code"'),
-    ("code followup gap", "--code-followup-gap: 1rem"),
+    ("code followup gap", "--code-followup-gap: 0.9rem"),
     ("list code followup spacing", "margin-top: var(--code-followup-gap)"),
     ("list code with filename selector", "li > :is(.code-copy-outer-scaffold, .code-with-filename"),
     ("readable body font", "font-size: 1rem"),
@@ -79,7 +79,8 @@ SHARED_CHECKS = [
     ("answer disclosure container", "details.answer-disclosure"),
     ("list marker token color", "li::marker"),
     ("answer disclosure summary", "details.answer-disclosure > summary"),
-    ("feature-grid max two columns", "calc((100% - 1.25rem) / 2)"),
+    ("feature-grid max two columns", "repeat(2, minmax(0, 1fr))"),
+    ("feature-grid single card full row", ":has(> .landing-card:only-child)"),
 ]
 
 # 语义令牌名必须存在（色值由活跃 palette 提供）
@@ -93,42 +94,117 @@ TOKEN_NAME_CHECKS = [
     ("callout important (deep-dive semantics)", "--callout-important-border"),
 ]
 
-# palettes/github 色值期望。换 pack 时改对应表。实验包色值不写进 github 表。
+# palettes/flexoki 色值期望（编译默认）。换 pack 时改对应表。
 PALETTE_VALUE_CHECKS = {
-    "github": [
-        ("light body token #1F2328", "--body-color: #1F2328"),
-        ("light GitHub link #0969DA", "#0969DA"),
-        ("light navbar page-bg token", "--navbar-bg: #FFFFFF"),
-        ("dark navbar page-bg token", "--navbar-bg: #22272E"),
-        ("light code background", "--code-bg: #F6F8FA"),
-        ("dark code background", "--code-bg: #2D333B"),
-        ("dark page #22272E", "#22272E"),
-        ("dark body #CDD9E5", "#CDD9E5"),
-        ("dark secondary #B1BAC4", "#B1BAC4"),
-        ("dark link #539BF5", "#539BF5"),
-        ("callout note border light", "--callout-note-border: #0969DA"),
-        ("light highlight comment #57606a", "#57606a"),
-        ("light highlight keyword #cf222e", "#cf222e"),
-        ("dark highlight comment #9aa1ab", "#9aa1ab"),
-        ("dark highlight keyword #ff7b72", "#ff7b72"),
+    "flexoki": [
+        ("light body token #100F0F", "--body-color: #100F0F"),
+        ("light emphasis #100F0F", "--emphasis-color: #100F0F"),
+        ("light line numbers #575653", "--line-num-color: #575653"),
+        ("light Flexoki link ink #100F0F", "--link-color: #100F0F"),
+        ("light navbar page-bg token", "--navbar-bg: #FFFCF0"),
+        ("dark navbar page-bg token", "--navbar-bg: #100F0F"),
+        ("light code background", "--code-bg: #F2F0E5"),
+        ("dark code background", "--code-bg: #1C1B1A"),
+        ("dark page #100F0F", "#100F0F"),
+        ("dark body #CECDC3", "#CECDC3"),
+        ("dark secondary #9F9D96", "#9F9D96"),
+        ("dark link ink #CECDC3", "--link-color: #CECDC3"),
+        ("callout note border light", "--callout-note-border: #6F6E69"),
+        ("callout warning border light", "--callout-warning-border: #BC5215"),
+        ("light highlight comment #575653", "#575653"),
+        ("light highlight keyword #66800b", "#66800b"),
+        ("dark highlight comment #878580", "#878580"),
+        ("dark highlight keyword #879a39", "#879a39"),
     ],
 }
 
+# Solarized 是运行时覆盖层：令牌必须挂在 html[data-palette="solarized"] 下。
+SOLARIZED_TOKEN_CHECKS = [
+    ("solarized token selector", 'html[data-palette="solarized"] body'),
+    ("solarized light page #FDF6E3", "--page-bg: #FDF6E3"),
+    ("solarized light body #526C74", "--body-color: #526C74"),
+    ("solarized light link rebase #586E75", "--link-color: #586E75"),
+    ("solarized light code text #526C74", "--code-fg: #526C74"),
+    ("solarized light code #EEE8D5", "--code-bg: #EEE8D5"),
+    ("solarized dark page #002B36", "--page-bg: #002B36"),
+    ("solarized dark body #839496", "--body-color: #839496"),
+    ("solarized dark link rebase #93A1A1", "--link-color: #93A1A1"),
+    ("solarized link hover action", "--link-hover-color: var(--action-color)"),
+    ("solarized dark code #073642", "--code-bg: #073642"),
+]
+
+SOLARIZED_SYNTAX_CHECKS = [
+    ("solarized syntax selector", 'html[data-palette="solarized"] code span.kw'),
+    ("solarized keyword #859900", "#859900"),
+    ("solarized light comment #556C73", "#556C73"),
+    ("solarized light syntax blue #1B6EA3", "#1B6EA3"),
+    ("solarized dark comment #93A1A1", "#93A1A1"),
+    ("solarized dark syntax blue #51A0D5", "#51A0D5"),
+]
+
+# 山光是运行时覆盖层，四时辰都挂在 html[data-palette="hill-light"][data-mode] 下。
+HILL_LIGHT_TOKEN_CHECKS = [
+    ("hill-light dawn selector", 'html[data-palette="hill-light"][data-mode="dawn"] body'),
+    ("hill-light noon selector", 'html[data-palette="hill-light"][data-mode="noon"] body'),
+    ("hill-light dusk selector", 'html[data-palette="hill-light"][data-mode="dusk"] body'),
+    ("hill-light night selector", 'html[data-palette="hill-light"][data-mode="night"] body'),
+    ("hill-light night native dark controls", "color-scheme: dark;"),
+    ("hill-light night print fallback", "@media print"),
+]
+
+HILL_LIGHT_SYNTAX_CHECKS = [
+    ("hill-light syntax base rule", '[data-mode="dawn"] code span:not([class])'),
+    ("hill-light dawn keyword", 'html[data-palette="hill-light"][data-mode="dawn"] code span.kw'),
+    ("hill-light noon keyword", 'html[data-palette="hill-light"][data-mode="noon"] code span.kw'),
+    ("hill-light dusk keyword", 'html[data-palette="hill-light"][data-mode="dusk"] code span.kw'),
+    ("hill-light night keyword", 'html[data-palette="hill-light"][data-mode="night"] code span.kw'),
+    ("hill-light night comment", 'html[data-palette="hill-light"][data-mode="night"] code span.co'),
+]
+
+
+def lu(hex_color: str) -> float:
+    """WCAG 相对亮度。"""
+    h = hex_color.lstrip("#")
+    r, g, b = (int(h[i:i + 2], 16) / 255 for i in (0, 2, 4))
+    lin = [c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in (r, g, b)]
+    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+
+
+def check_hill_light_modes(tokens_text: str) -> int:
+    """山光四时辰：前三个时辰浅纸、夜月暗纸；打印时夜月回落浅纸。"""
+    fails = 0
+    values = re.findall(r"--page-bg: (#[0-9A-Fa-f]{6})", tokens_text)
+    if len(values) < 5:
+        print(f"  MISS hill-light page-bg count (found {len(values)}, want >= 5)")
+        return 1
+    names = ("dawn", "noon", "dusk")
+    for name, v in zip(names, values[:3]):
+        ok = lu(v) > 0.55
+        print(f"  {'OK  ' if ok else 'MISS'} hill-light {name} paper is light  ({v} L={lu(v):.2f})")
+        fails += 0 if ok else 1
+    night_ok = lu(values[3]) < 0.15
+    print(f"  {'OK  ' if night_ok else 'MISS'} hill-light night is dark  ({values[3]} L={lu(values[3]):.2f})")
+    fails += 0 if night_ok else 1
+    print_ok = abs(lu(values[4]) - lu(values[0])) < 0.02
+    print(f"  {'OK  ' if print_ok else 'MISS'} hill-light night print falls back to dawn paper  ({values[4]})")
+    fails += 0 if print_ok else 1
+    return fails
+
+
 # 兼容旧名：测试与外部引用仍可能导入 CHECKS。
-CHECKS = SHARED_CHECKS + TOKEN_NAME_CHECKS + PALETTE_VALUE_CHECKS["github"]
+CHECKS = SHARED_CHECKS + TOKEN_NAME_CHECKS + PALETTE_VALUE_CHECKS["flexoki"]
 
 CALLOUT_CHECKS = [
     ("callout body font 16px", "font-size: 1rem;"),
-    ("callout title font 15px", "font-size: 0.9375rem;"),
-    ("callout padding 16px", "padding: 1rem;"),
-    ("callout header gap 8px", "margin: 0 0 0.5rem;"),
+    ("callout title font 13px", "font-size: 0.8125rem;"),
+    ("callout padding", "padding: 0.1rem 0 0.1rem 1.1rem;"),
+    ("callout header gap", "margin: 0 0 0.35rem;"),
 ]
 
 FORBIDDEN_FONT_REFERENCES = [
     ("Fixel reference", "Fixel"),
     ("LXGW WenKai Screen reference", "LXGW WenKai Screen"),
     ("Inter reference", "Inter"),
-    ("Noto Sans SC reference", "Noto Sans SC"),
     ("Noto Sans Mono CJK SC reference", "Noto Sans Mono CJK SC"),
     ("JetBrains Mono reference", "JetBrains Mono"),
     ("local font fallback", "local("),
@@ -317,6 +393,9 @@ def browser_layout(book_dir, verbose):
             f" (node={node or '无'}, NODE_PATH={playwright_root or '无'})"
         ), {}
 
+    # 测量目标是渲染产物：书目录里还可能有主题模板（theme/includes/*.html），
+    # 它们没有 #quarto-document-content，混进采样会误报。优先用 _book。
+    render_dir = book_dir / "_book" if (book_dir / "_book").is_dir() else book_dir
     shots_dir = ROOT / "temp" / "theme-regression"
     out_file = shots_dir / "measure.json"
     shots_dir.mkdir(parents=True, exist_ok=True)
@@ -325,7 +404,7 @@ def browser_layout(book_dir, verbose):
         node,
         str(MEASURE_SCRIPT),
         "--book-dir",
-        str(book_dir),
+        str(render_dir),
         "--out",
         str(out_file),
         "--shots-dir",
@@ -361,7 +440,7 @@ def browser_layout(book_dir, verbose):
     for _family, url in font_face_entries(FONTS_CSS.read_text(encoding="utf-8")):
         target = (FONTS_CSS.parent / url).resolve()
         font_assets_by_name[target.name] = target.stat().st_size if target.is_file() else 0
-    width_floor = {1280: 640, 768: 500, 390: 320}
+    width_floor = {1280: 640, 768: 500, 390: 320, 360: 300}
     for width_text, pages in metrics["viewports"].items():
         width = int(width_text)
         for key, data in pages.items():
@@ -371,6 +450,9 @@ def browser_layout(book_dir, verbose):
                 problems.append(f"{label}: {data['error']}")
                 continue
             requested_fonts = data.get("requestedFonts", [])
+            # MathJax 自带 CHTML 字体（mjx-*）：数学公式必须用它才有 TeX 字形，
+            # 不算「主题外字体漂移」，也不计入本站字体预算。
+            requested_fonts = [name for name in requested_fonts if not name.startswith("mjx-")]
             unknown_fonts = sorted(set(requested_fonts) - set(font_assets_by_name))
             if unknown_fonts:
                 problems.append(f"{label}: unknown font requests {unknown_fonts}")
@@ -411,6 +493,33 @@ def browser_layout(book_dir, verbose):
                     problems.append(
                         f"{label}: 窄屏左栏浮层底色 alpha={alpha}，正文会透上来，需不透明"
                     )
+            # 栏间分隔只留顶栏下那一条通栏横线：桌面左栏不得有右边框，
+            # 顶栏底边恰好 1px 且次级导航不再自己画一条，正文 h2 不带伪元素短线。
+            # 依据见 references/theme-system.md「定尺度」与「组件约定·章节线」。
+            if overlay and width > 991.98 and overlay.get("borderRightWidth", 0) != 0:
+                problems.append(
+                    f"{label}: 桌面左栏 border-right="
+                    f"{overlay['borderRightWidth']}px，应为 0（栏间不画竖线）"
+                )
+            header_rule = data.get("headerRule") or {}
+            if header_rule:
+                if abs(header_rule.get("borderBottomWidth", 0) - 1) > 0.01:
+                    problems.append(
+                        f"{label}: 顶栏底边 "
+                        f"{header_rule.get('borderBottomWidth')}px，应为 1px 通栏发丝线"
+                    )
+                if header_rule.get("secondaryBorderBottomWidth", 0):
+                    problems.append(
+                        f"{label}: 次级导航底边 "
+                        f"{header_rule['secondaryBorderBottomWidth']}px，会和顶栏底边叠成双线"
+                    )
+            h2_after = data.get("h2Rules") or []
+            if h2_after:
+                first = h2_after[0]
+                problems.append(
+                    f"{label}: h2「{first['text']}」仍有装饰短线 "
+                    f"{first['afterWidth']}×{first['afterHeight']}，章节不画线"
+                )
             # 侧栏折叠层级：桌面视口下只有当前页所在的分组默认展开。
             # 其余分组折叠。依据见本仓 designing-theme 技能的主题说明。
             sections = data.get("sidebarSections")
@@ -427,24 +536,25 @@ def browser_layout(book_dir, verbose):
                         f"{label}: 侧栏展开的不是当前页所在分组 "
                         f"（展开={expanded[0]['text']}）"
                     )
-            paragraph_font_size = data.get("paragraphFontSize", 0)
+            # Callout 按 theme-system.md「组件约定」是薄条：2px 左色条、无填充、无圆角，
+            # 标题 13px、正文 16px，上下内边距各 0.1rem（根字号 16px 时 1.6px）。
+            # 不跟正文 17px 比——Callout 是附注层，比正文低一档是有意为之。
             for index, callout in enumerate(data.get("callouts", []), 1):
-                if abs(callout["bodyFontSize"] - paragraph_font_size) > 0.01:
+                if abs(callout["bodyFontSize"] - 16) > 0.01:
                     problems.append(
-                        f"{label}: Callout#{index} 正文 {callout['bodyFontSize']}px "
-                        f"!= 正文 {paragraph_font_size}px"
+                        f"{label}: Callout#{index} 正文 {callout['bodyFontSize']}px != 16px"
                     )
-                if abs(callout["titleFontSize"] - 15) > 0.01:
+                if abs(callout["titleFontSize"] - 13) > 0.01:
                     problems.append(
-                        f"{label}: Callout#{index} 标题 {callout['titleFontSize']}px != 15px"
+                        f"{label}: Callout#{index} 标题 {callout['titleFontSize']}px != 13px"
                     )
                 if (
-                    abs(callout["paddingTop"] - 16) > 0.01
-                    or abs(callout["paddingBottom"] - 16) > 0.01
+                    abs(callout["paddingTop"] - 1.6) > 0.05
+                    or abs(callout["paddingBottom"] - 1.6) > 0.05
                 ):
                     problems.append(
                         f"{label}: Callout#{index} 内边距 "
-                        f"{callout['paddingTop']}/{callout['paddingBottom']}px != 16/16px"
+                        f"{callout['paddingTop']}/{callout['paddingBottom']}px != 1.6/1.6px"
                     )
                 if callout["width"] + 1 < data["paragraphWidth"]:
                     problems.append(
@@ -493,14 +603,31 @@ def browser_layout(book_dir, verbose):
     return problems, None, info
 
 
-def needs_cjk_coverage(codepoint):
-    """Only assert self-hosted coverage for CJK text and CJK punctuation."""
-    return (
-        0x2E80 <= codepoint <= 0x9FFF
-        or 0xF900 <= codepoint <= 0xFAFF
-        or 0x3000 <= codepoint <= 0x303F
-        or 0xFF00 <= codepoint <= 0xFFEF
-    )
+# 自托管字面必须覆盖的码位：汉字与中文标点之外，还包括西文标点、数学/箭头的
+# 「书中符号」。漏了它们不会被发现，却会静默回落到系统字体——同一个「+」会按
+# 系统 CJK 字体的中线画在 0.5em 高度，紧挨 0.23em 的拉丁基线，肉眼就是「++ 偏上」。
+# 表情符号（≥U+1F000 与 U+2600–U+27BF 的装饰符）按设计就该由系统 emoji 字体绘制，不在断言内。
+GLYPH_RANGES = (
+    (0x00A0, 0x024F),  # Latin-1 补充 + Latin Extended-A
+    (0x2000, 0x206F),  # 通用标点（引号、破折号、省略号、间隔号）
+    (0x20A0, 0x20BF),  # 货币符号
+    (0x2100, 0x214F),  # 字母式符号（℃ ™ №）
+    (0x2190, 0x21FF),  # 箭头
+    (0x2200, 0x22FF),  # 数学运算符
+    (0x2500, 0x257F),  # 制表符（终端输出里的 ├ ─ └ │）
+    (0x25A0, 0x25FF),  # 几何图形（■ □ ▲）
+    (0x2E80, 0x2EFF),  # CJK 部首补充
+    (0x3000, 0x303F),  # CJK 标点
+    (0x4E00, 0x9FFF),  # 汉字
+    (0xF900, 0xFAFF),  # CJK 兼容汉字
+    (0xFE30, 0xFE4F),  # CJK 兼容形式
+    (0xFF00, 0xFFEF),  # 全角形式（＋ － ＝ （））
+)
+
+
+def needs_glyph_coverage(codepoint):
+    """Assert self-hosted coverage for CJK text, CJK punctuation and book symbols."""
+    return any(start <= codepoint <= end for start, end in GLYPH_RANGES)
 
 
 def read_font_cmap(path):
@@ -563,13 +690,90 @@ def check_font_coverage(book_dir):
                 for char in chunk:
                     codepoint = ord(char)
                     if (
-                        needs_cjk_coverage(codepoint)
+                        needs_glyph_coverage(codepoint)
                         and codepoint not in coverage[family]
                     ):
                         missing[family].add(char)
     return coverage, missing
 
 
+def _parse_hex_color(value):
+    match = re.fullmatch(r"#([0-9a-fA-F]{6})", value.strip())
+    if not match:
+        return None
+    digits = match.group(1)
+    return tuple(int(digits[i : i + 2], 16) for i in (0, 2, 4))
+
+
+def _relative_luminance(rgb):
+    channels = []
+    for value in rgb:
+        v = value / 255
+        channels.append(v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4)
+    return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]
+
+
+def _contrast_ratio(fg, bg):
+    hi, lo = sorted((_relative_luminance(fg), _relative_luminance(bg)), reverse=True)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def check_palette_contrast():
+    """色板正文/次要/链接/代码前景对各自底色都需 >= 4.5:1。
+
+    只读 tokens.css 的顶层定义块，跳过 prefers-contrast 的增强段：
+    那里本来就该更高。Solarized 的语法彩色 token 由官方配色决定，
+    不在本断言范围内（见 theme-system.md 的对比度说明）。
+    """
+
+    palette_dir = THEME_DIR / "assets" / "theme" / "palettes"
+    pairs = (
+        ("body", "--body-color", "--page-bg"),
+        ("secondary", "--text-secondary", "--page-bg"),
+        ("link", "--link-color", "--page-bg"),
+        ("code", "--code-fg", "--code-bg"),
+        ("line numbers", "--line-num-color", "--code-bg"),
+        ("code title", "--code-title-fg", "--code-title-bg"),
+    )
+    failures = []
+    for palette in ("flexoki", "solarized", "hill-light"):
+        tokens_path = palette_dir / palette / "tokens.css"
+        if not tokens_path.is_file():
+            continue
+        css = tokens_path.read_text(encoding="utf-8")
+        css = re.sub(r"/\*.*?\*/", "", css, flags=re.S)
+        for match in re.finditer(r"([^{}]+)\{([^{}]*)\}", css):
+            selector = " ".join(match.group(1).split())
+            if "@media" in selector or "prefers-contrast" in selector:
+                continue
+            body = match.group(2)
+            if "--page-bg" not in body:
+                continue
+            mode_match = re.search(r'data-mode="(\w+)"', selector)
+            if palette == "hill-light":
+                if " body" not in selector:
+                    continue
+                mode = mode_match.group(1) if mode_match else "dawn"
+            else:
+                if " body" not in selector:
+                    continue
+                mode = "dark" if "quarto-dark" in selector else "light"
+            values = dict(re.findall(r"(--[a-z0-9-]+)\s*:\s*([^;]+);", body))
+            for name, fg_token, bg_token in pairs:
+                fg = _parse_hex_color(values.get(fg_token, ""))
+                bg = _parse_hex_color(values.get(bg_token, ""))
+                if not fg or not bg:
+                    continue
+                ratio = _contrast_ratio(fg, bg)
+                if ratio < 4.5:
+                    failures.append(
+                        f"{palette}/{mode}: {name} {ratio:.2f}:1 "
+                        f"({values.get(fg_token).strip()} on {values.get(bg_token).strip()})"
+                    )
+    return failures
+
+
+
 def main():
     try:
         sys.stdout.reconfigure(encoding="utf-8")
@@ -638,6 +842,45 @@ def main():
         if not found:
             fail += 1
 
+    # Solarized 不参与编译，但两份覆盖层必须始终可用；按文件分别核 selector 与色值。
+    solarized_tokens = PALETTE_ROOT / "solarized" / "tokens.css"
+    solarized_syntax = PALETTE_ROOT / "solarized" / "syntax.css"
+    solarized_texts = {}
+    for path in (solarized_tokens, solarized_syntax):
+        if path.is_file():
+            solarized_texts[path.name] = path.read_text(
+                encoding="utf-8", errors="ignore"
+            )
+        else:
+            print(f"  MISS solarized layer file  ({path.as_posix()})")
+            fail += 1
+    hill_tokens = PALETTE_ROOT / "hill-light" / "tokens.css"
+    hill_syntax = PALETTE_ROOT / "hill-light" / "syntax.css"
+    hill_texts = {}
+    for path in (hill_tokens, hill_syntax):
+        if path.is_file():
+            hill_texts[path.name] = path.read_text(encoding="utf-8", errors="ignore")
+        else:
+            print(f"  MISS hill-light layer file  ({path.as_posix()})")
+            fail += 1
+    for texts, path, layer_checks in (
+        (solarized_texts, solarized_tokens, SOLARIZED_TOKEN_CHECKS),
+        (solarized_texts, solarized_syntax, SOLARIZED_SYNTAX_CHECKS),
+        (hill_texts, hill_tokens, HILL_LIGHT_TOKEN_CHECKS),
+        (hill_texts, hill_syntax, HILL_LIGHT_SYNTAX_CHECKS),
+    ):
+        text = texts.get(path.name)
+        if text is None:
+            continue
+        for name, pattern in layer_checks:
+            found = pattern in text
+            mark = "OK  " if found else "MISS"
+            print(f"  {mark} {name}  ({pattern})")
+            if not found:
+                fail += 1
+
+    fail += check_hill_light_modes(hill_texts.get("tokens.css", ""))
+
     callouts_css = (
         THEME_DIR / "assets" / "theme" / "css" / "callouts.css"
     ).read_text(encoding="utf-8")
@@ -661,6 +904,21 @@ def main():
         if found:
             fail += 1
 
+    contrast_failures = check_palette_contrast()
+    print(f"  {'MISS' if contrast_failures else 'OK  '} palette text contrast >= 4.5:1")
+    if contrast_failures:
+        for line in contrast_failures:
+            print(f"       {line}")
+        fail += 1
+
+    css_defined = set(re.findall(r"(--[a-z0-9-]+)\s*:", theme_text))
+    css_used = set(re.findall(r"var\(\s*(--[a-z0-9-]+)", theme_text))
+    undefined_tokens = sorted(css_used - css_defined)
+    print(f"  {'MISS' if undefined_tokens else 'OK  '} css tokens all defined")
+    if undefined_tokens:
+        print("       " + ", ".join(undefined_tokens))
+        fail += 1
+
     legacy_font_files = sorted(
         p.name
         for pattern in ("inter-*", "noto-sans-sc-*", "jetbrains-mono-*")
@@ -715,7 +973,7 @@ def main():
     else:
         print(
             f"  {'OK  ' if not browser_problems else 'MISS'} browser-layout"
-            f"  (viewports=1280,768,390; schemes=light,dark; "
+            f"  (viewports=1280,768,390,360; schemes=light,dark; "
             f"mode={browser_info.get('mode', 'n/a')}; "
             f"pages={browser_info.get('pages', 0)})"
         )
@@ -732,7 +990,7 @@ def main():
             print(
                 "PASS theme-static；browser-layout "
                 f"{browser_info.get('mode', 'full')} "
-                f"{browser_info.get('pages', 0)} pages × 1280/768/390 × light/dark"
+                f"{browser_info.get('pages', 0)} pages × 1280/768/390/360 × light/dark"
             )
         return 0
     print(f"{fail} theme check(s) failed; inspect the diagnostics above.")

package/skills/designing-theme/scripts/measuring-pages.mjs

@@ -20,7 +20,7 @@ const bookDir = resolve(flag("--book-dir", "_book"));
 const outFile = flag("--out", "");
 const shotsDir = flag("--shots-dir", "");
 const allPages = argv.includes("--all-pages");
-const viewports = [1280, 768, 390];
+const viewports = [1280, 768, 390, 360];
 const colorSchemes = ["light", "dark"];
 
 async function collectHtml(directory) {
@@ -152,6 +152,9 @@ async function collect(page, pageId, scheme) {
       for (const element of scope.querySelectorAll("*")) {
         if (
           element.closest(".screen-reader-only, .sr-only, [aria-hidden='true']")
+          // 内联 SVG（棋盘快照等）没有 CSS 盒模型，<text> 的 clientWidth 恒为 0、
+          // scrollWidth 按字形量出，天然「溢出」，不能当版式问题。
+          || element.closest("svg")
           || style(element).display === "none"
           || style(element).visibility === "hidden"
         ) {
@@ -160,13 +163,22 @@ async function collect(page, pageId, scheme) {
         if (!element.clientWidth || element.scrollWidth <= element.clientWidth + 1) {
           continue;
         }
-        const overflowX = style(element).overflowX;
+        // 宽于容器的元素只有整页横向滚动条才算问题：代码行本身宽于 <pre> 是常态，
+        // <pre> 自己 overflow-x: auto 就不该上报。所以沿祖先链找真正的滚动容器。
+        let scrolls = false;
+        for (let node = element; node && node !== document.body; node = node.parentElement) {
+          const overflowX = style(node).overflowX;
+          if (overflowX === "auto" || overflowX === "scroll") {
+            scrolls = true;
+            break;
+          }
+        }
         overflow.push({
           tag: element.tagName.toLowerCase(),
           classes: typeof element.className === "string" ? element.className.slice(0, 80) : "",
           scrollWidth: element.scrollWidth,
           clientWidth: element.clientWidth,
-          scrolls: overflowX === "auto" || overflowX === "scroll",
+          scrolls,
           inPre: Boolean(element.closest("pre")),
         });
       }
@@ -183,6 +195,29 @@ async function collect(page, pageId, scheme) {
           borderRightWidth: px(style(sidebar).borderRightWidth),
         }
       : null;
+    // 栏间分隔只该有顶栏下那一条：读 #quarto-header 的底边，和有没有 h2 短伪元素线。
+    // 三个数据都来自计算样式，不依赖主题里写了什么，改回旧规则会直接失败。
+    const header = document.querySelector("#quarto-header");
+    const headerRule = header
+      ? {
+          borderBottomWidth: px(style(header).borderBottomWidth),
+          borderBottomColor: style(header).borderBottomColor,
+          secondaryBorderBottomWidth: px(
+            style(document.querySelector("nav.quarto-secondary-nav") || header).borderBottomWidth
+          ),
+        }
+      : null;
+    const h2Rules = [...document.querySelectorAll("#quarto-document-content h2")]
+      .map((heading) => {
+        const after = window.getComputedStyle(heading, "::after");
+        return {
+          text: heading.textContent.trim().slice(0, 30),
+          afterContent: after.content,
+          afterWidth: px(after.width),
+          afterHeight: px(after.height),
+        };
+      })
+      .filter((item) => item.afterContent && item.afterContent !== "none" && item.afterHeight > 0);
     // 折叠状态来自构建期写入的 expanded：顶层 part 以 depth=1 渲染，
     // collapse-level 决定哪一层默认展开。断言只看 show 类，不看动画中间态。
     const sidebarSections = sidebar
@@ -224,6 +259,8 @@ async function collect(page, pageId, scheme) {
       copyButtonOpacities,
       sidebarOverlay,
       sidebarSections,
+      headerRule,
+      h2Rules,
       contentWidth: px(rootStyle.width),
       color: rootStyle.color,
       backgroundColor: style(document.body).backgroundColor,

package/skills/writing-quarto/examples/01-language-scope.md

@@ -4,7 +4,7 @@
 
 ## 语言课旁白与工程旁白
 
-`content/**` 正文禁止用旁白讲解 C++ 语言机制或风格指南条目（硬边界见 `writing-quarto` 技能 `steps/01-task.md`「叙事范围（硬边界）」；三个工程问题与反例句式见`steps/01-task.md`，判定口诀同在该条文）。以下对照收工程旁白的定稿形态：
+`content/**` 正文禁止用旁白讲解 C++ 语言机制或风格指南条目（硬边界见 `writing-quarto` 技能 `steps/01-task.md`「叙事范围（硬边界）」；三个工程问题与反例句式见 `steps/01-task.md`，判定口诀同在该条文）。以下对照收工程旁白的定稿形态：
 
 对照一：常量与类型定义（示例章 state.h 节）。
 
@@ -46,7 +46,7 @@ Position 携带从 0 起算的行列坐标，越界由 IsInRange 判为非法：
 正确（先动作 → 再点名成员 → 后边界）：
 终端程序把「行 列」变成一次操作动作后，只能调用 Game 的三个成员去改状态面板或查结果，
 不能直接改私有数组 cells_。测试也调用同一组成员。
-Game::Place 负责写入数据项；Game::GetCellState 负责读某个数据项的状态；
+Game::ApplyMove 负责写入数据项；Game::ReadCellState 负责读某个数据项的状态；
 Game::GetResult 负责报告流程结果。
 ```
 
@@ -67,7 +67,7 @@ Game 不调用终端程序，也不读键盘。
 
 ## 流程交流不绑定媒介与行为刚性表述
 
-以 首章观察一次流程节改稿前为对照。把交流绑定到具体媒介、把行为写成刚性属性，都会在后续编号目录更换界面或引入协议时与前面冲突（禁用与替换见`steps/06-wording.md`）：
+以 首章观察一次流程节改稿前为对照。把交流绑定到具体媒介、把行为写成刚性属性，都会在后续编号目录更换界面或引入协议时与前面冲突（禁用与替换见 `steps/06-wording.md`）：
 
 ```text
 不佳（媒介绝对化，「只发生在」把流程交流写死在终端）：

package/skills/writing-quarto/examples/02-structure-shape.md

@@ -22,7 +22,7 @@
 
 ## 定结构：标题只留对象名
 
-条文见`steps/02-structure.md`「标题字数」「形式规则」。两个旧标题都在旧字数上限内，仍是一句步骤说明：指示、过程动词和关系词把真正的对象挤到末尾；目录、侧栏和页内 TOC 需要的是对象名，不是把导语缩进标题。改写在定结构：先圈出目录里要扫到的对象，删掉指示、过程和数量，再检查同级句式是否一致。
+条文见 `steps/02-structure.md`「标题字数」「形式规则」。两个旧标题都在旧字数上限内，仍是一句步骤说明：指示、过程动词和关系词把真正的对象挤到末尾；目录、侧栏和页内 TOC 需要的是对象名，不是把导语缩进标题。改写在定结构：先圈出目录里要扫到的对象，删掉指示、过程和数量，再检查同级句式是否一致。
 
 **定结构（示例章「记下流程数据」下两个三级标题）：**
 
@@ -40,7 +40,7 @@
 
 ## 小节标题抽象与首句无中心
 
-小节标题用了读者没学过的术语怎么办，与一段压缩多个论断怎么改，是同一类病。示例章依赖节的两次改稿对照：第一轮标题读不出动作对象，首句堆齐名称后才在句尾给出结论；第二轮标题动作化了，但「使用方」仍是读者未建立的术语，正文一句压缩三个论断，读者无法逐条核对（规则见`steps/03-blocks.md`「小节标题与正文对齐」）：
+小节标题用了读者没学过的术语怎么办，与一段压缩多个论断怎么改，是同一类病。示例章依赖节的两次改稿对照：第一轮标题读不出动作对象，首句堆齐名称后才在句尾给出结论；第二轮标题动作化了，但「使用方」仍是读者未建立的术语，正文一句压缩三个论断，读者无法逐条核对（规则见 `steps/03-blocks.md`「小节标题与正文对齐」）：
 
 ```text
 不佳（标题抽象 + 首句无中心）：
@@ -83,7 +83,7 @@
 
 ## 树注释点名文件与问答式读法句
 
-示例章改稿前的两个反例：树注释点名下层实现文件，与同棵树的职责注释不同层级；树后读法句用问答式并列把前半句再讲一遍，像写给工具的格式规格，不像给读者的解说（规则见`steps/03-blocks.md`  与 `steps/01-task.md`）：
+示例章改稿前的两个反例：树注释点名下层实现文件，与同棵树的职责注释不同层级；树后读法句用问答式并列把前半句再讲一遍，像写给工具的格式规格，不像给读者的解说（规则见 `steps/03-blocks.md`  与 `steps/01-task.md`）：
 
 ```text
 不佳（树注释列举实现文件名）：
@@ -109,7 +109,7 @@
 
 ## 树后换对象收束句
 
-目录树后能补一段工具配置的分工吗：不能换对象。示例章改稿对照：树后两句把主语换成 `.clang-format`、`.clang-tidy`、`.clangd` 三份工具配置，而本节标题和清单的对象是四个目录；第二句「三份配置只描述工具怎么检查代码，CMake 构建规则不依赖它们」还与仓库事实不符——`.clangd` 的 `CompileFlags.Add` 是未构建时的解析兜底，不是检查规则，CMake 会为 clangd 导出 `build/compile_commands.json`（规则见`steps/04-paragraphs.md`「段间：过渡句只在话题切换处」与 `steps/03-blocks.md`「小节标题与正文对齐」）：
+目录树后能补一段工具配置的分工吗：不能换对象。示例章改稿对照：树后两句把主语换成 `.clang-format`、`.clang-tidy`、`.clangd` 三份工具配置，而本节标题和清单的对象是四个目录；第二句「三份配置只描述工具怎么检查代码，CMake 构建规则不依赖它们」还与仓库事实不符——`.clangd` 的 `CompileFlags.Add` 是未构建时的解析兜底，不是检查规则，CMake 会为 clangd 导出 `build/compile_commands.json`（规则见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」与 `steps/03-blocks.md`「小节标题与正文对齐」）：
 
 ```text
 不佳（树后收束句换成本节清单没有的对象）：
@@ -154,7 +154,7 @@
 
 ## 自测问可观察结果
 
-以 示例章自测第 1 题改稿前为对照。「为什么后手不能在开局直接落在中心」把「中心」当成读者已认识的概念，本章正文从未定义中心格；拒绝的原因也与格子无关——空状态面板上轮到甲方，O 落在哪一格都会被拒绝。题面用本章没说全的情景提问，读者会以为中心格另有规则（步骤：定结构；规则见`steps/02-structure.md`「六段块序列」）：
+以 示例章自测第 1 题改稿前为对照。「为什么后手不能在开局直接落在中心」把「中心」当成读者已认识的概念，本章正文从未定义中心格；拒绝的原因也与格子无关——空状态面板上轮到甲方，O 落在哪一格都会被拒绝。题面用本章没说全的情景提问，读者会以为中心格另有规则（步骤：定结构；规则见 `steps/02-structure.md`「六段块序列」）：
 
 ```text
 不佳（题面用了本章未定义的概念，情景没说全）：