voxflow 1.15.6 → 1.17.0

package/skills/card/references/themes/presets.md

@@ -0,0 +1,314 @@
+# Theme Presets
+
+Use these presets as palette and composition starting points for card sets. The default taste should be closer to magazines, reports, field notes, product manuals, and printed matter than to generic AI SaaS visuals.
+
+## Anti-AI-Template Rule
+
+When style is ambiguous, avoid the usual AI-card signals:
+
+- neon blue/purple gradients, aurora blobs, glowing dark dashboards, terminal green, cyberpunk grids, fake glass panels, and excessive black backgrounds.
+- generic "AI future" imagery, robot hands, abstract brain networks, floating chips, holographic UI, and meaningless data particles.
+- one-note blue/purple palettes or pitch-deck gradients unless the user explicitly asks for them.
+
+Prefer restrained paper color, readable ink, real editorial hierarchy, purposeful whitespace, and one or two quiet accent colors.
+
+## Anti-Plain-Template Rule
+
+Removing AI cliches is not enough. Do not replace them with a plain system of hairlines, coordinate grids, and repeated boxes.
+
+- Do not use a full-card grid background as the default texture.
+- Do not make every content item a bordered rectangle.
+- Do not rely on thin rules and small mono labels as the main source of "design".
+- Prefer large filled fields, cropped objects, image-led composition, typographic scale contrast, torn-paper shapes, stamps, labels, bands, and asymmetric layouts.
+- Use lines and borders sparingly, as accents around a stronger visual anchor.
+
+## Token Model
+
+Every card set should define a compact theme token block before component styling:
+
+- `--bg`, `--bg-soft`
+- `--surface`, `--surface-2`
+- `--border`, `--border-strong`
+- `--text-1`, `--text-2`, `--text-3`
+- `--accent`, `--accent-2`, `--accent-3`
+- `--good`, `--warn`, `--bad`
+- `--grad`, `--grad-soft`
+- `--radius`, `--radius-sm`, `--radius-lg`
+- `--shadow`, `--shadow-lg`
+- `--font-sans`, `--font-serif`, `--font-mono`, `--font-display` — do not hardcode font names here; their values come from the `references/fonts.md` selection algorithm (preset × design-language × content-language → weighted-random pick), embedded locally via `assets/fonts/fonts.css`.
+
+Use tokens in component CSS. Avoid scattering literal colors outside the token block unless a one-off asset or data visualization genuinely requires it.
+
+## Primary Preset Catalog
+
+### `magazine-eink`
+
+Ink-black on warm paper, serif/display headlines, sans-serif body, mono metadata, minimal borders.
+
+Use for editorial carousels, talk summaries, longform explainers, essays, culture, creator narratives, and premium text-led cards.
+
+Suggested tokens:
+
+- `--bg: #f1efea`
+- `--bg-soft: #e8e5de`
+- `--surface: #fbfaf6`
+- `--surface-2: #f4f1ea`
+- `--border: rgba(10, 10, 11, 0.18)`
+- `--border-strong: #0a0a0b`
+- `--text-1: #0a0a0b`
+- `--text-2: #3f3d39`
+- `--text-3: #777169`
+- `--accent: #18181a`
+- `--accent-2: #8f5b34`
+- `--accent-3: #b8aa8c`
+
+### `porcelain-research`
+
+Deep indigo ink on porcelain white, cool but not neon, with precise rules and quiet contrast.
+
+Use for technology, research, data analysis, academic-feeling explainers, serious product narratives, and technical topics that should not look like a hacker poster.
+
+Suggested tokens:
+
+- `--bg: #f1f3f5`
+- `--bg-soft: #e4e8ec`
+- `--surface: #fbfcfd`
+- `--surface-2: #edf2f6`
+- `--border: rgba(10, 31, 61, 0.18)`
+- `--border-strong: #0a1f3d`
+- `--text-1: #0a1f3d`
+- `--text-2: #3b526d`
+- `--text-3: #76879a`
+- `--accent: #174f9a`
+- `--accent-2: #6f8fb4`
+- `--accent-3: #c2a35f`
+
+### `newsroom-paper`
+
+White and light gray editorial base, black text, measured red accent, hard information blocks.
+
+Use for news, incidents, releases, comparisons, urgency, public statements, and factual explainers.
+
+Suggested tokens:
+
+- `--bg: #f7f7f5`
+- `--bg-soft: #ececea`
+- `--surface: #ffffff`
+- `--surface-2: #f0f0ee`
+- `--border: rgba(20, 22, 24, 0.16)`
+- `--border-strong: #141618`
+- `--text-1: #141618`
+- `--text-2: #4b5055`
+- `--text-3: #7b8085`
+- `--accent: #c9342c`
+- `--accent-2: #2f5f86`
+- `--accent-3: #c9a451`
+
+### `quiet-report`
+
+Clean report style with off-white background, charcoal/navy text, modest blue accent, and conservative spacing.
+
+Use for B2B, operations, finance, board updates, enterprise product messaging, and formal summaries.
+
+Suggested tokens:
+
+- `--bg: #f6f7f4`
+- `--bg-soft: #ebeee9`
+- `--surface: #ffffff`
+- `--surface-2: #eef2f3`
+- `--border: rgba(26, 39, 52, 0.15)`
+- `--border-strong: #1a2734`
+- `--text-1: #1a2734`
+- `--text-2: #4a5a66`
+- `--text-3: #7d8a92`
+- `--accent: #2d647f`
+- `--accent-2: #7d8b68`
+- `--accent-3: #c0a062`
+
+### `product-manual`
+
+Instruction-manual feel: warm white, graphite text, practical diagrams, object labels, stamps, and large artifact metaphors.
+
+Use for product notes, how-to guides, API explainers, workflows, checklists, and developer education.
+
+Suggested tokens:
+
+- `--bg: #f4f1ea`
+- `--bg-soft: #e7e2d8`
+- `--surface: #fffdf8`
+- `--surface-2: #ece8df`
+- `--border: rgba(32, 38, 42, 0.18)`
+- `--border-strong: #20262a`
+- `--text-1: #20262a`
+- `--text-2: #4e565b`
+- `--text-3: #7f8587`
+- `--accent: #3b6f75`
+- `--accent-2: #9a6b37`
+- `--accent-3: #c7b474`
+
+### `engineering-paper`
+
+White engineering paper, navy ink, sparse mono labels, precise diagrams, and strong technical artifacts. Do not default to full-canvas coordinate grids.
+
+Use for architecture, system design, infrastructure, API flows, technical documentation, and engineering explainers.
+
+Suggested tokens:
+
+- `--bg: #f7f8f3`
+- `--bg-soft: #eef3f6`
+- `--surface: #ffffff`
+- `--surface-2: #edf3f8`
+- `--border: rgba(17, 36, 58, 0.16)`
+- `--border-strong: #11243a`
+- `--text-1: #102033`
+- `--text-2: #3f566b`
+- `--text-3: #708292`
+- `--accent: #1468a8`
+- `--accent-2: #8a7044`
+- `--accent-3: #c9a24e`
+
+### `field-notes`
+
+Ivory paper, forest ink, muted green and clay accents, calm non-fiction tone.
+
+Use for sustainability, culture, public-interest explainers, field research, community, and reflective narratives.
+
+Suggested tokens:
+
+- `--bg: #f5f1e8`
+- `--bg-soft: #ece7da`
+- `--surface: #fffaf0`
+- `--surface-2: #eee8d9`
+- `--border: rgba(26, 46, 31, 0.18)`
+- `--border-strong: #1a2e1f`
+- `--text-1: #1a2e1f`
+- `--text-2: #485849`
+- `--text-3: #7f8979`
+- `--accent: #2f6d4f`
+- `--accent-2: #8b6b3e`
+- `--accent-3: #c9b276`
+
+### `kraft-editorial`
+
+Warm kraft paper, dark brown ink, archival texture, independent-magazine warmth.
+
+Use for history, reading notes, handmade brands, personal essays, retro product stories, and literary cards.
+
+Suggested tokens:
+
+- `--bg: #eedfc7`
+- `--bg-soft: #e0d0b6`
+- `--surface: #f8ecd8`
+- `--surface-2: #ead8bb`
+- `--border: rgba(42, 30, 19, 0.2)`
+- `--border-strong: #2a1e13`
+- `--text-1: #2a1e13`
+- `--text-2: #604c38`
+- `--text-3: #8e7b64`
+- `--accent: #8f4b28`
+- `--accent-2: #2f5d50`
+- `--accent-3: #b9894a`
+
+### `dune-gallery`
+
+Charcoal ink on sand paper, restrained gallery tone, neutral premium feel.
+
+Use for design, art, architecture, brand studies, portfolio stories, and aesthetic-first cards.
+
+Suggested tokens:
+
+- `--bg: #f0e6d2`
+- `--bg-soft: #e3d7bf`
+- `--surface: #fbf3e3`
+- `--surface-2: #eadcc4`
+- `--border: rgba(31, 26, 20, 0.18)`
+- `--border-strong: #1f1a14`
+- `--text-1: #1f1a14`
+- `--text-2: #51483d`
+- `--text-3: #817768`
+- `--accent: #6f6255`
+- `--accent-2: #a06445`
+- `--accent-3: #c9b171`
+
+### `social-notebook`
+
+Warm white, soft red/clay accents, light paper shadows, approachable but still editorial.
+
+Use for Xiaohongshu, creator notes, consumer product tips, lightweight education, and friendly explainers.
+
+Suggested tokens:
+
+- `--bg: #fbf7f2`
+- `--bg-soft: #f2e9e2`
+- `--surface: #ffffff`
+- `--surface-2: #fff2ef`
+- `--border: rgba(86, 54, 46, 0.14)`
+- `--border-strong: #56362e`
+- `--text-1: #302421`
+- `--text-2: #6a5650`
+- `--text-3: #9a8982`
+- `--accent: #c75f55`
+- `--accent-2: #7a8b62`
+- `--accent-3: #d7b77a`
+
+### `bold-editorial`
+
+Cream paper, black editorial type, one warm spot color, strong cover energy without synthetic gradients.
+
+Use for opinion pieces, columns, hot takes, cultural topics, strong hooks, and shareable argument cards.
+
+Suggested tokens:
+
+- `--bg: #f3eadb`
+- `--bg-soft: #e7dac7`
+- `--surface: #fff7ea`
+- `--surface-2: #eadcc8`
+- `--border: rgba(15, 14, 13, 0.22)`
+- `--border-strong: #0f0e0d`
+- `--text-1: #0f0e0d`
+- `--text-2: #4b4037`
+- `--text-3: #807266`
+- `--accent: #d65f2d`
+- `--accent-2: #2f5d6b`
+- `--accent-3: #d5aa4b`
+
+## Legacy Motifs
+
+These names may appear in older card sets. Do not recommend them by default because they often create a generic AI-template feel.
+
+- `tokyo-night`: only use if the user explicitly asks for a dark code-editor mood.
+- `terminal-green`: only use for command-reference cards or intentionally retro terminal artifacts.
+- `neo-brutalism`: only use if the user explicitly wants a loud youth-campaign look.
+- `blueprint`: prefer `engineering-paper` unless the user asks for a dark blueprint.
+- `pitch-deck-vc`: prefer `quiet-report` or `product-manual` unless the user asks for startup deck styling.
+- `soft-pastel`: prefer `social-notebook` unless the user asks for soft consumer colors.
+- `xiaohongshu-white`: prefer `social-notebook`; keep this as a platform-specific alias.
+- `corporate-clean`: prefer `quiet-report`; keep this as a conservative-report alias.
+- `news-broadcast`: prefer `newsroom-paper`; keep this as a higher-urgency alias.
+- `engineering-whiteprint`: prefer `engineering-paper`; keep this as a technical-paper alias.
+- `magazine-bold`: prefer `bold-editorial`; keep this as an older alias.
+- `editorial-serif`: prefer `magazine-eink`; keep this as an older alias.
+
+## Scenario Mapping
+
+When the style is ambiguous, recommend 2-3 user-facing directions and map them internally to presets:
+
+- Business/report: `quiet-report`, `product-manual`, `porcelain-research`.
+- Engineering/API/system: `engineering-paper`, `product-manual`, `porcelain-research`.
+- Social/Xiaohongshu: `social-notebook`, `magazine-eink`, `bold-editorial`.
+- News/update/incident: `newsroom-paper`, `quiet-report`, `engineering-paper`.
+- Bold opinion: `bold-editorial`, `magazine-eink`, `newsroom-paper`.
+- Editorial/magazine: `magazine-eink`, `dune-gallery`, `field-notes`, `kraft-editorial`.
+- Design/art/brand: `dune-gallery`, `magazine-eink`, `bold-editorial`.
+- Culture/history/reading: `kraft-editorial`, `field-notes`, `magazine-eink`.
+- Technical CLI/security: `engineering-paper`, `product-manual`, `newsroom-paper`; use `terminal-green` only on explicit request.
+
+## Guardrails
+
+- Keep letter spacing at `0` unless uppercase micro-label tracking is necessary. Do not use negative letter spacing.
+- Avoid one-note palettes unless the user explicitly asks for a monochrome look.
+- Use dark themes sparingly. If a card needs dark contrast, make it feel like black ink, night photography, or print inversion rather than neon code wallpaper.
+- For technical topics, prefer `engineering-paper`, `product-manual`, or `porcelain-research` before any dark developer motif.
+- Prefer texture through typography, cropped shapes, stamps, labels, image/object anchors, captions, paper color, and real images instead of abstract glowing decoration.
+- Do not make fine-line grids, rectangular panels, or hairline diagrams the primary visual language unless the user explicitly asks for blueprint/spec-sheet aesthetics.
+- For final exports, keep source inspiration in `sources.md` or `credits.md` when relevant.

