Xuanqing Visual Explainer Cards

Dependencies

This skill requires the following to be installed:

Image generation may use either the host's built-in image tool, such as Codex imagegen, or the user's own OpenAI-compatible image API.

<skill-dir> in the commands below refers to the directory containing this SKILL.md file.

Visual Explainer Cards

Create social cards that readers understand visually before reading closely.

This skill is Editorial-first: serif display titles (Playfair Display + Noto Serif SC), sans body, mono meta. IKB Klein Blue is the visible system color on every page (chrome, foot, section labels, dividers, page numbers). Mustard Yellow appears exactly once per set, on the cover horizontal bar — nowhere else.

It pairs that strict typography system with GPT Image 2 illustrations that may carry a small number of exact Chinese labels.

Default to a hybrid composition:

• Render the outer card, large titles, body copy, bottom takeaways, page rhythm, and editorial structure in HTML.
• Generate illustrations for most content pages — text leads, illustration explains. Use small, supporting illustrations (160-560px depending on page role), not one full-canvas centerpiece per set.
• Allow only small, high-value in-image labels inside generated illustrations. Keep long explanations and caveats in HTML.
• The cover (S00) is the only fixed layout in the system. Content pages are composed fresh from primitives based on content shape — do not invent named "S01/S02/S03" templates and force pages into them.

Core Workflow

0. Verify dependencies are ready:

   python3 -c "import PIL" 2>/dev/null || echo "ERROR: Pillow missing; stop and report dependency_setup_required"
   node -e "require('playwright')" 2>/dev/null || echo "ERROR: Playwright missing; stop and report dependency_setup_required"
   test -n "$OPENAI_API_KEY$ZENMUX_API_KEY" || echo "INFO: use the host image tool or configure your own image API before generation"
   

   If a dependency is unavailable, report it and stop before generating images.

1. Read the source and verify unstable facts when necessary.

2. Split the source into content_source and publish_metadata before storyboarding. Lines under 标签: / Tags: / Hashtags: and standalone hashtag lines such as #AI学习 #TTS are publish metadata only. They must not become page messages, cover text, footer text, illustration labels, captions, or generated-image prompt text.

3. Build a beginner explanation brief using references/beginner-explanation.md. Do not begin layout work until the concept can be explained without jargon.

4. Create storyboard.yaml before designing. Give each page one message and one visual role. Keep user-provided hashtags under source_tags, outside pages.

5. For recurring AI knowledge series, make page 1 a fixed series-cover: series line, English term, Chinese explanation, and one user-scenario question. Do not generate a cover illustration unless the user explicitly asks.

6. Add a page-rhythm plan before coding: first list the source's natural message units and resulting page count, then list each content page's silhouette and evidence type. Use varied silhouettes after the cover; in longer sets, avoid repeating the same page shape back to back.

7. Route each content page using references/visual-routing.md.

8. The cover (page 1) uses the fixed S00 layout in references/layouts.md. For pages 2 onwards, do NOT pick a pre-named recipe — read references/layouts.md to choose a layout pattern based on the content shape, and compose the page fresh from primitives.

9. For every illustration-led page, define image_slot before writing any image prompt. The slot must state the final HTML wrapper, slot dimensions, slot ratio, generator aspect ratio, expected output canvas, and subject bounding box. Use references/illustration-prompts.md as the slot registry.

10. Use labeled-gpt-image for every generated illustration. Every illustration must carry a small set of high-value labels rendered directly by the image model.

11. Write a compact GPT Image 2 prompt derived from image_slot, with only the short in-image labels needed to explain the picture and no duplicate card title. Never include source_tags or any text beginning with #.

12. Choose one image route for the task. Do not silently switch routes after generation begins.

For a host image tool such as Codex imagegen, pass it the exact prompt, save the returned PNG at the storyboard output path, then record deterministic provenance without inventing provider usage:

python3 <skill-dir>/scripts/generate-illustration.py \
  --import-tool-image \
  --prompt-file prompts/page-02.md \
  --output assets/page-02.png \
  --orientation landscape \
  --size 1536x1024 \
  --quality high \
  --provider codex-imagegen \
  --model host-managed-imagegen

