68 lines
3.7 KiB
Markdown
68 lines
3.7 KiB
Markdown
# update_spec.py
|
|
|
|
> **Scope boundary**: this tool updates only deterministic global color and font
|
|
> substitutions, writes the authoritative `spec_lock.md` only after the SVG
|
|
> updates succeed, and relies on version control for rollback instead of
|
|
> creating parallel backups.
|
|
|
|
Propagate a `spec_lock.md` value change to both the lock file and every `svg_output/*.svg`. The single edit surface for bulk style tweaks after generation.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python3 skills/ppt-master/scripts/update_spec.py <project_path> <section>.<key>=<value>
|
|
```
|
|
|
|
Bare `<key>=<value>` (no dot) is treated as `colors.<key>=<value>` for backward compat.
|
|
|
|
One invocation = one change. The tool:
|
|
|
|
1. Reads the old value from `<project_path>/spec_lock.md`
|
|
2. Plans and propagates the change into every `.svg` under `svg_output/`
|
|
3. Writes the new value into `spec_lock.md`; a global font replacement updates
|
|
every existing `typography.*_family` row together
|
|
4. Prints the list of files touched
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# swap the primary color deck-wide (bare key → colors.primary)
|
|
python3 skills/ppt-master/scripts/update_spec.py projects/acme_ppt169_20260301 primary=#0066AA
|
|
|
|
# explicit section.key form
|
|
python3 skills/ppt-master/scripts/update_spec.py projects/acme_ppt169_20260301 colors.accent=#FF6B35
|
|
|
|
# change the deck-wide font family
|
|
python3 skills/ppt-master/scripts/update_spec.py projects/acme_ppt169_20260301 \
|
|
'typography.font_family=Arial, "Microsoft YaHei", sans-serif'
|
|
```
|
|
|
|
## v2 scope
|
|
|
|
- **Supported**:
|
|
- `colors.*` — HEX value replacement across `svg_output/*.svg` (case-insensitive).
|
|
- `typography.font_family` — replaces the inner value of every
|
|
`font-family="..."` / `font-family='...'` attribute and sets all existing
|
|
`typography.*_family` lock rows to that universal family.
|
|
- **Not supported**: typography sizes, icons, images, canvas, forbidden — these involve attribute-scoped or semantic replacements whose risk/benefit does not warrant bulk propagation. Edit `spec_lock.md` and the affected SVGs by hand, or re-author the pages.
|
|
|
|
## When to use
|
|
|
|
- "Change the primary color across the whole deck" → one `update_spec.py` call
|
|
- "Switch the deck-wide font family" → one `update_spec.py` call
|
|
- "Switch an individual page's accent" → just edit that page's SVG directly
|
|
- "Re-design the palette / type system" → update `spec_lock.md` manually, then the Executor can regenerate affected pages
|
|
|
|
## Safety
|
|
|
|
- HEX values (e.g. `#005587`) are unique enough in SVG content that literal replacement is safe
|
|
- `font-family` substitution is scoped to the attribute; the outer quote character is preserved, and switched automatically if the new value contains the same quote
|
|
- a global font substitution rewrites all existing family-role lock rows in one
|
|
file write, so the universal SVG result cannot leave stale title/body roles
|
|
- The tool refuses non-HEX inputs, unknown keys, and unsupported sections
|
|
- No backups are created — the project folder should be under git so you can diff / revert
|
|
|
|
### Note on first `font-family` update
|
|
|
|
The script writes the `spec_lock.md` value verbatim into every SVG's `font-family` attribute. If the Executor generated SVGs with quote-flattened font names (e.g. `font-family="Microsoft YaHei, Arial, sans-serif"`) while `spec_lock.md` holds the quoted form (`"Microsoft YaHei", Arial, sans-serif`), the **first** substitution will normalize every SVG to match the `spec_lock.md` literal (e.g. `font-family='"Microsoft YaHei", Arial, sans-serif'`). The two forms are semantically equivalent (CSS and DrawingML parse them identically), but the normalization produces byte-level diffs across every SVG that contains text. Subsequent updates only touch files where the value actually changes.
|