Preserve approved mockups with controlled adjustments and recolorable assets (0.9.4)
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
name: ppt-template-workflow
|
||||
description: Create and revise template-based editable PPTX decks, design page mockups and materials, reconstruct visual pages into native objects, and maintain portable source projects. Select one external template and theme at a time; includes its own native compiler and workflows without requiring another installed Skill.
|
||||
metadata:
|
||||
version: "0.9.3"
|
||||
version: "0.9.4"
|
||||
---
|
||||
|
||||
# PPT Template Workflow
|
||||
@@ -56,6 +56,10 @@ Read [authoring handoff](references/authoring-handoff.md) for shared page inputs
|
||||
|
||||
Once the user confirms a page mockup, [reconstruct it faithfully](references/visual-design.md#approved-mockup-fidelity). Preserve its content, figures, graphics and relationship-bearing shapes, including connectors and grouping boundaries. Make necessary quality repairs while retaining the accepted meaning, composition and relationships; do not silently simplify, omit elements or treat difficult objects as dispensable decoration.
|
||||
|
||||
For that approved reconstruction, [controlled content-area adjustments](references/visual-design.md#controlled-adjustments-for-approved-mockups) allow necessary font-size, fit and alignment repairs through project-owned shared styles/recipes. Preserve the approved relative positions, visualization forms, icon identities and text styling; this allowance is not permission to redesign them. Prefer integers or consistent fixed-step values in explicit units; retain fixed page UI and locked structures. After each such adjustment, check overflow inside text frames/containers and beyond the page, including actual glyphs, formulas, strokes, clipping and occlusion. Repair source, rebuild and inspect the new render before completion.
|
||||
|
||||
When an approved element is impractical to express faithfully with native components or SVG, [use ImageGen for that element](references/visual-design.md#elements-that-need-imagegen), with the approved sample as reference. Preserve its appearance and relationships. Deliver generated material with a transparent background and one color or a few clearly separated color roles, retaining alpha masks/layers and declared adjustable/fixed bindings for reliable recoloring. Keep it as an independent project asset and disclose its picture editability. Do not replace it with a simpler visualization/icon or flatten the whole page. Exact evidence/identity originals remain authoritative.
|
||||
|
||||
For data graphics read [charts](references/charts.md); for native tables, metrics, timelines and explicit linear flows read [components](references/components.md). Their generators return data-bound component groups to compose inside an existing template slot, retaining its UI/Master/Layout. Keep sources and synchronize native payloads and visible fallback. New icons follow [icon production](references/icon-production.md) regardless of whether drawn, generated or externally sourced.
|
||||
|
||||
Apply the [visual design boundary](references/visual-design.md#page-composition-and-html-boundary) to every route: do not lay out report pages with HTML/DOM/CSS or convert such layouts through screenshots, printing or other formats. HTML may host a JavaScript visualization itself and its necessary runtime container; surrounding page text and layout use the permitted native/SVG route.
|
||||
|
||||
+10
@@ -1,5 +1,15 @@
|
||||
# 版本变化
|
||||
|
||||
## 0.9.4
|
||||
|
||||
为已确认小样的忠实复刻增加C27：允许通过工程共享样式／版式作必要的内容区字号、文本框／容器尺寸、间距、适配与对齐调整，不机械沿用模板全部预设数值。C25同步明确原则上保留元素相对位置关系、可视化形式、图标及文字样式，字号调整保持原有层次，不将微调解释成重新设计。主动设计参数优先取整数，细调时按参数类型和明确单位采用统一固定步长；计算得到的等比分布、缩放、单位换算、字体度量和曲线路径保留必要精度，证据数值不受取整规则影响。
|
||||
|
||||
每次字号或几何调整后必须检查两个层次的溢出：内容相对文本框／容器，完整可见对象相对可用正文区／页面；覆盖实际字形、公式、箭头、描边、裁切、遮挡及固定UI碰撞，修复源、重建并查看当前画面。模板默认字号／几何和固定间距的绝对表述已同步加入适用条件；固定页面UI、字体族和锁定结构保持，共享调整统一应用于同类元素，内容调用者仍无单实例内部偏移权限。
|
||||
|
||||
新增C28：原生组件或SVG不便忠实表示的已确认元素，使用ImageGen参照小样制作独立素材，保留可视化／图标／样式和关系，不简化替换或整页扁平化。生成图片交付真实透明背景、单色或少量简单颜色，保留alpha／分区遮罩、语义颜色映射及实际调色证据，支持保持轮廓、透明度和固定色的调色。保留真实证据及标识原件，如实披露图片可编辑性；可调色图片与可复用SVG图标的paint接口分开，不新增自动PNG调色接口。
|
||||
|
||||
本版只修订制作规则、入口及相关说明，不增加自动style-overlay接口或新审批流程，现有工具的支持范围和容量校验保持。生产脚本、编译器、数学、模板、结构Skill、依赖和旧发行包保持；发布与受管安装另行进行。
|
||||
|
||||
## 0.9.3
|
||||
|
||||
本地源码补充三项强制要求（C24—C26）：用户要求使用本Skill时必须用工程工具创建可构建项目或继续有效工程，单页任务同样适用，最终PPTX经真实工程入口构建，禁止手拼或给成品补空工程；用户确认小样后尽量忠实重建，必要质量修复保留其内容、图形及关系形状，不擅自删减；每页完成后从整页字号、字体、字重、间距与内容视觉分组检查层次，修复源、重建并查看当前画面。
|
||||
|
||||
@@ -5,9 +5,17 @@
|
||||
使用本Skill制作时，以下三项为必做要求：
|
||||
|
||||
1. 必须用Skill工程工具创建可构建项目，或继续已有有效工程；单页任务也适用。保留真实构建入口和输入，交付PPTX须通过工程构建生成，禁止绕过Skill手拼PPT或给成品补空工程。
|
||||
2. 用户确认小样后尽量忠实重建，保留其内容、图形及表示关系的形状，包括连线、箭头和分组边界。修复排版与可读性问题时不得擅自删减这些元素。
|
||||
2. 用户确认小样后尽量忠实重建，保留其内容、图形及表示关系的形状，包括连线、箭头和分组边界。原则上保留已确定的元素相对位置关系、可视化形式、图标及文字样式；必要排版修复不授权删减、换图标、换表现形式或重新设计。
|
||||
3. 每页完成后检查全页字号、字体、字重、间距和内容视觉分组的组合效果，确认层次清楚；发现问题后修复源、重建并查看当前画面，不以“不溢出”代替层次检查。
|
||||
|
||||
为忠实复刻已确认小样，允许作必要的内容区字号、文本框／容器尺寸、间距、适配与对齐调整，不必机械沿用模板全部预设数值。调整须保留上述相对位置关系、可视化、图标及文字样式，字号微调保持原有层次。主动设定的设计参数优先取整数；需要细调时，按参数类型和明确单位采用统一步长，如0.5pt或0.25pt，同类元素一致。等比缩放、单位换算、字体度量、曲线路径等计算结果保留必要精度。固定页面UI、已声明字体族和锁定结构继续遵守模板契约。
|
||||
|
||||
调整写入工程共享样式或版式，由真实builder消费并统一应用于同类实例。每次调整后，既检查文字、公式、图形是否超出文本框／内容容器，也检查完整对象及可见边缘是否超出可用正文区和页面、与固定UI碰撞或发生裁切／遮挡；修复源、重建并查看当前整页画面。见[小样调整与溢出检查](references/visual-design.md#controlled-adjustments-for-approved-mockups)。
|
||||
|
||||
原生组件或SVG不便忠实表示的已确认元素，使用[ImageGen制作独立素材](references/visual-design.md#elements-that-need-imagegen)，以小样为参考保留原有外观、细节和关系表达，不能换成更简单的图示／图标。素材进入真实工程并如实标注图片可编辑性，其他可编辑对象保持分离；真实证据与标识使用原件，不让生成素材代替真实数据。
|
||||
|
||||
生成图片素材交付真实透明背景、单色或少量明确分区的简单颜色，以支持调色。单色保留alpha遮罩及颜色角色，多色保留语义分层／分区遮罩及可调色／固定色映射；调色保持轮廓、透明度、细节与固定色，并检查实际换色结果。素材、遮罩和映射随工程保留。图片可调色不等于图内对象可独立编辑；现有SVG调色工具不会自动给PNG调色，按实际实现的图片编辑或工程绑定交付。
|
||||
|
||||
具体见[工程接口](references/project-workspace.md)、[小样保真](references/visual-design.md#approved-mockup-fidelity)及[全页层次检查](references/visual-design.md#full-page-hierarchy-check)。
|
||||
|
||||
可以直接这样请求：
|
||||
@@ -78,7 +86,7 @@ Agent 读取导出的调色板、字体、网格、素材 paint 契约、结构
|
||||
|
||||
段落还须遵守标点避头尾；检查每一行，包括末行，禁止单字或被标点包围的单字独占一行。重新排整段文字来消除问题，保持完整内容、逻辑文本块和声明字号。纯文本可使用`paragraph_layout.py`配合实际字体测量；复杂文字与PowerPoint重新换行的结果仍按实际画面检查。
|
||||
|
||||
间距由template与共享recipe固定，调用者不传数字、阈值、偏移或临时变体。检查文字与边框、标题与正文、相邻内容和公式周围的固定关系，过窄与过宽均拒绝。多段文字用完整段落数组，段内行距与段间距分别控制；`text_block.py`读取固定padding与paragraph_gap并自动记录关系，`layout_spacing.py`按role精确核对。几何检查不能替代实际字形与画面审阅，见[固定间距](references/spacing.md)。
|
||||
间距由生效的共享recipe固定，默认取template数值；复刻已确认小样时可声明工程共享调整，同类实例统一使用。内容调用者仍不传数字、阈值、偏移或临时变体。检查文字与边框、标题与正文、相邻内容和公式周围的固定关系，过窄与过宽均拒绝。多段文字用完整段落数组，段内行距与段间距分别控制；`text_block.py`读取所传共享style的固定padding与paragraph_gap并自动记录关系，`layout_spacing.py`按role精确核对。现有工具支持的数值类型／模数保持；记录工程调整不会自动应用它，builder须实际消费。几何检查不能替代实际字形、容器／页面溢出与画面审阅，见[固定间距](references/spacing.md)。
|
||||
|
||||
含数学内容时读取[数学制作](references/mathematics.md)，声明专用数学字体。`math_component.py`与原生导出包装器支持结构化表达式的Office Math输出；字体、字号角色和颜色由template或显式工程样式提供。它不是通用LaTeX解析器；源SVG的线性兼容文字也不等于复杂公式预览。目标应用的渲染和实际公式编辑分别验证。
|
||||
|
||||
@@ -90,7 +98,7 @@ Agent 读取导出的调色板、字体、网格、素材 paint 契约、结构
|
||||
"$PPT_PYTHON" /path/to/project/tools/ppt_project.py build --project /path/to/project
|
||||
```
|
||||
|
||||
构建校验输入锁并生成当前PPTX，失败时保留旧产物；不要靠已有导出物或单独调用底层编译器绕过工程。原生页面保留 Master／Layout／占位符；图表保留数据缓存和内嵌工作簿，表格保留单元格。图标按 SVG＋paint 的 palette／fixed／structural 通道处理。图表和表格示例位于 `assets/components/`，用法见[图表](references/charts.md)和[基础组件](references/components.md)。
|
||||
构建校验输入锁并生成当前PPTX，失败时保留旧产物；不要靠已有导出物或单独调用底层编译器绕过工程。原生页面保留 Master／Layout／占位符；图表保留数据缓存和内嵌工作簿，表格保留单元格。可复用调色图标按 SVG＋paint 的 palette／fixed／structural 通道处理；C28的小样复刻图片例外按独立工程素材保留并披露，不冒充可调色图标。图表和表格示例位于 `assets/components/`，用法见[图表](references/charts.md)和[基础组件](references/components.md)。
|
||||
|
||||
## 工程和协作
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Native formulas, tables and charts need their own object checks. Bitmap or SVG f
|
||||
|
||||
This package carries no template, theme or global style library. Installation and source synchronization belong to the installation owner.
|
||||
|
||||
A theme switch changes only declared palette and asset properties. Shared canvas, typography, geometry, layout/slot identities and content meaning remain fixed unless the template explicitly defines an exception. Rebuild and inspect affected pages after a switch. Recompilation sets the PowerPoint theme palette; it does not retroactively recolor undeclared source literals.
|
||||
A theme switch changes only declared palette and asset properties. Preserve the active shared canvas, typography and geometry, including any [C27 project adjustments](visual-design.md#controlled-adjustments-for-approved-mockups), along with layout/slot identities and content meaning, unless the template explicitly defines a theme exception. The theme switch itself does not authorize new geometry changes. Rebuild and inspect affected pages after a switch. Recompilation sets the PowerPoint theme palette; it does not retroactively recolor undeclared source literals.
|
||||
|
||||
For a template with chapter/subsection agendas, use its declared generator and data contract. A single overview may expand all subsections or collapse them all. Repeated agendas precede chapter and subsection entries, expand only the chapter being entered, and highlight the actual target through stable parent/child IDs. Preserve chapters without children. Bind any generated insertion plan to the report's real page order; co-located chapter/first-subsection entries need one agenda rather than consecutive duplicates. Reuse the template's fixed typography and whole-chapter column recipe; report capacity failures without dropping children, shrinking text or silently turning a single overview into multiple pages.
|
||||
|
||||
|
||||
@@ -27,6 +27,8 @@ A user's later change affects the stated scope; revise the same arrangement and
|
||||
|
||||
The mandatory project build, approved-sample fidelity and full-page hierarchy checks apply regardless of whether specialist review is selected. Every page must be retained in its buildable project, reconstructed without unauthorized element loss and checked as a whole for sizes, families, weights, spacing and visual grouping. These are production requirements, not an additional review assignment or approval round; follow [mockup fidelity and page checks](visual-design.md#approved-mockup-fidelity).
|
||||
|
||||
For approved-mockup reconstruction using [controlled content-area adjustments](visual-design.md#controlled-adjustments-for-approved-mockups), include the consumed shared project style/recipe, its units/steps and affected scope in the existing inputs. Check both container and page overflow after each adjustment, including the current rendered text/formula extents, clipping and occlusion. These checks follow the same agreed assignment; a numerical adjustment alone does not require another approval round.
|
||||
|
||||
By default, the agreed post-revision review uses a fresh-context Agent who did not participate in editing that portion. Reuse the once-confirmed assignment and budget. If the user explicitly selected main-Agent checking or skipped this review, follow and label that choice; do not describe it as independent review.
|
||||
|
||||
Provide current deliverable source and preview as relevant, confirmed report/section/page goals, audience knowledge, criteria, original evidence and sufficient prior content to verify dependencies. Include precise premises, symbol meanings, conditions and source locations needed for the current use. Do not make the reviewer assume a preceding block has already explained them. A missing item in the review input is not proof that the whole report lacks it; allow source lookup, and distinguish missing evidence from an input gap.
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
|
||||
Use suitable template icons first. For new icons, prefer directly authored SVG/native shapes for simple forms, ImageGen for complex imagery, and external ready icons as a supplement. Choose a recognizable information meaning and keep stroke weight, corners, perspective, optical scale and detail consistent at the intended size. An icon should remain understandable without nearby explanatory prose, or deliberately reuse the same established icon as its counterpart.
|
||||
|
||||
For an approved mockup, preserve the accepted icon identity and styling rather than substituting a different icon from that priority list. If native components/SVG are impractical for faithful reproduction, [C28 requires ImageGen](visual-design.md#elements-that-need-imagegen) for the element. Deliver the project-local picture with a transparent background and one color or a few simple semantic colors, retaining alpha masks/layers, adjustable/fixed palette bindings and actual recoloring evidence. Keep its reference, generation provenance and usable asset in the project. It remains a disclosed picture with color adjustability, not editable internal geometry or an SVG paint-contract icon. The reusable SVG contract below still applies before publishing it as that template/library icon type or using the paint helper.
|
||||
|
||||
## One deliverable contract for all sources
|
||||
|
||||
All routes must support approved whole or partial palette recoloring. Deliver original source, normalized SVG, a paint contract, palette bindings, provenance and preview evidence together. Use stable IDs for semantic parts, explicit fill/stroke attributes and per-channel rules. `palette` permits a semantic token to bind an index; `fixed` preserves an exact literal; `structural` preserves `none`. Unlisted channels preserve their source paint. Shared tokens express shared roles; separate tokens permit independent colors.
|
||||
For reusable adjustable icons, all routes must support approved whole or partial palette recoloring. Deliver original source, normalized SVG, a paint contract, palette bindings, provenance and preview evidence together. Use stable IDs for semantic parts, explicit fill/stroke attributes and per-channel rules. `palette` permits a semantic token to bind an index; `fixed` preserves an exact literal; `structural` preserves `none`. Unlisted channels preserve their source paint. Shared tokens express shared roles; separate tokens permit independent colors.
|
||||
|
||||
Whole-icon coloring means binding every intended adjustable part to one palette index. It never means replacing every matching color in a bitmap. Keep fixed details, white details, opacity, holes, masks, geometry and paint order intact. Validate IDs, explicit source paint, duplicate/missing bindings and palette indices. See [the exact schema](template-interface.md#svg-paint-contract).
|
||||
|
||||
@@ -14,7 +16,7 @@ Keep an exact official mark or evidence image as its original asset when that is
|
||||
|
||||
## Project-local icons
|
||||
|
||||
Keep new materials under the caller's project, outside a locked template snapshot. A local material descriptor contains `schema_version: 1`, `id`, project-relative `path` and `paint_contract`, and a `bindings` array of `{selector, channel, palette_index}`. Paths resolve beside the descriptor. The bindings must cover exactly the contract's palette pairs, and at least one pair must be adjustable. This lets an author add an icon without publishing a new template or modifying vendor files.
|
||||
Keep new materials under the caller's project, outside a locked template snapshot. For an SVG icon consumed by the paint helper, a local material descriptor contains `schema_version: 1`, `id`, project-relative `path` and `paint_contract`, and a `bindings` array of `{selector, channel, palette_index}`. Paths resolve beside the descriptor. The bindings must cover exactly the contract's palette pairs, and at least one pair must be adjustable. This lets an author add an SVG icon without publishing a new template or modifying vendor files. C28 bitmap materials retain their alpha/semantic masks and verified recoloring inputs separately; this SVG descriptor and `--material` route do not automatically support PNG recoloring.
|
||||
|
||||
```sh
|
||||
python /path/to/skill/scripts/paint_asset.py \
|
||||
|
||||
@@ -6,13 +6,13 @@ Create or continue the [mandatory buildable Skill project](project-workspace.md)
|
||||
|
||||
Start the current page from its selected layout source. Retain inheritance metadata, inherited objects and placeholder indices. Fill the declared placeholder carrier; put independent content objects in the intended slide layer. Do not paint opaque slide-local copies over the master logo or layout watermarks. When a template supplies a custom composition generator, inspect it and use its declared content interface rather than approximating its source geometry.
|
||||
|
||||
Use the template's discrete typography, grid, fixed content region and spacing. Resolve overflow by choosing a suitable layout, or by shortening content/dividing the page within the user's authorized content scope. For an approved mockup, preserve its content, graphics and relationship-bearing shapes under [mockup fidelity](visual-design.md#approved-mockup-fidelity); necessary quality repair does not permit silently dropping elements. Do not infer ad hoc font sizes and alignment guides from mockup pixels. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. Tables, charts and formulas must retain their required native object type; a collection of lines/text or a formula picture does not automatically qualify.
|
||||
Start with the template's typography, grid, fixed content region and spacing. For an approved mockup, use [controlled content-area adjustments](visual-design.md#controlled-adjustments-for-approved-mockups) to font sizes, bounds, spacing and necessary fit/alignment, with declared shared project values in integer/fixed-step units. Preserve fixed UI, locked structures, accepted relative positions, visualization forms, icons and text styling under [mockup fidelity](visual-design.md#approved-mockup-fidelity). Resolve remaining overflow through reflow or an authorized layout/content change; necessary quality repair does not permit silently dropping or redesigning elements. Do not trace raster artifacts or introduce unexplained multi-digit offsets. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. For an element that native components/SVG cannot conveniently reproduce faithfully, use [ImageGen](visual-design.md#elements-that-need-imagegen) and disclose its independent picture type. Tables, charts and formulas must retain any explicitly required native object type; a collection of lines/text or a formula picture does not automatically qualify.
|
||||
|
||||
Apply [text and container rules](text-and-containers.md) before authoring: prefer one native frame per paragraph, use a unified logical block for any necessary fragments, distinguish text functions by size/weight/color and instantiate repeated containers through a shared renderer. Inspect actual native paragraph structure after export; positional SVG spans can otherwise be split by the compiler.
|
||||
|
||||
Before emitting paragraph rows, check punctuation at both line edges and prohibit every singleton row, including one character surrounded by punctuation. Reflow the complete paragraph with measured text widths; keep derived rows inside the same native frame. Repeat the check against actual rendered lines if PowerPoint performs further wrapping.
|
||||
|
||||
Keep separate paragraphs separated by the template's fixed paragraph gap, retaining their normal internal line height. Spacing values and applicable relationships belong to the shared recipe; content callers cannot adjust them. Check exact fixed padding/gaps and actual glyph/edge clearance at normal scale. Use [text-block/spacing helpers](text-and-containers.md#spacing-and-paragraph-separation) for supported content. Explicit math markers use the [Office Math wrapper](mathematics.md), not the upstream table/chart marker kinds.
|
||||
Keep separate paragraphs separated by the active shared recipe's fixed paragraph gap, retaining their normal internal line height. Use template defaults or the declared project adjustment above. Spacing values and applicable relationships belong to the shared recipe; content callers cannot adjust them. Check exact fixed padding/gaps and actual glyph/edge clearance at normal scale. Use [text-block/spacing helpers](text-and-containers.md#spacing-and-paragraph-separation) for supported content. Explicit math markers use the [Office Math wrapper](mathematics.md), not the upstream table/chart marker kinds.
|
||||
|
||||
## Current-page project build
|
||||
|
||||
@@ -36,6 +36,8 @@ The exporter embeds images in temporary source copies, preserving canonical sour
|
||||
|
||||
Before marking each page complete, perform the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check) on its current render, covering font sizes/families/weights, spacing and visual content groups across the entire page. Compare with any approved sample, repair the source and rebuild/reinspect as needed; a successful compile is not this visual check.
|
||||
|
||||
After any approved-mockup typography or geometry adjustment, also check [container and page overflow](visual-design.md#controlled-adjustments-for-approved-mockups): actual text/formula extents and paragraph height must fit their frames/containers, and complete visible groups must fit the usable page/canvas without unintended clipping, occlusion or collisions with fixed UI. Check the actual rebuilt render, repair source and repeat for affected shared instances.
|
||||
|
||||
## Template authors and review prototypes
|
||||
|
||||
Keep proposed styles and mockups outside the final template workspace until the user's design review allows formal construction. A proposal manifest cannot be consumed as a released production template. After approval, author the common style, independent themes, roster and native SVG layout definitions together; compare each theme against the same geometry and slot contract.
|
||||
|
||||
@@ -14,7 +14,9 @@ Keep exact supplied logos, figures and screenshots as independent source assets.
|
||||
|
||||
## Native reconstruction
|
||||
|
||||
Start from the selected template layout source, retaining its Master/Layout/placeholder metadata. Recreate normal text as native text with the external style's font family, discrete size, line spacing and alignment. Build simple panels, rules, arrows and diagram nodes as separate structural objects. Fit to the declared grid, not pixel-by-pixel ad hoc anchors.
|
||||
Start from the selected template layout source, retaining its Master/Layout/placeholder metadata. Recreate normal text as native text with the declared font family and active shared sizes, line spacing and alignment. For an approved mockup, [controlled project adjustments](visual-design.md#controlled-adjustments-for-approved-mockups) allow necessary content-area size, bounds, spacing and fit/alignment repairs with explicit integer/fixed-step values. Preserve its relative spatial relationships, visualization forms, icon identities and text styling, as well as fixed UI and locked structures. Build simple panels, rules, arrows and diagram nodes as separate structural objects. Use the declared template/project grid and shared roles, not pixel-by-pixel ad hoc anchors.
|
||||
|
||||
When native components or SVG are impractical for faithfully expressing an approved element, [use ImageGen for that element](visual-design.md#elements-that-need-imagegen) with the accepted reference, preserving its appearance, details and relationship cues. Keep it as a separate project asset and disclose the picture exception; do not swap its visualization/icon style, omit it or flatten the whole page. Exact evidence/identity originals retain their own source requirements.
|
||||
|
||||
Apply [text and container rules](text-and-containers.md) even when the reference image was built differently. Reconstruct a paragraph as one logical text block, preferably one native frame; do not turn each visible source line into an independently positioned box. Repeated container internals use one shared recipe. Essential explanations and limitations stay in the main information hierarchy, and different text functions need size/weight/color distinctions.
|
||||
|
||||
@@ -22,4 +24,4 @@ Use actual data for native charts; if source values are unavailable, preserve th
|
||||
|
||||
Preserve crop, aspect ratio and source meaning for image objects. Independently editable text over an unchanged full-page screenshot is not a reconstructed page. Keep repeated UI in inherited layers, rather than covering it with copied slide objects.
|
||||
|
||||
Build the current SVG through the project's declared builder using [native export](native-authoring.md), then compare the actual rendered page with the accepted design and element inventory at full size and a normal presentation view. Complete the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check), including all font sizes, families, weights, spacing and content groups. Check density, line breaks, safe margins, alignment, clipping, asset identity and reading order. Native object checks establish object type and inheritance; they do not prove appearance. Complete the requested application checks before claiming editability acceptance.
|
||||
Build the current SVG through the project's declared builder using [native export](native-authoring.md), then compare the actual rendered page with the accepted design and element inventory at full size and a normal presentation view. Complete the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check), including all font sizes, families, weights, spacing and content groups. After typography/geometry adjustments, complete both [container and page overflow checks](visual-design.md#controlled-adjustments-for-approved-mockups), including actual glyphs/formulas, strokes, clipping and occlusion; repair source, rebuild and inspect again. Check density, line breaks, safe margins, alignment, asset identity and reading order. Native object checks establish object type and inheritance; they do not prove appearance. Complete the requested application checks before claiming editability acceptance.
|
||||
|
||||
@@ -29,7 +29,7 @@ For separate worktrees/devices, return an assigned source diff or directory arch
|
||||
|
||||
Deliver source/content/notes, private assets and a packet recording ID, owner, revision, baseline hashes, layout, purpose, origin, source/asset hashes, preview renderer/hash, native objects, picture exceptions and unresolved issues. State source/static, native structure, SVG render, actual PowerPoint render, editing and projection individually; unavailable checks stay `not-run` with a reason. A PNG does not prove editability. Ready means ready for integration review.
|
||||
|
||||
Source, content and notes must agree. Update table/chart metadata with data; preserve evidence labels, numbers, units, necessary premises and key steps. Check actual reading order and the visual association between conclusions and evidence. Match fonts, grid, fixed body area and palette; remove placeholders/example text. Keep resources within the assigned page directory.
|
||||
Source, content and notes must agree. Update table/chart metadata with data; preserve evidence labels, numbers, units, necessary premises and key steps. Check actual reading order and the visual association between conclusions and evidence. Match declared fonts, active shared grid/styles, fixed body area and palette, including any scoped [C27 approved-mockup adjustments](visual-design.md#controlled-adjustments-for-approved-mockups); remove placeholders/example text. Typography/geometry adjustments require both container and page overflow review on the current render. Keep resources within the assigned page directory; the assigned shared-resource writer integrates shared recipe changes before affected pages are rebuilt.
|
||||
|
||||
## Integrate and revise
|
||||
|
||||
|
||||
@@ -8,12 +8,14 @@ Use the current output of the mandatory [project build](project-workspace.md). P
|
||||
|
||||
For rendered evidence, export this file to PDF through PowerPoint's own export dialog using the intended quality setting and a task-owned destination. Check the export exists and belongs to the current file, render its pages and inspect the images. Compare page geometry, text wrapping, typography, images, transparent edges, alignment and separators. Confirm actual PDF font identities when font rendering is disputed; a declared PowerPoint face alone does not prove which font the application rendered.
|
||||
|
||||
Use the [text/container review](text-and-containers.md#review-before-delivery): paragraph frame or justified logical-block fallback, no substantive statements in small muted notes, visible size/weight/color hierarchy within containers, one shared internal layout implementation per type/variant, compliant punctuation/singleton handling on every paragraph line, exact template-owned spacing and visible fixed paragraph gaps. Reject caller spacing overrides. Check actual glyphs/edges and visual rows, not only boxes, authored breaks or XML paragraphs. Review content/source and native objects as well as the render. A screenshot cannot prove a shared renderer or unified text source; grouping cannot prove native paragraph flow. Test fragment reflow in the application only when that editing behavior is part of the requested evidence.
|
||||
Use the [text/container review](text-and-containers.md#review-before-delivery): paragraph frame or justified logical-block fallback, no substantive statements in small muted notes, visible size/weight/color hierarchy within containers, one shared internal layout implementation per type/variant, compliant punctuation/singleton handling on every paragraph line, exact active shared spacing and visible fixed paragraph gaps. The active recipe may contain C27's declared project-owned content-area adjustments for an approved mockup; reject caller spacing overrides. Check actual glyphs/edges and visual rows, not only boxes, authored breaks or XML paragraphs. Review content/source and native objects as well as the render. A screenshot cannot prove a shared renderer or unified text source; grouping cannot prove native paragraph flow. Test fragment reflow in the application only when that editing behavior is part of the requested evidence.
|
||||
|
||||
For equations, inspect `mc:Choice/a14:m` and OMML structures separately from compatibility fallback text. Verify the declared math family on runs and operator/control properties, missing glyphs, fraction/radical/script/limit placement and clearance from adjacent prose. Actual equation editing requires selecting and changing the equation in a disposable copy; XML or a correctly shaped picture cannot establish that evidence. See [math checks](mathematics.md#verification).
|
||||
|
||||
Every completed page also requires the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check): sizes, families, weights, spacing and visual grouping across the whole rendered page. Component checks, a successful export or absence of overlap do not replace it. Repair issues and inspect the updated render; report application/projection evidence at its actual level.
|
||||
|
||||
After each approved-mockup font-size or geometry adjustment, complete both [container and page overflow checks](visual-design.md#controlled-adjustments-for-approved-mockups). Inspect actual text/formula layout and complete visible edges: content must fit its text frame/container, and the full composition must fit the usable page/canvas without unintended clipping, occlusion or fixed-UI collisions. Repair source, rebuild and inspect the current output; container boxes inside the canvas alone are insufficient. Preserve only explicitly intended template crops/contacts under their existing rules.
|
||||
|
||||
Opening and exporting are distinct from actual editing. When editing evidence is requested, use a disposable task-owned copy: select a representative text/shape/placeholder, change it through the UI, save or export, and verify the resulting independent object/content change. Check an appropriate inherited object separately if template behavior is in scope. Do not alter the authoritative source project or a user's finished original merely to demonstrate editing.
|
||||
|
||||
Report the evidence actually obtained: source/reference validation, native structure and object types, current-page rendering, PowerPoint opening, actual object editing, or projection readability. A successful export cannot establish every later level. If the host application or UI capability is unavailable, deliver the validated source and PPTX with that specific unresolved application check.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Production rules
|
||||
|
||||
These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C26 are requirements, including where C04–C06 offer broader design recommendations.
|
||||
These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C28 are requirements, including where C04–C06 offer broader design recommendations. C27 permits controlled content-area repairs for an approved mockup while preserving its relative positions, visualizations, icons and text styling; C28 provides ImageGen for elements that native/SVG representation cannot conveniently reproduce faithfully.
|
||||
|
||||
## Understand and compose
|
||||
|
||||
@@ -8,12 +8,12 @@ These rules apply across templates and authoring routes. **Required** rules prot
|
||||
- **C02 · Required:** preserve facts, numbers, conditions, causal relationships and strength of conclusions. Distinguish source statements, inference and added material. Do not invent unknown values. Identify synthetic examples and retain traceable sources for material claims.
|
||||
- **C03 · Required meaning and visual correspondence, recommended composition:** preserve the supplied page purpose, intended understanding, evidence and key steps. Every text, formula, label, visualization and meaningful decorative group serves the page, section and report goals. Make the association between each conclusion and its evidence visible, and check the actual page's progression and necessary context. Choose a suitable composition and reading order for those relationships; concrete layout methods may vary. Preserve demonstrated contributions and judgments without defaulting to limitations lists or preventive self-doubt. Do not silently change chapter order or move essential content to notes. Return meaningful omissions, contradictions or capacity conflicts to the content plan; do not create a parallel report-structure rule library. Summarize only within the authorized content scope and without changing meaning; C02 governs required content fidelity.
|
||||
- **C04 · Recommended:** keep hierarchy, color semantics, terminology, units, legends, strokes, icon grammar and component scale consistent across pages. Use declared template exceptions where needed.
|
||||
- **C05 · Recommended:** choose layout and columns from content relationships, then place components. Maintain grouping, alignment, spacing, reading order and moderate density. Add decoration for a purpose. Resolve excess content through the template's rewrite/layout/split policy; keep its declared typography and grid rules.
|
||||
- **C05 · Recommended:** choose layout and columns from content relationships, then place components. Maintain grouping, alignment, spacing, reading order and moderate density. Add decoration for a purpose. Resolve excess content within the authorized content scope through the template's rewrite/layout/split policy or C27's controlled approved-mockup adjustments; retain fixed UI and declared shared typography/grid rules, including the project's scoped adjustments.
|
||||
- **C06 · Recommended:** inspect suitable components and page-library examples before authoring. Read their rationale and method; adapt, combine or create as needed. Remove example content, update data and metadata, and preserve reference attribution.
|
||||
|
||||
## Materials and information graphics
|
||||
|
||||
- **C07 · Recommended priority, required paint contract:** reuse suitable template icons; draw new simple icons as SVG/native shapes; use ImageGen for complex icon imagery; use external ready icons as a supplement. Every route must finish with the selected icon production contract: stable semantic parts, permitted whole/partial palette binding, fixed details and transparent structure. Generated or external source material is not exempt. See [icon production](icon-production.md).
|
||||
- **C07 · Recommended priority, required paint contract for adjustable icons:** reuse suitable template icons; draw new simple icons as SVG/native shapes; use ImageGen for complex icon imagery; use external ready icons as a supplement. For an approved mockup preserve its icon identity under C25/C28 rather than substituting from this priority list. Reusable adjustable icons from every route must finish with the selected icon production contract: stable semantic parts, permitted whole/partial palette binding, fixed details and transparent structure. Generated or external source material is not exempt from that reusable contract; C28's disclosed project-local picture exception is a separate deliverable type. See [icon production](icon-production.md).
|
||||
- **C08 · Required truthfulness, recommended selection:** choose photos, evidence figures, illustrations and decoration by their information role. Use supplied/trustworthy originals for exact identity and real evidence. Identify generated material; do not present it as official marks, real scenes or experimental results. Keep originals, derivative/generation provenance and needed production inputs. Preserve proportions and critical evidence when cropping.
|
||||
- **C09 · Required data fidelity, recommended expression:** retain data, units, definitions, time range, missing-value policy and sources. Before drawing comparisons, check compatible objects, denominators/baselines, samples or workloads and statistical methods. Resolve differences with valid conversion, recalculation or comparable subsets where possible, retaining the basis. If they cannot be aligned, use separate views or a justified limited comparison and state the remaining scope; a difference label alone cannot justify a ranking. Select comparison, trend, distribution, composition or relationship views accordingly; normally avoid misleading truncation, meaningless dual axes and 3D ornament. Sources may live in notes/metadata; necessary conditions for interpreting the comparison remain visible. Do not introduce a forbidden footer. See [charts](charts.md) and [components](components.md).
|
||||
- **C10 · Required semantics, recommended implementation:** nodes, links, arrows, groups and legends represent actual relationships. Distinguish peers, classification/containment, comparison, time/process, cause, condition/dependency, reasoning, data flow and control flow as relevant. Adjacency, grouping, correlation or time order alone does not establish cause; an arrow must express an identified relationship. Prefer native objects/SVG for technical diagrams; preserve code symbols, indentation and necessary context. State the actual formula object type.
|
||||
@@ -36,8 +36,8 @@ These rules apply across templates and authoring routes. **Required** rules prot
|
||||
- **C18 · Required:** different text functions inside one container, such as subheading and body, must have a perceptible distinction in declared size, weight and/or palette color. A font-family change alone is insufficient. Bind functions to named text roles and apply the same distinction to all instances.
|
||||
- **C19 · Required:** every instance of a container type/variant uses the same shared layout implementation for padding, slots, text roles, wrapping, icon placement and alignment. Authors provide content and whole-container placement/bounds; the implementation computes internal geometry. Do not hand-position/nudge text or icons per instance. Resolve capacity through the shared layout's content-driven rules, a meaningful shared variant, rewriting or page/layout changes, never a one-off override. See [implementation and review](text-and-containers.md).
|
||||
- **C20 · Required:** paragraph lines obey punctuation rules for line starts and ends. Do not leave a line containing only one substantive character, whether alone, followed by punctuation, or surrounded by punctuation; this applies to every line, including the final line. Keep closing punctuation with preceding content and opening punctuation with following content; preserve unbreakable marks and words. Reflow the complete logical paragraph under its shared layout, then check the actual rendered lines. Do not fix this by deleting/changing content, splitting independent text boxes, or introducing undeclared font sizes, character spacing or per-line offsets. See [paragraph line breaking](text-and-containers.md#paragraph-line-breaking-rules).
|
||||
- **C21 · Required:** spacing is fixed by the template and shared component recipe for each relationship: text-to-container padding, heading-to-body distance, adjacent groups/columns and clearance around connectors, rules and formulas. Content callers cannot supply numeric gaps, thresholds, per-instance spacing overrides or invent variants. Check the declared fixed values, including unintended excess spacing, as well as collisions and actual glyph/edge clearance. Preserve intentional decorative contacts under their own template rules. Capacity changes must reflow content or change the whole supported layout, not loosen/tighten its spacing. See [fixed spacing](spacing.md).
|
||||
- **C22 · Required:** distinguish separate semantic paragraphs visually with the template's fixed paragraph spacing in addition to normal line spacing. Preserve paragraph boundaries in complete source content. The shared implementation owns this value; content callers cannot adjust it. Use native before/after paragraph spacing where the text-frame route supports it, or consistently positioned paragraph frames. Do not add empty paragraphs, repeated line breaks or per-instance offsets to simulate spacing. Reflowing a paragraph must preserve the fixed separation from the next paragraph.
|
||||
- **C21 · Required:** spacing is fixed by the template and shared component recipe for each relationship: text-to-container padding, heading-to-body distance, adjacent groups/columns and clearance around connectors, rules and formulas. For C27's approved-mockup reconstruction, the project may declare adjusted content-area values in its shared style/recipe; those become the fixed values for the affected type/variant and scope. Content callers cannot supply numeric gaps, thresholds, per-instance spacing overrides or invent variants. Check the active declared values, including unintended excess spacing, as well as collisions and actual glyph/edge clearance. Preserve intentional decorative contacts under their own template rules. Resolve capacity through reflow, supported whole-layout changes or C27's shared adjustment, with container/page overflow checks. See [fixed spacing](spacing.md).
|
||||
- **C22 · Required:** distinguish separate semantic paragraphs visually with the active shared recipe's fixed paragraph spacing in addition to normal line spacing. Use the template value by default or the project's declared adjustment under C27. Preserve paragraph boundaries in complete source content. The shared implementation owns this value; content callers cannot adjust it. Use native before/after paragraph spacing where the text-frame route supports it, or consistently positioned paragraph frames. Do not add empty paragraphs, repeated line breaks or per-instance offsets to simulate spacing. Reflowing a paragraph must preserve the fixed separation from the next paragraph.
|
||||
- **C23 · Required:** mathematical content uses an explicitly declared mathematical font and preserves symbols, operators, scripts, fractions and grouping. Keep ordinary prose in its own text role. Use native Office Math when native equations are required; ordinary Unicode text, linear compatibility text and formula images are different object types. Verify the declared math font and the actual equation structure/rendering; do not silently substitute the prose font or claim equation editability from its appearance. See [mathematics](mathematics.md).
|
||||
|
||||
Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not infer paragraph identity, explanation importance or semantic text roles, and do not automatically enforce every text/container rule across arbitrary source files. The paragraph helper checks the lines supplied to it and reflows supported plain text; it does not intercept arbitrary SVG or PowerPoint reflow. Inspect source and current native/rendered output; export success alone is insufficient.
|
||||
@@ -45,5 +45,7 @@ Technical helpers enforce supported inputs, path safety, object consistency and
|
||||
## Buildable project, approved mockups and full-page hierarchy
|
||||
|
||||
- **C24 · Required:** when the user requests this Skill, create a buildable project with its project tools, or continue a valid existing Skill project. This includes one-slide requests and revisions, regardless of whether Git collaboration or relocation is requested. Retain the real builder, selected template/compiler, sources, content, data, assets, notes and environment; generate the delivered PPTX through the declared project build. Do not bypass the Skill with a one-off PPTX packager, manually stitch XML/ZIP or assemble the final deck by hand and backfill a nominal project. An empty skeleton, cached export or metadata-only check is insufficient: the current authorized page set must build successfully from its inputs. See [project workspace](project-workspace.md).
|
||||
- **C25 · Required:** after the user confirms a mockup, reconstruct it as faithfully as possible, including its content, figures, graphics, grouping and relationship-bearing shapes. Preserve nodes, connectors, arrows, braces, enclosures, labels and other accepted elements; do not silently omit or simplify them because they are difficult to rebuild or seem expendable. Make necessary quality repairs to typography, wrapping, spacing, alignment, contrast, clipping and collisions while retaining the accepted content, composition and relationship semantics. A removal or substantive change needs the user's instruction; do not treat general quality repair as permission to reduce the sample. See [approved-mockup fidelity](visual-design.md#approved-mockup-fidelity).
|
||||
- **C25 · Required:** after the user confirms a mockup, reconstruct it as faithfully as possible, including its content, figures, graphics, grouping and relationship-bearing shapes. Preserve nodes, connectors, arrows, braces, enclosures, labels and other accepted elements; do not silently omit or simplify them because they are difficult to rebuild or seem expendable. As a rule, retain the accepted elements' relative spatial relationships, visualization forms, icon identities and text styling, including family intent, weight, color, emphasis, alignment and relative size hierarchy. Make necessary quality repairs to typography, wrapping, spacing, alignment, contrast, clipping and collisions while retaining that design and its relationship semantics. A removal, restyling or substantive rearrangement needs the user's instruction; ordinary fit repair under C27 does not authorize it. See [approved-mockup fidelity](visual-design.md#approved-mockup-fidelity).
|
||||
- **C26 · Required:** after every page is completed, inspect the entire current rendered page for hierarchy from font size, font family, font weight, spacing and visual content grouping. Cover all text roles and the relationships across containers, not just isolated boxes. Confirm that the main message, sections, body and supporting detail are distinguishable and groups reflect the intended meaning. Repair failures and re-render before reporting the page complete. No clipping/overlap, a successful compile or a few differently styled objects alone does not establish hierarchy. See [full-page hierarchy check](visual-design.md#full-page-hierarchy-check).
|
||||
- **C27 · Required:** to faithfully reconstruct an approved mockup, content-area font sizes, text/container dimensions, spacing and necessary fit/alignment adjustments may depart from the template's preset numbers through declared project-owned shared styles/recipes. Preserve C25's relative spatial relationships, visualizations, icons and text styling; retain fixed page UI and explicitly locked structures. Font-size changes must preserve readable roles and the accepted relative hierarchy. Prefer integer design parameters; when finer adjustment is useful, use consistent fixed steps in explicit units for each parameter class. Preserve necessary precision for derived scaling, unit conversion, font metrics and curve geometry. Apply shared changes consistently to repeated elements; do not round evidence values or invent per-instance overrides. After each adjustment, check text/content against its frame and container, then every visible object against the usable page and canvas, including actual glyphs/formulas, strokes, clipping and occlusion. Repair source and rebuild/reinspect the current render; passing box or build checks alone is insufficient. See [controlled adjustments and overflow](visual-design.md#controlled-adjustments-for-approved-mockups).
|
||||
- **C28 · Required:** when an accepted element is impractical or cumbersome to express faithfully with native components or SVG, use the host ImageGen capability for that element, conditioned on the approved reference and preserving its visualization, icon/style identity and relationships. Deliver generated picture material with a transparent background and one color or a few clearly separated color roles. Retain the alpha mask or semantic layers/masks, adjustable/fixed color mapping, original and consumed asset, reference/prompt/provenance, and verify actual recoloring preserves structure and transparency. Keep other editable elements separate and disclose the picture exception; recolorability does not imply editable internal geometry. Do not simplify the accepted element, replace it with an unrelated symbol or flatten the entire page. Exact supplied identity/evidence assets and real data remain authoritative; generated material cannot invent or replace them. Follow explicit current user tool choices and report unavailable capabilities rather than silently dropping the element. See [ImageGen element reconstruction](visual-design.md#elements-that-need-imagegen).
|
||||
|
||||
@@ -6,6 +6,8 @@
|
||||
|
||||
用户要求使用本Skill时，必须使用本工程工具创建可构建项目，或继续使用已有的有效工程；单页、小样重建和修改任务也适用，不以需要Git协作或跨设备迁移为前提。选定template／theme后先初始化工程，再在其中维护页面源和真实builder。禁止绕过Skill编译器手拼PPT、临时拼接PPTX／XML／ZIP，或给已手拼的成品补一个空工程。交付PPTX必须由声明的工程入口从当前输入成功构建，并保留对应工程。
|
||||
|
||||
复刻已确认小样时，可按[C27](visual-design.md#controlled-adjustments-for-approved-mockups)在工程自有共享样式／版式中调整内容区字号与几何，记录适用范围、单位和取值步长，并由真实builder／renderer消费。把所需样式与配方文件列入`build.inputs`，作为作者输入锁定；不能只记录数值而不应用，也不修改锁定的`vendor/template`、已安装模板或冻结包。每次调整后重建，检查内容容器及整页溢出、裁切、遮挡与层次；共享样式变化覆盖受影响页面。此处不新增自动识别的样式叠加schema或模板重锁入口。
|
||||
|
||||
## 初始化与作者工作流
|
||||
|
||||
解析和工程管理要求 Python 3.10+，只用标准库；实际 builder 的依赖由工程自行声明。消费方明确逐页制作时，保留 `interactive-page`，不要因建立工程而自动批量创作。
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# Fixed spacing
|
||||
|
||||
Spacing belongs to the selected template and shared component recipe. Content callers provide content and whole-container bounds/placement; they do not choose gap values, padding, checking thresholds or one-off variants. If content does not fit, reflow it or choose another supported whole layout/capacity policy. Do not tighten or loosen spacing to fit an instance.
|
||||
Spacing belongs to the selected template and shared component recipe. For faithful reconstruction of an approved mockup, [C27's controlled adjustments](visual-design.md#controlled-adjustments-for-approved-mockups) allow the project to declare revised content-area spacing in a project-owned shared style/recipe. Its values remain fixed within the affected type/variant and scope. Content callers provide content and whole-container bounds/placement; they do not choose gap values, padding, checking thresholds or one-off variants. If content does not fit, reflow it, choose another supported whole layout/capacity policy or revise the shared recipe under C27, then check container and page overflow. Do not tighten or loosen spacing separately for an instance.
|
||||
|
||||
The external style declares `spacing.policy: "fixed"`, `caller_overrides: false` and named `roles`. Each role has a `kind` (`gap` or `padding`) and a `path` array pointing to its authoritative numeric value in the same style. Values stay external; the generic Skill does not prescribe a template's palette, geometry or organization. A role can point to an existing component field, so values are not duplicated. Padding may be a scalar, `[vertical,horizontal]` or `[top,right,bottom,left]`.
|
||||
|
||||
The template owner fixes role names and values; the recipe fixes which roles apply to each relationship. Consumers cannot invent new spacing variants or edit a locked style to evade the policy. A shared owner change is a versioned template/recipe change and triggers affected validation. An older template without the `spacing` section can use supported fixed bindings to its existing fields; absent fields are reported, never filled with guessed numeric defaults.
|
||||
The template owner supplies the default role names and values; the active shared recipe fixes which roles apply to each relationship. Under C27, put revised values in a declared project-owned recipe/style input consumed by the builder, with explicit units and regular integer/fixed-step values, rather than editing the locked template or injecting caller overrides. Rebuild and inspect all affected instances for actual container/page overflow. Project-local adjustments do not modify the published template. A shared template-owner change is a versioned template/recipe change and triggers affected validation. An older template without the `spacing` section can use supported fixed bindings to its existing fields; absent fields are reported, never filled with guessed numeric defaults.
|
||||
|
||||
`resolve_spacing(style, role)` returns the declared scalar or normalized four-sided padding. `check_spacing(boxes, checks, *, style)` accepts only roles:
|
||||
|
||||
@@ -22,4 +22,4 @@ The checker rejects caller-supplied `minimum`, `expected` or override numbers. B
|
||||
|
||||
`text_block.py` automatically records and checks its fixed text padding and paragraph gaps in `spacing_contract`. Callers cannot alter those values through content data. The same rules apply after a content/width change and to every instance of the type/variant.
|
||||
|
||||
The checker measures declared layout geometry. Actual glyph ink, optical clearances, clipping, mathematical layout and decorative contacts still require the current render. Do not modify a fixed value to disguise a font/layout problem or declare visual acceptance from box equality.
|
||||
The checker measures the active style's declared layout geometry and does not load a project override automatically. Actual glyph ink, optical clearances, clipping, mathematical layout and decorative contacts still require the current render. A declared shared adjustment still needs the two-level overflow review; changing a value merely to disguise a font/layout failure or box equality does not establish visual acceptance.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Text blocks and container layout
|
||||
|
||||
Apply C16–C23 in [production rules](production-rules.md) to page authoring, reconstruction, reusable components and collaboration. These are required constraints. A page-library example is a design reference, not an exemption from current rules. Keep fonts, sizes, colors, grid and spacing tied to the selected external template.
|
||||
Apply C16–C23 and C27 in [production rules](production-rules.md) to page authoring, reconstruction, reusable components and collaboration. These are required constraints. A page-library example is a design reference, not an exemption from current rules. Keep fonts, colors and fixed UI tied to the selected external template; approved-mockup content sizes, geometry and spacing may use declared shared project adjustments under C27.
|
||||
|
||||
## One paragraph, one logical text block
|
||||
|
||||
@@ -31,7 +31,7 @@ No paragraph line may consist of only one substantive character after ignoring s
|
||||
|
||||
Independent short labels, standalone table values and separate mathematical symbols are not automatically paragraphs. Determine their actual function; do not relabel a sentence fragment as a label to evade this rule.
|
||||
|
||||
Recompute the complete paragraph's break positions. Prefer intact phrases/clauses where they fit; move enough content between neighboring lines to satisfy both punctuation and singleton rules. If the existing bounds cannot support compliant lines, use the template's normal rewrite/layout/capacity policy. Preserve the complete content and logical text block. Do not delete punctuation, silently add words, compress glyphs, invent a smaller font size or independently position the last line.
|
||||
Recompute the complete paragraph's break positions. Prefer intact phrases/clauses where they fit; move enough content between neighboring lines to satisfy both punctuation and singleton rules. If the existing bounds cannot support compliant lines, use the template's normal rewrite/layout/capacity policy or C27's declared shared typography/geometry adjustment for an approved mockup, then check actual container/page overflow. Preserve the complete content and logical text block. Do not delete punctuation, silently add words, compress glyphs, invent an undeclared smaller font size or independently position the last line.
|
||||
|
||||
For supported plain horizontal text, `scripts/paragraph_layout.py` provides `wrap_paragraph(text, max_width, measure, *, max_lines=None)` and `validate_lines(lines)`. The caller supplies a width-measurement function using the actual selected font and size. The wrapper returns derived rows whose concatenation preserves the input; render them as internal lines of one text frame. Unsupported or impossible input raises an error instead of returning a known-invalid layout. Keep the helper with the shared renderer in the portable project's inputs.
|
||||
|
||||
@@ -41,7 +41,7 @@ This helper is not a complete Unicode line-breaking or typesetting engine, and d
|
||||
|
||||
Check more than overlap. Text must not crowd a border, a preceding explanation, a following module or a connector. Check heading/body spacing, four-sided container padding, column/group gaps, and the clearance around separators and formulas. Judge actual glyphs and visible edges at normal viewing scale; a text frame's nominal box may contain extra space or fail to describe its ink.
|
||||
|
||||
Spacing is **fixed per relationship by the selected template and shared recipe**. Content callers cannot supply numeric gaps, minima, arbitrary padding or alternate spacing variants. The template owner provides moderate values and the recipe applies them; callers do not decide how wide a particular instance should look. See the [fixed spacing contract](spacing.md). Resolve crowding by reflow, shorter content or a different supported whole layout/capacity choice, not by changing spacing or shrinking text. Intentionally cropped watermarks, attached arrows and other decorative/semantic contacts retain their own fixed rules.
|
||||
Spacing is **fixed per relationship by the active shared recipe**, using template values by default or declared project-owned content-area adjustments for an approved mockup under C27. Content callers cannot supply numeric gaps, minima, arbitrary padding or alternate spacing variants. The recipe applies the chosen values consistently; callers do not decide how wide a particular instance should look. See the [fixed spacing contract](spacing.md). Resolve crowding by reflow, an authorized content/layout change or a controlled shared typography/spacing adjustment, followed by [container/page overflow review](visual-design.md#controlled-adjustments-for-approved-mockups). Preserve substantive content and readable hierarchy. Intentionally cropped watermarks, attached arrows and other decorative/semantic contacts retain their own fixed rules.
|
||||
|
||||
Preserve separate paragraphs as separate complete strings or explicit paragraph nodes. Use the fixed positive paragraph gap beyond the normal line-height slots, consistently within the same text role/variant. A line wrap inside one paragraph is not a new paragraph. Prefer native paragraph before/after spacing when multiple paragraphs share a frame; one native frame per paragraph is also supported, with the shared layout deriving all positions. Avoid empty paragraphs, repeated hard breaks and blank text boxes used only as spacers.
|
||||
|
||||
@@ -67,7 +67,7 @@ Read the page without the small muted notes. Its workflow, conclusion and necess
|
||||
|
||||
## Different roles inside a container
|
||||
|
||||
Assign named roles before rendering: for example `card_heading`, `card_body`, `value`, `unit` and `source_note`, mapped to the external template's declared typography and palette. If subheading and body have different functions, distinguish them perceptibly with size, weight and/or color. Using serif for one and sans serif for the other at otherwise identical styling is insufficient. Do not introduce arbitrary sizes or literal colors to create the difference.
|
||||
Assign named roles before rendering: for example `card_heading`, `card_body`, `value`, `unit` and `source_note`, mapped to the external template's declared typography and palette, with any C27 content-size adjustment declared in the shared project style/recipe. If subheading and body have different functions, distinguish them perceptibly with size, weight and/or color. Using serif for one and sans serif for the other at otherwise identical styling is insufficient. Do not introduce undeclared instance sizes or literal colors to create the difference.
|
||||
|
||||
The required distinction is between functions, not every string. Peers with the same function share a role. Verify the distinction in the actual theme and normal viewing scale; two almost identical colors are not a useful hierarchy. A substantive statement remains a body/callout role even when the component offers a small `detail` field.
|
||||
|
||||
@@ -90,7 +90,7 @@ Keep the recipe, parameters, content and assets in the portable project's declar
|
||||
3. Compare subheading/body and other distinct roles within each container at normal viewing scale. Font family alone cannot pass.
|
||||
4. Compare all instances of each type/variant and inspect their creation calls/source. Confirm one shared implementation, no child-coordinate overrides and no post-generation nudges. Equal-looking screenshots alone cannot prove this.
|
||||
5. Read the actual line starts, line ends and last line of each paragraph. Reject forbidden punctuation positions, split unbreakable marks/words, punctuation-only rows and every singleton row, including a character surrounded by punctuation. Reflow and regenerate the whole logical paragraph when changing content, width or typography.
|
||||
6. Check the template's exact fixed values for text padding, heading/body, adjacent-group and formula/connector spacing. Verify no numeric spacing overrides or instance variants entered the caller input. Check actual glyph/edge clearance separately; non-overlap alone is insufficient.
|
||||
6. Check the active shared style/recipe's exact fixed values for text padding, heading/body, adjacent-group and formula/connector spacing, including any declared C27 project adjustment. Verify no numeric spacing overrides or instance variants entered the caller input. Check actual glyph/edge clearance separately; non-overlap alone is insufficient.
|
||||
7. Locate semantic paragraph boundaries in the content source and render. Confirm visible extra separation between paragraphs while maintaining normal line spacing within each paragraph; no dummy empty paragraphs or manually positioned spacer objects.
|
||||
8. For mathematics, inspect [font and equation structure](mathematics.md), then the actual render. Confirm scripts/fractions/limits have not become ordinary unformatted text or a picture.
|
||||
|
||||
|
||||
@@ -12,18 +12,47 @@ Let the user review the current layout at the agreed granularity, incorporate fe
|
||||
|
||||
Record confirmed feedback in existing project/page notes or review material: the preference, user confirmation, applicable page/report scope and reference image/source revision. Reuse it within that scope on subsequent authorized pages. A local change does not become a global rule; an ongoing preference needs explicit support. Do not create another preference database or write global memory. Keep rejected drafts distinguishable from accepted references.
|
||||
|
||||
The template/shared recipe owns final geometry, typography, fixed spacing and UI. Rough positions in the draft cannot override those contracts. Rebuild the actual page with supported native objects and check its reading order, capacity and visual evidence associations. Draft feedback does not establish final native rendering, editing or projection acceptance. Follow [review after revision](execution-and-review.md#review-after-revision) for the agreed independent check of substantive changes.
|
||||
The template/shared recipe supplies geometry, typography, fixed spacing and UI. For an approved mockup, the project may declare [controlled content-area adjustments](#controlled-adjustments-for-approved-mockups) rather than mechanically retain every preset number; fixed page UI and locked structures remain protected. Rebuild the actual page with supported native objects and check its reading order, capacity and visual evidence associations. Draft feedback does not establish final native rendering, editing or projection acceptance. Follow [review after revision](execution-and-review.md#review-after-revision) for the agreed independent check of substantive changes.
|
||||
|
||||
## Approved-mockup fidelity
|
||||
|
||||
An approved current-page mockup becomes the reconstruction reference. Rebuild it as faithfully as possible: preserve the accepted content, figure/image identities, graphics, relative arrangement, proportions, grouping, emphasis and relationships within the selected template's contracts. The draft's roughness permits necessary quality repair; it does not make its accepted elements optional.
|
||||
|
||||
As a rule, keep the established relative spatial relationships, visualization forms, icon identities and text styling. Preserve left/right and above/below order, proximity/grouping, connector endpoints, family intent, weight, color, emphasis, alignment and relative font-size hierarchy. Do not substitute a different chart/diagram form, redraw an icon in an unrelated style or move a label to another visual group for implementation convenience. Necessary fit and optical-alignment repairs below must retain these relationships and appearance; a substantive rearrangement or restyling needs the user's instruction.
|
||||
|
||||
Before reconstruction, inventory the accepted text and visual elements in existing page source/notes, including diagram nodes, links, arrows, braces, enclosures, legend items and labels. A shape that conveys grouping, containment, comparison, direction or a dependency is content. Do not drop it, replace it with an unrelated symbol or call it disposable decoration because native reconstruction is inconvenient. Preserve other accepted graphics too; an allowed picture exception must retain the element and disclose its object type.
|
||||
|
||||
Repair typography defects, verified-text spelling, wrapping, contrast, alignment, spacing, clipping and collisions as needed. Keep substantive text, values, groups and relationship meanings intact; do not solve a quality problem by removing an accepted paragraph, figure, graph element or connection. Use the declared template fonts, discrete sizes and shared geometry rather than tracing raster artifacts. If preserving the accepted content would require a substantive redesign or omission, present that specific change for the user's decision; ordinary quality repairs need no repeated approval.
|
||||
Repair typography defects, verified-text spelling, wrapping, contrast, alignment, spacing, clipping and collisions as needed. Keep substantive text, values, groups and relationship meanings intact; do not solve a quality problem by removing an accepted paragraph, figure, graph element or connection. Keep the declared font families, with font sizes and shared content geometry adjusted under the rules below when useful; do not trace raster artifacts. If preserving the accepted content would require a substantive redesign or omission, present that specific change for the user's decision; ordinary quality repairs and these controlled adjustments need no repeated approval.
|
||||
|
||||
Compare the new full-page render with the approved sample and its inventory. Check for missing elements, changed endpoints, lost group boundaries and altered emphasis as well as appearance. Keep the accepted reference and relevant repairs in the project; do not replace the baseline with a later simplified draft without user instruction. Follow the agreed review assignment without creating a new review pipeline.
|
||||
|
||||
## Controlled adjustments for approved mockups
|
||||
|
||||
For faithful reconstruction of a user-approved mockup, adjust content-area font sizes, text/container dimensions, line/paragraph spacing, padding and necessary fit/alignment as needed for the actual native render. Template preset numbers are the starting point. Keep the accepted content, graphics, relationship-bearing shapes, relative spatial relationships, visualization forms, icon identities and text styling. Font-size adjustments serve accurate reconstruction and readable fit while retaining the sample's relative hierarchy; this is not a general redesign allowance. Fixed page UI, declared font families, brand assets and explicitly locked structures retain their contracts.
|
||||
|
||||
Use explicit units and regular discrete values for actively chosen design parameters. Prefer integers; where useful, select a consistent fixed step for each parameter class and unit, such as 0.5 pt or 0.25 pt. These are examples, not universal required steps. Font sizes and layout distances may use different steps. Apply the same rule to equivalent roles/components within the recorded scope; avoid unexplained multi-digit decimals and unrelated instance nudges. Derived equal distribution, proportional scaling, unit conversion, font metrics and curve/path calculations retain necessary precision. Evidence values and scientific geometry keep their source meaning and precision.
|
||||
|
||||
Keep adjusted roles/values in project-owned shared styles or layout recipes and make the real builder/renderers consume them. Record the approved reference, affected scope, units/steps and meaningful changes in existing project inputs/notes; include required style/recipe files in `build.inputs`, then lock and build. Keep the selected template snapshot, its lock and fixed UI intact. A shared content-area adjustment does not authorize editing installed or frozen template sources. Repeated containers use the same adjusted implementation; content callers still supply semantic content and whole-container placement, not internal spacing overrides. This is an authoring allowance, not a new automatically interpreted style-overlay schema: existing helpers keep their actual supported value types/modules and validation. Use a supported shared recipe and verify that its values are really applied.
|
||||
|
||||
After each typography or geometry adjustment, perform both levels of overflow review on the current rebuilt page:
|
||||
|
||||
| Level | Required checks |
|
||||
|---|---|
|
||||
| Text frame and content container | Verify measured/actual line widths and heights, wrapping, final lines, paragraph gaps and padding. All required text, formulas, labels, images and relationship shapes fit their intended usable bounds, with no clipping or unintended occlusion. A container remaining inside the page does not prove its contents fit. |
|
||||
| Page and canvas | Verify complete visible groups, including container edges, arrowheads, connectors, image crops, strokes and effects, against the usable content region and page boundaries. Check collisions with fixed UI, neighboring groups and other content. A locally valid container does not prove the whole arrangement fits the page. |
|
||||
|
||||
Use source measurements and supported geometry/capacity checks, then inspect actual glyph/edge extents in the current full-page render at fit and normal presentation scale. Formula layout and native reflow may exceed nominal source boxes. Preserve explicitly intended crops or contacts, such as a template watermark, under their existing rules; do not count accidental content loss as intentional cropping. Repair the shared source/recipe, rebuild and inspect again, including affected pages when a shared style changes. Keep the accepted inventory and readable hierarchy; do not hide an overflow by deleting elements or shrinking substantive explanations into tiny text. Successful compilation or bounding-box equality alone does not complete this review. These checks use the existing page workflow and agreed review assignment without an extra approval round.
|
||||
|
||||
## Elements that need ImageGen
|
||||
|
||||
If an approved element is impractical or cumbersome to express faithfully with native components or SVG, use the host ImageGen tool to reconstruct that element as an independent material. Condition on the approved sample and relevant element references, preserving its visualization form, icon identity, style, proportions, details and relationship cues. Do not swap it for a simpler diagram, generic icon or different visual treatment. Native text, containers and connectors that are practical to reproduce remain separate; do not turn the whole page into a generated image.
|
||||
|
||||
Inspect local reference images before use. Give each input its actual role and constrain the edit/generation to the identified element. Request a transparent background and a monochrome or simple, clearly separated palette for generated materials, preserving the accepted shapes, details and style. Preserve real alpha, not a checkerboard or white matte. Compare the generated result to the accepted reference, checking missing parts, labels, endpoints, colors and style; repair the asset rather than accepting a simplified variant. Save the approved reference, prompt, generated original and consumed asset inside the project with provenance, and include them in the real build inputs. Follow current explicit tool choices; capability or budget limits do not authorize silently omitting the element.
|
||||
|
||||
Make recoloring explicit. For a single-color material, retain its alpha mask and the adjustable palette role; recoloring preserves alpha and the full silhouette/antialiased edges. For a few-color material, retain semantic layers or per-role alpha masks and a mapping of adjustable versus fixed colors; preserve holes, opacity and structural transparency. A small number of RGB values alone is not a semantic binding. Do not guess regions from matching colors or recolor fixed details indiscriminately. Use the available image-editing capability or an explicitly supported project binding to produce the intended palette, and inspect an actual recolored result at use size. Retain the required masks/mapping and recoloring inputs with the portable project. The existing SVG paint helper does not automatically recolor PNGs or read a new bitmap descriptor; only claim the mechanism that the project actually implements and verifies.
|
||||
|
||||
Keep exact supplied logos, screenshots, scientific evidence and source data authoritative, with their original backgrounds/colors where required. Reuse those originals instead of inventing replacements; ImageGen may reconstruct associated illustration/decorative material without fabricating evidence. Use verified source text for editable labels whenever practical and check any text retained in the asset. Disclose that a recolorable generated element is a picture, not independently editable internal geometry. Its bitmap color bindings do not turn it into an SVG paint-contract template icon; see [icon production](icon-production.md). Check its resolution, alpha edges, container/page overflow and placement relative to the other accepted elements in the actual rebuilt page.
|
||||
|
||||
## Page composition and HTML boundary
|
||||
|
||||
Every title, text, formula, label, visualization and meaningful decorative group must serve the page task and, through it, the section and report goals. Choose their arrangement from the current information relationship. Pure text can serve a short question, quotation or conclusion; a picture or icon needs a useful role. Do not mechanically reuse website hero sections, selling cards or dashboards as report layouts. The page's main meaning must be readable without scrolling, hovering or clicking.
|
||||
@@ -45,7 +74,7 @@ For a requested raster page sample within the confirmed ImageGen scope, use the
|
||||
|
||||
Inspect local reference images using the available image-viewing tool before editing or conditioning on them. Label each input's role in the prompt. Save prompt, tool result, source attribution and review status under the project. Show the current sample for the user's requested review and incorporate concrete corrections before native reconstruction.
|
||||
|
||||
Use generated text only as visual guidance. Native source text comes from verified content, with the template's declared fonts and sizes; do not copy misspellings or typography defects from the raster sample. Preserve original evidence/identity assets independently so the final native page can use those files exactly.
|
||||
Use generated text only as visual guidance. Native source text comes from verified content, with declared font families and the template's sizes or controlled project adjustments above; do not copy misspellings or typography defects from the raster sample. Preserve original evidence/identity assets independently so the final native page can use those files exactly.
|
||||
|
||||
Native paragraph lines must satisfy [punctuation and singleton rules](text-and-containers.md#paragraph-line-breaking-rules). Do not preserve a mockup's forbidden line-head/tail punctuation or a row containing only one character with optional punctuation; reflow the complete paragraph within the declared layout.
|
||||
|
||||
@@ -55,16 +84,18 @@ After completing each page, inspect its actual current render as a whole at a fi
|
||||
|
||||
| Dimension | Check across the whole page |
|
||||
|---|---|
|
||||
| Font size | Main title/message, section headings, body and supporting details are distinguishable and readable; no essential explanation is demoted to tiny text. Use the declared role sizes. |
|
||||
| Font size | Main title/message, section headings, body and supporting details are distinguishable and readable; no essential explanation is demoted to tiny text. Use the active declared template/project role sizes. |
|
||||
| Font family | Each role uses its declared family, including math/monospace where relevant; substitutions and inconsistent families do not disrupt the hierarchy. |
|
||||
| Font weight | Declared title/heading/body weights are realized correctly; emphasis helps the reader distinguish roles without inventing undeclared bold styles. |
|
||||
| Spacing | Line spacing, paragraph gaps, internal padding and distances between groups follow the shared recipe and visibly separate their intended levels. Check actual glyph/edge clearance. |
|
||||
| Spacing | Line spacing, paragraph gaps, internal padding and distances between groups follow the active shared recipe and visibly separate their intended levels. Check actual glyph/edge clearance. |
|
||||
| Visual content groups | Proximity, alignment, containers, headings and meaningful connectors group related material and separate different groups, including across columns and boxes. The groups match the accepted content relationships. |
|
||||
|
||||
Judge their combined effect: can the reader identify the main message, then the sections, explanations and supporting details in the intended order? Merely assigning several font sizes, passing a bounding-box check or avoiding overlap is not a pass. Uniform styling or equal gaps can flatten the page even when every object is individually legible.
|
||||
|
||||
Repair the source and shared recipes as needed, preserve the approved elements, rebuild and inspect the new render before calling the page complete. Recheck affected pages when a shared recipe changes. Record meaningful findings/repairs briefly in existing page notes or review material; no new scoring schema or specialist review is required. Application editing and projection evidence remain separate under [PowerPoint checks](powerpoint-checks.md).
|
||||
|
||||
For adjusted mockup reconstruction, also complete the [container and page overflow review](#controlled-adjustments-for-approved-mockups). Hierarchy and overflow are separate acceptance conditions: a page can have clear hierarchy while content is clipped, or fit its bounds while all text roles appear flat.
|
||||
|
||||
## Material generation and transparent assets
|
||||
|
||||
For new bitmap illustrations, photos, textures or image edits, use the selected host image-generation capability. Request a transparent background when the final asset needs transparency. Preserve transparency on edits unless the user asks to change it. Use reference-image paths when all targets have paths, otherwise the smallest supported recent-image set that includes every target; do not silently omit a required target.
|
||||
@@ -75,4 +106,4 @@ Check transparent edges against both light and dark backgrounds for halos, missi
|
||||
|
||||
For an existing SVG icon system, use its vector source and declared paint contract rather than generating a new bitmap. Multiple independent color roles need stable element IDs and per-channel rules. Palette binding, fixed details, structural `none` and unlisted paint remain distinct. See [icon handoff](authoring-handoff.md#icon-material-handoff).
|
||||
|
||||
For all new icon sources use [icon production](icon-production.md): reuse, simple authored vectors, complex generated materials, then external supplements. Every route finishes with compliant adjustable parts; raw generated or downloaded rasters are production inputs. Apply the source and evidence requirements in [production rules](production-rules.md).
|
||||
For new reusable adjustable icon sources use [icon production](icon-production.md): reuse, simple authored vectors, complex generated materials, then external supplements. Every reusable route finishes with compliant adjustable parts; raw generated or downloaded rasters are production inputs. For approved-mockup reconstruction preserve the accepted icon identity; [C28's independent picture exception](#elements-that-need-imagegen) remains a project asset and is not an adjustable template icon. Apply the source and evidence requirements in [production rules](production-rules.md).
|
||||
|
||||
Reference in New Issue
Block a user