package/skills/card/scripts/download-fonts.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# download-fonts.sh — 把卡片用字体下载到 skill 本地 assets/fonts/，并生成 fonts.css。
+#
+# 设计：
+#   - 全部为 OFL / ITF Free Font License，可内嵌打包分发。
+#   - woff2 优先；fontsource 可变字体单轴覆盖全字重，体积最小。
+#   - 幂等：已存在则跳过；--force 重新下载。
+#   - 零额外依赖：只用 curl + python3 标准库。
+#   - 非 OFL 字体（HarmonyOS / 阿里普惠 / 京華老宋）不在此下载，授权不允许随仓库再分发；
+#     这些在 references/fonts.md 里仅作「系统字体回退」选项，不内嵌。
+#
+# 用法：
+#   bash scripts/download-fonts.sh            # 下载缺失字体
+#   bash scripts/download-fonts.sh --force    # 全部重新下载
+#
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FORCE="${1:-}"
+
+python3 - "$HERE" "$FORCE" <<'PY'
+import sys, os, re, json, urllib.request, urllib.error
+
+ROOT, FORCE = sys.argv[1], (len(sys.argv) > 2 and sys.argv[2] == "--force")
+OUT = os.path.join(ROOT, "assets", "fonts")
+UA = {"User-Agent": "Mozilla/5.0 (font-fetch; voxflow-card)"}
+
+def get(url, binary=False, tries=3):
+    last = None
+    for _ in range(tries):
+        try:
+            req = urllib.request.Request(url, headers=UA)
+            with urllib.request.urlopen(req, timeout=40) as r:
+                return r.read() if binary else r.read().decode("utf-8", "replace")
+        except Exception as e:  # noqa
+            last = e
+    raise last
+
+def save(path, data):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    mode = "wb" if isinstance(data, (bytes, bytearray)) else "w"
+    with open(path, mode) as f:
+        f.write(data)
+
+def need(path):
+    return FORCE or not os.path.exists(path) or os.path.getsize(path) == 0
+
+# fontsource 包：拉 index.css，把 'Xxx Variable' 家族名改回 'Xxx'，再下所有引用的 woff2。
+# (dir, jsdelivr_pkg, css_path, family_variable, family_final)
+FONTSOURCE = [
+    ("geist",                "@fontsource-variable/geist@latest",         "index.css", "Geist Variable",          "Geist"),
+    ("geist-mono",           "@fontsource-variable/geist-mono@latest",    "index.css", "Geist Mono Variable",     "Geist Mono"),
+    ("space-grotesk",        "@fontsource-variable/space-grotesk@latest", "index.css", "Space Grotesk Variable",  "Space Grotesk"),
+    ("newsreader",           "@fontsource-variable/newsreader@latest",    "index.css", "Newsreader Variable",     "Newsreader"),
+    ("source-serif-4",       "@fontsource-variable/source-serif-4@latest","index.css", "Source Serif 4 Variable", "Source Serif 4"),
+    ("spectral",             "@fontsource/spectral@latest",               "400.css",   "Spectral",                "Spectral"),
+    ("spectral-600",         "@fontsource/spectral@latest",               "600.css",   "Spectral",                "Spectral"),
+    ("spectral-800",         "@fontsource/spectral@latest",               "800.css",   "Spectral",                "Spectral"),
+    ("ibm-plex-mono",        "@fontsource/ibm-plex-mono@latest",          "400.css",   "IBM Plex Mono",           "IBM Plex Mono"),
+    ("ibm-plex-mono-500",    "@fontsource/ibm-plex-mono@latest",          "500.css",   "IBM Plex Mono",           "IBM Plex Mono"),
+    ("ibm-plex-mono-600",    "@fontsource/ibm-plex-mono@latest",          "600.css",   "IBM Plex Mono",           "IBM Plex Mono"),
+    ("libre-caslon-display", "@fontsource/libre-caslon-display@latest",   "400.css",   "Libre Caslon Display",    "Libre Caslon Display"),
+    ("noto-sans-sc",         "@fontsource-variable/noto-sans-sc@latest",  "index.css", "Noto Sans SC Variable",   "Noto Sans SC"),
+    ("noto-serif-sc",        "@fontsource-variable/noto-serif-sc@latest", "index.css", "Noto Serif SC Variable",  "Noto Serif SC"),
+]
+
+# 嵌套 @import 的整包（lxgw lite / 得意黑）：递归抓 css 与 woff2，保持相对结构。
+# rename: 把包内声明的 family 归一到 fonts.md 用的名字（最长匹配优先）。
+# 第4位 keep：仅保留入口 css 中 @import 文件名命中这些子串的变体（None=全留）。
+# 霞鹜文楷瘦身：只留 regular + bold 普通体，丢弃 light 与全部 mono 变体。
+PACKAGED = [
+    ("lxgw-wenkai", "https://cdn.jsdelivr.net/npm/lxgw-wenkai-lite-webfont/style.css",
+     [("LXGW WenKai Lite", "LXGW WenKai")],
+     ["lxgwwenkailite-regular", "lxgwwenkailite-bold"]),
+    ("smiley-sans", "https://cdn.jsdelivr.net/npm/cn-fontsource-smiley-sans-oblique-regular/font.css",
+     [], None),
+]
+
+# Fontshare（ITF-FFL，可变 woff2，单文件/家族）。
+FONTSHARE = [
+    ("satoshi",         "Satoshi"),
+    ("general-sans",    "General Sans"),
+    ("cabinet-grotesk", "Cabinet Grotesk"),
+]
+
+report = []
+
+def do_fontsource(dirn, pkg, csspath, famv, famf):
+    base = f"https://cdn.jsdelivr.net/npm/{pkg}/{csspath}"
+    dst_css = os.path.join(OUT, "css", dirn + ".css")
+    if need(dst_css):
+        css = get(base)
+        # 家族名归一：'Xxx Variable' -> 'Xxx'
+        css = css.replace(f"'{famv}'", f"'{famf}'").replace(f'"{famv}"', f'"{famf}"')
+        # 把 url(./files/x.woff2) 改为指向集中 woff2 目录
+        css = re.sub(r"url\(\.?/?(?:files/)?([^)]+\.woff2)\)",
+                     lambda m: f"url(../woff2/{dirn}/{os.path.basename(m.group(1))})", css)
+        save(dst_css, css)
+    files = re.findall(r"url\(\.\./woff2/%s/([^)]+\.woff2)\)" % re.escape(dirn),
+                        open(dst_css).read())
+    n = 0
+    for fn in sorted(set(files)):
+        dst = os.path.join(OUT, "woff2", dirn, fn)
+        if need(dst):
+            save(dst, get(f"https://cdn.jsdelivr.net/npm/{pkg}/files/{fn}", binary=True))
+            n += 1
+    sz = dir_size(os.path.join(OUT, "woff2", dirn))
+    report.append((famf, dirn, len(set(files)), sz, "OFL/ITF" ))
+    print(f"  fontsource {famf:<22} files={len(set(files)):<3} new={n:<3} {human(sz)}")
+
+def do_packaged(dirn, top, rename, keep):
+    # 递归：解析 @import 与 url() 的 woff2/css，全部镜像到 packages/<dirn>/
+    root = os.path.join(OUT, "packages", dirn)
+    entry = os.path.basename(top)
+    seen = set()
+    csspaths = []
+    def fetch(url, rel):
+        if rel in seen:
+            return
+        seen.add(rel)
+        dst = os.path.join(root, rel)
+        is_css = rel.endswith(".css")
+        if need(dst):
+            save(dst, get(url, binary=not is_css))
+        if is_css:
+            txt = open(dst, encoding="utf-8", errors="replace").read()
+            # 入口 css 瘦身：仅保留命中 keep 的 @import 行，重写文件
+            if keep and rel == entry:
+                kept = [ln for ln in txt.splitlines()
+                        if "@import" not in ln or any(k in ln for k in keep)]
+                txt = "\n".join(kept) + "\n"
+                save(dst, txt)
+            csspaths.append(dst)
+            base = url.rsplit("/", 1)[0]
+            for ref in re.findall(r"@import url\(['\"]?\.?/?([^'\")]+)['\"]?\)", txt) + \
+                       re.findall(r"url\(['\"]?\.?/?([^'\")]+\.woff2)['\"]?\)", txt):
+                child_rel = os.path.normpath(os.path.join(os.path.dirname(rel), ref))
+                fetch(base + "/" + ref, child_rel)
+    fetch(top, entry)
+    # family 归一：每次运行都重跑，幂等（最长匹配先替换）
+    for cp in csspaths:
+        t = open(cp, encoding="utf-8", errors="replace").read()
+        orig = t
+        for old, new in rename:
+            t = t.replace("'%s'" % old, "'%s'" % new).replace('"%s"' % old, '"%s"' % new)
+        if t != orig:
+            save(cp, t)
+    sz = dir_size(root)
+    report.append((dirn, "packages/" + dirn, sum(1 for _ in walk_woff2(root)), sz, "OFL"))
+    print(f"  packaged   {dirn:<22} entry={os.path.basename(top):<14} {human(sz)}")
+
+def do_fontshare(slug, family):
+    css = get(f"https://api.fontshare.com/v2/css?f[]={slug}@1&display=swap")
+    m = re.search(r"src:\s*url\(['\"]?(//[^'\")]+\.woff2)", css)
+    wr = re.search(r"font-weight:\s*([0-9]+\s+[0-9]+|[0-9]+)", css)
+    if not m:
+        print(f"  fontshare  {family:<22} SKIP (no woff2 in css)")
+        report.append((family, "fontshare/" + slug, 0, 0, "ITF-FFL (missing)"))
+        return
+    woff2_url = "https:" + m.group(1)
+    weight = wr.group(1) if wr else "400 900"
+    dst = os.path.join(OUT, "woff2", "fontshare", slug + ".woff2")
+    if need(dst):
+        save(dst, get(woff2_url, binary=True))
+    face = (f"/* {family} — Fontshare, ITF Free Font License */\n"
+            f"@font-face{{font-family:'{family}';font-style:normal;font-display:swap;"
+            f"font-weight:{weight};src:url(../woff2/fontshare/{slug}.woff2) format('woff2');}}\n")
+    save(os.path.join(OUT, "css", slug + ".css"), face)
+    sz = os.path.getsize(dst)
+    report.append((family, "fontshare/" + slug, 1, sz, "ITF-FFL"))
+    print(f"  fontshare  {family:<22} weight={weight:<9} {human(sz)}")
+
+def walk_woff2(root):
+    for dp, _, fs in os.walk(root):
+        for f in fs:
+            if f.endswith(".woff2"):
+                yield os.path.join(dp, f)
+
+def dir_size(p):
+    return sum(os.path.getsize(os.path.join(dp, f))
+               for dp, _, fs in os.walk(p) for f in fs) if os.path.isdir(p) else 0
+
+def human(n):
+    for u in ("B", "KB", "MB"):
+        if n < 1024:
+            return f"{n:.0f}{u}"
+        n /= 1024
+    return f"{n:.1f}GB"
+
+print("→ fontsource (Latin VF + 思源黑/宋 分包):")
+for a in FONTSOURCE:
+    try:
+        do_fontsource(*a)
+    except Exception as e:  # noqa
+        print(f"  ! {a[4]} FAILED: {e}")
+
+print("→ packaged (霞鹜文楷 Lite / 得意黑):")
+for a in PACKAGED:
+    try:
+        do_packaged(*a)
+    except Exception as e:  # noqa
+        print(f"  ! {a[0]} FAILED: {e}")
+
+print("→ fontshare (Satoshi / General Sans / Cabinet Grotesk):")
+for a in FONTSHARE:
+    try:
+        do_fontshare(*a)
+    except Exception as e:  # noqa
+        print(f"  ! {a[1]} FAILED: {e}")
+
+# 组装 master fonts.css
+imports = []
+for a in FONTSOURCE:
+    imports.append(f'@import url("./css/{a[0]}.css");')
+for slug, _ in FONTSHARE:
+    imports.append(f'@import url("./css/{slug}.css");')
+for dirn, top, _, _ in PACKAGED:
+    imports.append(f'@import url("./packages/{dirn}/{os.path.basename(top)}");')
+
+master = "/* fonts.css — 本地内嵌字体（download-fonts.sh 生成，勿手改）\n" \
+         "   规则与主题映射见 ../../references/fonts.md。\n" \
+         "   家族名：Geist / Geist Mono / Space Grotesk / Newsreader / Source Serif 4 /\n" \
+         "   Spectral / IBM Plex Mono / Libre Caslon Display / Satoshi / General Sans /\n" \
+         "   Cabinet Grotesk / Noto Sans SC / Noto Serif SC / LXGW WenKai* / Smiley Sans Oblique */\n\n" \
+         + "\n".join(imports) + "\n"
+save(os.path.join(OUT, "fonts.css"), master)
+
+total = dir_size(OUT)
+lines = ["# Font bundle manifest (download-fonts.sh)", "",
+         "| family | path | files | size | license |",
+         "|---|---|---|---|---|"]
+for fam, path, nf, sz, lic in report:
+    lines.append(f"| {fam} | {path} | {nf} | {human(sz)} | {lic} |")
+lines += ["", f"**Total bundle: {human(total)}**", "",
+          "Not bundled (license forbids repo redistribution; system-font fallback only):",
+          "HarmonyOS Sans SC, Alibaba PuHuiTi 3.0, KingHwa OldSong, Zhuque Fangsong, Sarasa Mono SC.",
+          "Sarasa Mono SC / Zhuque Fangsong are OFL but lack a clean woff2 source; add manually if needed."]
+save(os.path.join(OUT, "MANIFEST.md"), "\n".join(lines) + "\n")
+
+print(f"\n✓ fonts.css + MANIFEST.md written. Total bundle: {human(total)}")
+PY