svg-slide-authoring
Canonical SVG slide authoring language for native PPTX decks. Closed element/attribute whitelist, px viewBox, #RRGGBB color spelling, per-page hand authoring with locked registry tokens. Use when: authoring or repairing slide pages for the co-work native PPTX deck capability, or deciding whether an SVG construct is canonical / compatible / invalid.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- svg-slide-authoring
- owner
- pm
- scope
- co-work
- status
- active
- version
- 1.5.1
- metadata
- { "type": "capability", "triggers": [ "author slide", "canonical svg", "pptx deck page", "slide svg page", "repair slide page" ] }
- description
- Canonical SVG slide authoring language for native PPTX decks. Closed element/attribute whitelist, px viewBox, #RRGGBB color spelling, per-page hand authoring with locked registry tokens. Use when: authoring or repairing slide pages for the co-work native PPTX deck capability, or deciding whether an SVG construct is canonical / compatible / invalid.
- last_reviewed
- 1794009600000
- prerequisites
- Python 3.10+, templates/co-work/scripts/deck/svg_check.py, document-style-registry.json (decks section)
03 SKILL.md 正文
🛠️ Skill: svg-slide-authoring
Context
The co-work deck capability compiles per-page SVG into natively editable
DrawingML PPTX (ppt-master-adapter.ts + the ppt-master chain since the
2026-11-06 rebase; Phase 2 moved the gate to python svg_check.py). The SVG a page uses is NOT arbitrary
browser SVG: it is project-canonical SVG — a closed language whose
element/attribute whitelist has exact DrawingML mappings. Three input states:
| State | Definition | Handling |
|---|---|---|
| Canonical | A whitelisted spelling listed below | Compiles clean, no warnings |
| Compatible | A documented alternative with one deterministic normalization | Non-blocking warning; the checker normalizes; never fed back into authoring prompts |
| Invalid | Anything with no mapping, ambiguous meaning, or a risk of invalid DrawingML | Blocking error; re-author the page |
When to Use
- Authoring slide pages for a PPTX deck (with
deck-builder) - Repairing pages that failed
svg_check.py - Deciding whether a construct is allowed before writing it
Canonical Language
Root
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" width="1280" height="720">
- viewBox in px; canvas from the registry
decks.canvas(default 1280×720, 16:9). - Root must carry
data-slide-role(one of the chosendeck_types.slide_roles, e.g.title,content,closing) anddata-page-number(1-based).
Element whitelist
| Family | Canonical form | Notes |
|---|---|---|
| Structure | g (top-level = logical content block) |
every top-level g requires data-block-id="bN" (unique, 1-based per page) |
| Text | text with explicit x, y, font-size, fill |
y is the baseline. font-family allowed (registry fonts only). font-weight="bold" / font-style="italic" allowed. Escape XML entities in text (&, <, >, ", '): a bare & (P&L, Q&A) aborts resvg preview rendering; the gate decodes entities before diffing, so either spelling passes since svg-check v1.5.0 — prefer the escaped one |
| Text runs | tspan with x + dy stacking |
dy-stacked tspans compile to paragraphs in one text body; a tspan repeating its line-start x (the wrap pattern) is canonical; tspans mixing different x values warn (W-TSPAN-X) |
| Text presentation | text-anchor="start|middle|end", letter-spacing (px number), text-decoration="underline|line-through|none" |
anchor/spacing/decoration compile to algn/spc/u·strike; dominant-baseline/alignment-baseline are unsupported (W-UNSUPPORTED-BASELINE) — pre-adjust y instead |
| Geometry | rect (+rx ≤ half of min side), circle, ellipse, line, polyline |
explicit numeric x/y/width/height or point lists — no percentages |
| Paths | path with absolute M L H V C Q Z commands only |
lowercase (relative) commands are compatible (normalized) |
| Images | image with x/y/width/height + preserveAspectRatio |
href to a local file under the deck's assets/ directory |
| Paint | fill, stroke, fill-opacity, stroke-opacity, opacity |
colors as uppercase #RRGGBB. NEVER rgba(), rgb(), hsl(), or lowercase hex (lowercase hex is compatible; the rest are invalid) |
| Gradients | linearGradient / radialGradient in defs, with stop children using stop-color (uppercase #RRGGBB) and stop-opacity |
reference via fill="url(#id)" |
| Transforms | transform="translate(tx[,ty])" on g; transform="translate(tx,ty) rotate(deg)" on leaf shapes |
scale is compatible (warning: pre-scale the geometry instead); skew/matrices are invalid |
Prohibitions (invalid — blocking)
rgba()/rgb()/hsl()/ named colors (use#RRGGBB)- CSS
<style>blocks,class/styleattributes,!important <foreignObject>,<use>,<symbol>,<clipPath>,<mask>,<filter>(blur/shadow effects),<pattern>- Percent unit values (
width="50%"),em/remunits - Text content outside
<text>elements (e.g.<title>visible text is ignored, not rendered) - Nested
<svg>
Locked tokens
Colors, fonts, and canvas come from templates/co-work/docs/document-style-registry.json → decks for the chosen deck style. Reference tokens by role (background/primary/accent/text/muted) — do not invent hues per run. Page-local accents are allowed (a tint of a locked token, or the accent used sparingly); a second recurring visual system is not — recurring identity requires a registry/brief update.
Authoring discipline
- One page per pass. Hand-author each page; never write a script that generates page SVGs. Visual continuity is sequential judgment against the locked tokens.
- Content SSOT. Slide text comes verbatim from
deck_content.md. The gate diffs text runs mechanically; additions/rewording block. Need different words? Send it upstream (content-writer/storyteller), not into the page. - Every slide needs one focal point — an oversized number, a chart-like geometry, a single bold statement. Everything else is subordinate (contrast, size, position).
- Comfortable density. One key message per page; trim or split rather than overpack; leave breathing room around text blocks.
- Contrast first.
textonbackground(dark-on-light) or inverted for divider/title pages; never mid-tone on mid-tone.
Composition Patterns (v2.0 practice)
Codified from the v2.0 deck rebuild (22 rebuilt pages + a 100-slide intent table,
Nov 2026). Worked references: the shipped deck's previews/ renders — cite them by
pattern name when judging or repairing a page; do not copy page assets into this
template.
Two-column default (content slides)
Content-role slides split the canvas: left text ≈55% (x ≈ 80–690) / right visual ≈45% (x ≈ 720–1200). The visual column carries the page's focal element (chart-like geometry, oversized stat, image block); the text column carries the headline and supporting lines. Documented exceptions:
| Exception | Composition |
|---|---|
title / agenda / divider / closing roles |
full-width composition — no text/visual split |
| data-hero | a single oversized stat owns the page; the supporting sentence stays subordinate |
| punchline band | full-width statement band; no competing elements on it |
native-table (data-native="table") |
table block takes full canvas width; text stacks above it |
Punchline band
Single-takeaway divider/takeaway pages render one short bold statement on a full-width band filled with a locked surface token (accent or primary). The band IS the focal point — nothing else competes on it.
Data-hook
An oversized stat (72px class) is the page focal point; the supporting sentence sits smaller and muted below/next to it. This is "every slide needs one focal point" (concept 3 above) made concrete for data pages.
Full-bleed background rect (new pages SHOULD)
Start every new page with a full-bleed background rect as its first block child:
<rect x="0" y="0" width="1280" height="720" fill="<background token>"/>. Pages
without one render a transparent backdrop in resvg previews (black in most viewers).
Legacy pages are exempt — the exported slide master carries white, so the PPTX is
never transparent; to preview legacy pages, use the pptx-export white-underlay
render procedure rather than editing the page.
Execution Steps
- Resolve tokens: read the registry
deckssection for the chosen deck type; write the locked values into the design brief once. - Author P01 fully (title page): role, canvas, one focal point, locked tokens.
- Early gate (rosters > 6): run
python3 templates/co-work/scripts/deck/svg_check.py --deck <dir> --content <deck_content.md> --stage early --jsonafter P01–P05; fix all blocking errors and selected warnings before continuing. - Author remaining pages one at a time — carry the method (hierarchy rhythm, spacing, block naming) from the sample pages.
- Final gate: same command with
--stage final; repair failures (max 2 rounds per page, then PM escalation).
Output Format
<NN>-<slug>.svgper page (e.g.01-title.svg), zero-padded, in the deck working directory- All passing
svg_check.pywith zero errors before export
Related Skills
svg-quality-gate— validates what this skill authors; its severity model is the contract for repair roundspptx-export— consumes the gate-passed pages this skill producessvg-quality-gateandpptx-exportshare the same canonical language defined here
References
- Spec:
docs/designs/2026-11-03-co-work-native-pptx-deck-design.md(§4 canonical spec, §3 pipeline) - Hardening spec:
docs/designs/2026-11-06-deck-pipeline-hardening-design.md(entity decode D1, composition patterns D5, full-bleed background guidance D3) - Registry:
templates/co-work/docs/document-style-registry.json(decks) - Gate:
svg-quality-gateskill; export:pptx-exportskill
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.