For the user's own OpenAI-compatible image API, configure OPENAI_API_KEY, OPENAI_BASE_URL, and OPENAI_IMAGE_MODEL, then run the same script without --import-tool-image:

python3 <skill-dir>/scripts/generate-illustration.py \
  --prompt-file prompts/page-02.md \
  --output assets/page-02.png \
  --orientation landscape \
  --size 1536x1024 \
  --quality high

13. Keep default paper-background normalization and conservative auto-frame. Use --remove-background only for isolated cutouts, --skip-background-normalize only for intentional scene backgrounds, and --no-auto-frame only when large blank space is deliberate. The API route preserves provider usage when the endpoint returns it. Require usage sidecars only when exact API accounting is part of the task.

14. Copy assets/template.html into the task directory as index.html. The template is an Editorial seed (Indigo Porcelain default) with serif display fonts, IKB Blue as the visible system color, and ONE fixed layout: the S00 Series Cover. Switch data-accent on <html> to change palette (indigo-porcelain | lemon-yellow | lemon-green | safety-orange). The alt accents collapse to single-color (no separate highlight) — only Indigo Porcelain carries the cover-bar yellow.

15. Keep the cover (S00) structure verbatim, replacing only the placeholders. For content pages, copy a named snippet from the bottom of assets/template.html as your starting point and adjust:

    • P-METAPHOR — concept + large 540px illustration
    • P-LIST — numbered list with 200px thumb illustrations per row
    • P-COMPARE — two-column before/after with 240px illustrations
    • P-MECHANISM — vertical pipeline with 130px inline step icons
    • P-QUOTE — pull-quote + 420px supporting illustration
    • P-ACTION — closing self-check with 200px illustration + options

    Read references/layouts.md for which snippet maps to which content shape, and references/components.md for the full type scale. Two hard rules from the reference system: (a) "the larger, the lighter" — display weights are 500, never 700+; (b) body and lead are serif-zh, not sans. Most content pages should pair text + small illustration. Every major generated illustration must be placed as .evidence-figure containing .illust-frame, so it sits natively inside the card instead of floating, shrinking, or sticking to the top. Add task-scoped CSS in the page's <style> only when necessary — do NOT add it back into the seed.

16. Render:

node <skill-dir>/scripts/render.mjs <task-dir>

17. Validate before showing final results. After rendering, run the validator by default unless the user explicitly says "先别跑校验，只看效果" or asks for an intentionally rough visual draft:

node <skill-dir>/scripts/validate.mjs <task-dir>

Fix every FAIL before final delivery. WARN is advisory: report important WARNs briefly, but do not block delivery unless the visual issue is obvious.

18. Inspect the final PNGs. Run both image-only and full-page explanation checks, then check generated Chinese text accuracy, factual accuracy, readability, page rhythm, and series consistency. Confirm no publish hashtags or #... strings appear inside cards or generated images. Show the user the rendered PNGs only after validation and inspection, with absolute paths and a short note summarizing validator status.

Storyboard Contract

Create this shape before image generation:

topic: Token 是什么
audience: AI 初学者
beginner_brief:
  prior_knowledge: 会使用聊天类 AI,但不了解模型原理
  plain_definition: Token 是 AI 读取和生成文字时使用的小单位
  not_this: 它不一定等于一个汉字或一个单词
  why_it_matters: 它会影响费用、可处理内容长度和对话记忆
  concrete_example: 今天天气真好会被拆成若干小块处理
source_tags:
  - AI入门
  - ChatGPT
  - AI小白
pages:
  - id: 1
    message: Token 会影响 AI 怎么读文字、花多少钱、能记住多少上下文
    role: cover
    layout: series-cover
    cover:
      series_line: 每天吃透一个 AI 知识点
      english_term: Token
      chinese_explanation: 文字处理单位
      user_question: 为什么 AI 聊久了会忘记前面说过什么?
  - id: 2
    message: Token 是 AI 处理文字的单位
    role: concept
    visual_type: labeled-gpt-image
    metaphor: 一整句话被拆成积木块
    layout: annotated-canvas
    image_slot:
      html_wrapper: evidence-figure landscape
      slot_px: 904x603
      slot_ratio: 3:2
      generator_ar: 4:3
      generator_canvas: 1536x1024
      subject_bbox: x=120-1416,y=128-896
      fit: contain

Hard rules:

• Keep one core message per page.
• Treat user-provided labels/hashtags as source_tags, not content. Do not place source_tags into page messages, cover copy, footers, captions, image prompts, or generated in-image labels unless the user explicitly asks to design a hashtag page.
• Page 1 of a recurring AI concept series should use the fixed series-cover layout unless the user asks for another cover format.
• The cover must contain exactly four content units: series line, English technical term, Chinese explanation, and one scenario question.
• Cover typography must be rendered in HTML, not generated into an image.
• The cover's term-zh must be the Chinese explanation of term-en, not an English subtitle or slogan.
• A core message must be a complete sentence with a subject, mechanism, and consequence. A keyword is not a message.
• Introduce every necessary technical term with plain-language meaning on first appearance.
• For every abstract definition, include at least one concrete example and one "why it matters" consequence in the card set.
• State important boundaries or misconceptions. Avoid teaching an analogy as if it were the literal mechanism.
• Use HTML as the default expression. Use illustrations to explain, not decorate.
• Do not generate an illustration when a comparison, process, ledger, or number communicates better.
• Decide page count from the source content, not from a fixed template. First extract the source's natural message units; use one page per core message. Typical sets are 4-7 pages including the cover. Do not force content into 5 pages, and do not merge or delete necessary causal steps just to hit a target page count.
• Keep long explanations, caveats, prices, dates, and unstable facts out of generated images.
• In labeled-gpt-image mode, generated images may contain only short exact labels that make the picture self-explanatory.
• Never duplicate the outer HTML title inside the generated illustration. The illustration should explain the mechanism, while the outer card introduces the topic.
• Do not add top metadata/category/page labels by default. Use them only when the user requests an editorial issue system.
• Use enough illustrations to support the natural page count.
• Reserve composition safe zones before generating illustrations.
• Prefer concrete actions over static collections of objects.
• Illustration presence is not success. Every illustration-led page must visibly communicate a causal chain and pass both image-only and full-page explanation checks.
• Generated illustrations explain one decisive visual moment. HTML completes exact causal chains, labels, definitions, and caveats.
• Generate for the final image slot. Do not default every embedded illustration to 3:4.
• Decide the final image_slot before writing or running any image prompt. Do not generate first and then hunt for a slot that happens to fit.
• Match the generated image's physical canvas to the HTML slot before accepting it. Landscape GPT Image output is normally 1536x1024; use .evidence-figure.landscape or another near-3:2 slot by default so object-fit: contain does not shrink it inside a shallow wide band.
• Every generated illustration prompt must include both a percentage-based composition contract and a pixel margin contract for the actual output canvas.
• Place generated content-page illustrations inside .evidence-figure landscape|hero|wide|square|portrait|compact; do not use a naked .illust-frame for major illustrations.
• Reuse a textual style anchor across the series. Use the first approved illustration as a reference only when the active generator supports reference images; the default local OpenAI-compatible wrapper does not.
• When using GPT Image 2, visually inspect every generated Chinese label. Regenerate if any label is wrong, fuzzy, cramped, duplicated, or invented.

Required References

• Read references/visual-routing.md when deciding whether and how to illustrate a page.
• Read references/beginner-explanation.md before storyboarding or writing card copy.
• Read references/metaphor-library.md when translating abstract ideas into scenes.
• Read references/illustration-prompts.md before generating any illustration.
• Read references/design-system.md before editing the HTML template (typography, spacing, two-layer color logic).
• Read references/theme-presets.md when choosing an accent palette (default: Indigo Porcelain).
• Read references/background-systems.md only when setting up sparse-page backgrounds.
• Read references/layouts.md when selecting page structures (S00-S04).
• Read references/style-system.md for Editorial identity rules and anti-patterns.
• Read references/components.md for class names, emphasis patterns, and image containers.
• Read references/platform-specs.md to confirm the Xiaohongshu 1080×1440 dimension and safe zones.
• Read references/qa-checklist.md before delivery.

Task Directory

visual-cards/<slug>/
├── source.md
├── storyboard.yaml
├── prompts/
├── assets/
├── index.html
└── output/

Keep prompts and source files so the result can be revised and reproduced.