Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(native-shapes): add semantic preset discovery

hugohe39c11cb9148f9
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.md
index 2c33258d..f99d4901 100644
--- a/skills/ppt-master/references/native-shape-authoring.md
+++ b/skills/ppt-master/references/native-shape-authoring.md
@@ -12,20 +12,26 @@ only when those constructions fail. Neither helper writes a page. The preset
helper does not create the shape's own `p:txBody`; keep visible text outside the
atomic fragment.
-**Mandatory — complete registry discovery at authoring entry**: before the
+**Mandatory — semantic registry discovery at authoring entry**: before the
first newly authored page or template contour in each valid context, run the
-following command unfiltered and retain its complete output (currently 187
-names). This is authoring-time capability discovery, never a Strategist task or
-Design Spec field. Rerun only after context invalidation or a registry change.
+following command unfiltered and retain its complete output. It organizes all
+187 presets by the official Office gallery categories, then adds semantic
+groups, scopes, and one-line intent summaries. This compact index is
+authoring-time capability discovery, never a Strategist task or Design Spec
+field. Rerun only after context invalidation or a registry change.
```bash
-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list
+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list --grouped
```
-Choose from that full inventory by page job. Use `list --search` only to narrow
-the already-read inventory and `describe <name>` only after identifying a
-candidate; neither replaces the complete initial read. Discovery is prerequisite;
-each page consumes it through §§1–2.1 without a quota.
+The plain `list` command remains a compatibility view of exact registry names;
+it does not replace grouped discovery. For each page, run `recommend` from the
+actual page role and applicable relationship, direction, aspect, text capacity,
+scope, or intent terms, then run `describe <name>` on the serious candidates.
+Those page-local commands supply the full match reasons, intended uses, and
+misuse boundaries omitted from the compact entry index. Recommendation is
+diverse candidate recall, not a whitelist, automatic choice, or shape quota.
+Each page still resolves the final contour through §§1–2.1.
## 1. Contour Selection and Materialization Gate
@@ -82,36 +88,48 @@ objects or their composition.
---
-## 2. Semantic Preset Candidate Guide
+## 2. Semantic Preset Selection
-Use this table as navigation, not a shortlist. Match intent against the loaded
-inventory before selecting a neutral primitive or freeform; examples, style,
-and syntax never hide a more specific contour. Style composition examples
-remain vocabulary, not a menu.
+The catalog's top level follows the Office gallery taxonomy: Lines,
+Rectangles, Basic Shapes, Block Arrows, Equation Shapes, Flowchart, Stars and
+Banners, Callouts, and Action Buttons. The bundled semantic layer at
+`scripts/pptx_shapes/data/presetShapeSemantics.json` adds authoring roles and
+use boundaries; it does not redefine the DrawingML registry.
-"Automatic" means the Executor applies this gate before drawing. Export never
-scans or upgrades existing geometry.
+Apply this page-local sequence before drawing:
-| Visual intent | Candidate presets | Boundary |
+| Pass | Action | Result |
|---|---|---|
-| Page field, outline, or content carrier | `rect`, `round*Rect`, `snip*Rect`, `plaque`, `bevel`, `frame`, `halfFrame`, `corner`, `foldedCorner`, `homePlate` | Match edge, corner, and opening behavior to ownership, hierarchy, or deck language; keep `rect` when no inflection helps. |
-| Grouping or ownership boundary | `leftBrace`, `rightBrace`, `bracePair`, `leftBracket`, `rightBracket`, `bracketPair` | Use a brace / bracket when one visible boundary must collect or assign content without becoming a filled card. |
-| Literal geometric body | `triangle`, `diamond`, `pentagon`, `hexagon`, `octagon`, `star5` | Use only when the named geometry itself is the intent. |
-| Solid block direction | `rightArrow`, `leftArrow`, `upArrow`, `downArrow`, `leftRightArrow`, `upDownArrow`, `chevron` | Use `<line>` for a thin straight relationship; do not fake a solid directional object with a stroked path. |
-| Standard flowchart node | `flowChartProcess`, `flowChartDecision`, `flowChartInputOutput`, `flowChartTerminator`, `flowChartDocument` | Use only for an actual flowchart; ordinary content cards remain cards. |
-| Stock bent / curved relationship contour | `bentConnector*`, `curvedConnector*` | Prefer when the contour fits and endpoint attachment is not required. The authored object is an unconnected native Connector, so moving nodes does not reroute it. |
-| Stock callout | `wedgeRectCallout`, `wedgeRoundRectCallout`, `wedgeEllipseCallout`, `cloudCallout` | For a brand-specific or custom tail, continue through the Boolean gate; use freeform only if the result still cannot be expressed faithfully. |
-| Stock ribbon or scroll | `ribbon*`, `ellipseRibbon*`, `verticalScroll`, `horizontalScroll` | Select only when the stock contour is visually acceptable. |
-| Standalone math symbol | `mathPlus`, `mathMinus`, `mathMultiply`, `mathDivide`, `mathEqual`, `mathNotEqual` | Use only when the symbol itself is a diagram shape; simple notation remains text, while non-trivial inline or block mathematics follows [`native-formula.md`](./native-formula.md). |
-| Literal Office symbol | `heart`, `sun`, `moon`, `lightningBolt`, `gear6`, `gear9` | Never replace an icon required by `spec_lock.icons`. |
-
-Narrow and inspect candidates from the already-loaded inventory:
+| Job | State what the object must do for the reader before naming a shape. | Page role plus any real relationship, direction, aspect, text load, or literal scope. |
+| Recall | Run `recommend` with the known criteria. Keep the default `general` scope unless the page truly needs `literal`, `flowchart`, or `navigation`. | A group-diverse candidate set with match reasons and misuse boundaries. |
+| Inspect | Run `describe` for candidates whose contour could fit; compare `intent`, `recommended_for`, `avoid_for`, adjustments, text rectangle, and connection sites. | Evidence for choosing or rejecting each serious candidate. |
+| Select | Choose the contour whose inference and visual character fit the page, including a neutral primitive when neutrality is useful. | One page-fit contour; no syntax decision yet. |
+| Encode | Apply §1's materialization gate. | Ordinary SVG primitive, helper-authored preset, Boolean result, or necessary freeform. |
+
+Example recall and inspection commands:
```bash
-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list --search arrow
-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py describe rightArrow
+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py recommend \
+ --role spine --relationship order --directionality horizontal --aspect wide
+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py describe chevron
+
+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py recommend \
+ --scope flowchart --role node --relationship flow --query decision
```
+**Hard rule — semantic fit, not name association**: a preset name, topic word,
+or metaphor is not evidence of use. Respect `literal_only` and `scope` before
+visual preference. For example, a scroll is not a generic playbook carrier, a
+lightning bolt is not generic price tension, `chartX` / `chartStar` /
+`chartPlus` are partition symbols rather than charts, and a flowchart symbol
+belongs only in an actual flowchart. An action-button preset supplies visual
+geometry only; it never creates an action or hyperlink.
+
+The semantic catalog chooses contours, not syntax. It never requires `rect`,
+`ellipse`, `line`, or any other primitive to pass through the preset helper;
+after selection, the simplest exact authoring form in §1 remains authoritative.
+Export never scans or upgrades existing geometry.
+
**Shape-first diagram rule**: use `<line>` for straight thin relationships;
use an exact connector-family preset for a stock bent or curved contour; use a
block-arrow / chevron preset for a solid direction. Resort to an open freeform
@@ -123,6 +141,8 @@ owned by the preserve/mirror round-trip contract.
**Forbidden — false native semantics**:
+- a catalog entry with `literal_only=true` when the depicted literal concept is
+ absent, or a `flowchart` / `navigation` scope outside that real context;
- `actionButton*` when navigation or trigger behavior is expected; the helper
maps its visual preset geometry only and never creates an action or hyperlink;
- `chartX`, `chartStar`, or `chartPlus` as a substitute for native charts;
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 5ce345bb..afb37b89 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -197,7 +197,8 @@ python3 scripts/pptx_delivery_check.py <finished.pptx>
Native preset shape authoring (one or more registry-backed fragments on stdout):
```bash
-python3 scripts/preset_shape_svg.py list --search arrow
+python3 scripts/preset_shape_svg.py list --grouped
+python3 scripts/preset_shape_svg.py recommend --role spine --relationship order --directionality horizontal --aspect wide
python3 scripts/preset_shape_svg.py describe rightArrow
python3 scripts/preset_shape_svg.py render rightArrow --id process-arrow --frame 120 180 240 96 --fill '#2563EB'
python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'
@@ -208,18 +209,35 @@ python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'
JSON
```
+`list --grouped` is the compact entry index: it organizes the exact 187-name
+registry under the official Office gallery categories, then exposes semantic
+groups, scopes, one-line intent summaries, and grouped preset names. Full match
+reasons, intended uses, and misuse boundaries remain page-local in `recommend`
+and `describe` instead of being repeated in the mandatory discovery output.
+`recommend` recalls candidates from page-job criteria; its default `general`
+scope excludes literal-only symbols, flowchart notation, and action controls.
+Its result is neither a whitelist nor an automatic selection. `describe`
+combines the selected preset's semantic record with its technical geometry
+metadata. A zero-match recommendation is valid JSON with exit code 0 so the
+caller can relax its criteria; a zero-match `list --search` remains a failed
+lookup with exit code 1. Plain `list [--search QUERY]` remains the compatibility
+name view.
+
The helper never writes a page or project file. Select one exact semantic
stock-shape match, inspect the emitted fragment, and insert it into the
-hand-authored SVG with the normal patch workflow. Its project-authored output
-is one compact atomic `<g>` with direct registry-generated visible paths. When
-one effect is justified, optional `--filter-id softShadow` references one
-existing direct page-level filter under the shared shadow/glow contract and
-applies it once to a shape preset. Connector presets do not accept that option.
-The helper does not create the filter definition. `render-batch` accepts a
-non-empty JSON array using the snake_case forms of the single-render options;
-it validates every item and duplicate id before printing, so one invalid item
-produces no partial fragment output. The batch remains fragment-only input for
-one current construction, not a page generator or project manifest.
+hand-authored SVG with the normal patch workflow. Semantic discovery does not
+force ordinary rectangles, ellipses, or lines through `render`; use the
+simplest exact authoring form from the native-shape reference. A rendered
+project-owned preset is one compact atomic `<g>` with direct registry-generated
+visible paths. When one effect is justified, optional `--filter-id softShadow`
+references one existing direct page-level filter under the shared shadow/glow
+contract and applies it once to a shape preset. Connector presets do not accept
+that option. The helper does not create the filter definition. `render-batch`
+accepts a non-empty JSON array using the snake_case forms of the single-render
+options; it validates every item and duplicate id before printing, so one
+invalid item produces no partial fragment output. The batch remains
+fragment-only input for one current construction, not a page generator or
+project manifest.
Quality check and export rerender the registry instead of relying on a hidden
carrier, preview wrapper, or stored preview fingerprint. PPTX import and
round-trip SVGs deliberately keep their expanded carrier/preview evidence and
diff --git a/skills/ppt-master/scripts/pptx_shapes/__init__.py b/skills/ppt-master/scripts/pptx_shapes/__init__.py
index 5e724838..52d7ccbe 100644
--- a/skills/ppt-master/scripts/pptx_shapes/__init__.py
+++ b/skills/ppt-master/scripts/pptx_shapes/__init__.py
@@ -55,6 +55,18 @@ from .registry import (
PresetShapeRegistry,
get_preset_registry,
)
+from .semantics import (
+ BUNDLED_SEMANTICS_PATH,
+ SEMANTIC_ASPECTS,
+ SEMANTIC_DIRECTIONALITY,
+ SEMANTIC_RELATIONSHIPS,
+ SEMANTIC_ROLES,
+ SEMANTIC_SCOPES,
+ SEMANTIC_TEXT_CAPACITIES,
+ SEMANTIC_VISUAL_WEIGHTS,
+ PresetShapeSemantics,
+ get_preset_shape_semantics,
+)
from .semantic_hash import (
NATIVE_FALLBACK_SHA256_ATTR,
resolve_preset_preview_hash,
@@ -69,6 +81,7 @@ from .xml_safety import RELATIONSHIPS_NS, has_relationship_attributes
__all__ = [
"BUNDLED_DEFINITIONS_PATH",
"BUNDLED_DEFINITIONS_SHA256",
+ "BUNDLED_SEMANTICS_PATH",
"BUNDLED_SHAPE_TYPES_PATH",
"BUNDLED_SHAPE_TYPES_SHA256",
"CONNECTOR_PRESET_TYPES",
@@ -89,12 +102,21 @@ __all__ = [
"PresetShapeDefinition",
"PresetShapeError",
"PresetShapeRegistry",
+ "PresetShapeSemantics",
"RELATIONSHIPS_NS",
+ "SEMANTIC_ASPECTS",
+ "SEMANTIC_DIRECTIONALITY",
+ "SEMANTIC_RELATIONSHIPS",
+ "SEMANTIC_ROLES",
+ "SEMANTIC_SCOPES",
+ "SEMANTIC_TEXT_CAPACITIES",
+ "SEMANTIC_VISUAL_WEIGHTS",
"UnknownGuideError",
"UnknownPresetShapeError",
"build_builtin_guides",
"evaluate_formula",
"get_preset_registry",
+ "get_preset_shape_semantics",
"has_relationship_attributes",
"load_preset_shape_definitions",
"load_shape_type_values",
diff --git a/skills/ppt-master/scripts/pptx_shapes/data/presetShapeSemantics.json b/skills/ppt-master/scripts/pptx_shapes/data/presetShapeSemantics.json
new file mode 100644
index 00000000..f534c955
--- /dev/null
+++ b/skills/ppt-master/scripts/pptx_shapes/data/presetShapeSemantics.json
@@ -0,0 +1,1217 @@
+{
+ "schema": "ppt-master.preset-shape-semantics.v1",
+ "sources": [
+ {
+ "kind": "office-gallery-categories",
+ "url": "https://support.microsoft.com/en-US/Accessibility/powerpoint/use-a-screen-reader-to-insert-and-edit-pictures-and-tables-in-powerpoint",
+ "use": "Office category names"
+ },
+ {
+ "kind": "drawingml-preset-enum",
+ "url": "https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.shapetypevalues?view=openxml-3.0.1",
+ "use": "DrawingML preset names"
+ },
+ {
+ "kind": "powerpoint-shape-enum",
+ "url": "https://learn.microsoft.com/en-us/javascript/api/powerpoint/powerpoint.geometricshapetype?view=powerpoint-js-preview",
+ "use": "Literal shape identity and terminology"
+ },
+ {
+ "kind": "powerpoint-action-buttons",
+ "url": "https://support.microsoft.com/en-us/powerpoint/add-commands-to-your-presentation-with-action-buttons",
+ "use": "Action-button behavior boundary"
+ }
+ ],
+ "office_categories": [
+ {
+ "id": "lines",
+ "label": "Lines",
+ "summary": "Straight, bent, and curved relationship contours."
+ },
+ {
+ "id": "rectangles",
+ "label": "Rectangles",
+ "summary": "Neutral and corner-inflected rectangular carriers."
+ },
+ {
+ "id": "basic-shapes",
+ "label": "Basic Shapes",
+ "summary": "Geometric bodies, boundaries, radial contours, and literal symbols."
+ },
+ {
+ "id": "block-arrows",
+ "label": "Block Arrows",
+ "summary": "Filled directional bodies for sequence, movement, and route emphasis."
+ },
+ {
+ "id": "equation-shapes",
+ "label": "Equation Shapes",
+ "summary": "Literal mathematical operators."
+ },
+ {
+ "id": "flowchart",
+ "label": "Flowchart",
+ "summary": "Conventional flowchart notation for explicit process diagrams."
+ },
+ {
+ "id": "stars-and-banners",
+ "label": "Stars and Banners",
+ "summary": "Emblems, bursts, banners, scrolls, and wave accents."
+ },
+ {
+ "id": "callouts",
+ "label": "Callouts",
+ "summary": "Annotation bodies and leaders that point to another object or region."
+ },
+ {
+ "id": "action-buttons",
+ "label": "Action Buttons",
+ "summary": "Visual navigation-control shapes whose actions must be assigned separately."
+ }
+ ],
+ "groups": [
+ {
+ "id": "straight-lines",
+ "label": "Straight lines and connectors",
+ "office_category": "lines",
+ "scope": "general",
+ "roles": ["edge", "spine", "boundary"],
+ "relationships": ["link", "order", "contrast", "annotation"],
+ "directionality": ["horizontal", "vertical", "diagonal"],
+ "aspects": ["linear"],
+ "text_capacity": "none",
+ "visual_weight": "quiet",
+ "literal_only": false,
+ "recommended_for": [
+ "Direct links, dividers, leaders, and reading-path spines.",
+ "Thin relationships whose meaning comes from endpoints, routing, or an optional marker."
+ ],
+ "avoid_for": [
+ "Do not substitute a line for a filled directional body or content carrier.",
+ "Do not imply endpoint attachment; newly authored connector presets remain unconnected."
+ ],
+ "presets": {
+ "line": {"intent": "Straight line with the default diagonal orientation."},
+ "lineInv": {"intent": "Straight line with the inverse default diagonal orientation."},
+ "straightConnector1": {"intent": "Straight connector contour when connector object identity matters."}
+ }
+ },
+ {
+ "id": "bent-connectors",
+ "label": "Bent connectors",
+ "office_category": "lines",
+ "scope": "general",
+ "roles": ["edge", "spine"],
+ "relationships": ["link", "order", "hierarchy", "flow"],
+ "directionality": ["bent"],
+ "aspects": ["flexible"],
+ "text_capacity": "none",
+ "visual_weight": "quiet",
+ "literal_only": false,
+ "recommended_for": [
+ "Orthogonal routing around content or between aligned zones.",
+ "Relationships whose route needs visible right-angle structure."
+ ],
+ "avoid_for": [
+ "Do not add bends when a straight relationship is clearer.",
+ "Do not use the extra segments as decoration or imply unsupported endpoint attachment."
+ ],
+ "presets": {
+ "bentConnector2": {"intent": "One-bend orthogonal connector."},
+ "bentConnector3": {"intent": "Two-bend orthogonal connector."},
+ "bentConnector4": {"intent": "Three-bend orthogonal connector."},
+ "bentConnector5": {"intent": "Four-bend orthogonal connector for more complex routing."}
+ }
+ },
+ {
+ "id": "curved-connectors",
+ "label": "Curved connectors",
+ "office_category": "lines",
+ "scope": "general",
+ "roles": ["edge", "spine"],
+ "relationships": ["link", "order", "cycle", "flow"],
+ "directionality": ["curved"],
+ "aspects": ["flexible"],
+ "text_capacity": "none",
+ "visual_weight": "quiet",
+ "literal_only": false,
+ "recommended_for": [
+ "Soft rerouting, feedback links, or relationships that must pass around objects.",
+ "Continuous paths where curvature carries meaning."
+ ],
+ "avoid_for": [
+ "Do not curve a direct link merely to make it look less plain.",
+ "Do not imply unsupported endpoint attachment."
+ ],
+ "presets": {
+ "curvedConnector2": {"intent": "Single-curve connector."},
+ "curvedConnector3": {"intent": "Two-segment curved connector."},
+ "curvedConnector4": {"intent": "Three-segment curved connector."},
+ "curvedConnector5": {"intent": "Four-segment curved connector for complex routing."}
+ }
+ },
+ {
+ "id": "neutral-rectangles",
+ "label": "Neutral rectangular carriers",
+ "office_category": "rectangles",
+ "scope": "general",
+ "roles": ["field", "carrier", "node", "label"],
+ "relationships": ["none", "membership", "contrast", "hierarchy"],
+ "directionality": ["none"],
+ "aspects": ["flexible"],
+ "text_capacity": "high",
+ "visual_weight": "quiet",
+ "literal_only": false,
+ "recommended_for": [
+ "Content ownership, stable fields, and nodes that need no directional or symbolic inflection.",
+ "Layouts where the absence of contour meaning is itself useful."
+ ],
+ "avoid_for": [
+ "Do not choose neutrality only because primitive syntax is shorter.",
+ "Do not wrap every text block when spacing already communicates ownership."
+ ],
+ "presets": {
+ "rect": {"intent": "Fully neutral rectangular field or carrier."},
+ "roundRect": {"intent": "Uniformly rounded carrier with a softer, more approachable boundary."}
+ }
+ },
+ {
+ "id": "corner-inflected-rectangles",
+ "label": "Corner-inflected rectangles",
+ "office_category": "rectangles",
+ "scope": "general",
+ "roles": ["field", "carrier", "node", "label"],
+ "relationships": ["membership", "order", "hierarchy", "contrast"],
+ "directionality": ["none", "horizontal", "vertical", "diagonal"],
+ "aspects": ["flexible"],
+ "text_capacity": "high",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Carriers whose rounded or clipped corners mark an entry edge, open edge, or deck-wide contour language.",
+ "Subtle hierarchy without adding arrows or icons."
+ ],
+ "avoid_for": [
+ "Do not scatter corner variants randomly; the changed corners must have a page-level reason.",
+ "Do not let a decorative corner imply direction that the content does not have."
+ ],
+ "presets": {
+ "round1Rect": {"intent": "One rounded corner for a single softened or attached edge."},
+ "round2SameRect": {"intent": "Two rounded corners on one side, creating a clear opening or terminal edge."},
+ "round2DiagRect": {"intent": "Two diagonally opposed rounded corners for reciprocal or diagonal tension."},
+ "snipRoundRect": {"intent": "Mixed clipped and rounded corners for controlled technical contrast."},
+ "snip1Rect": {"intent": "One clipped corner for a single technical or directional cue."},
+ "snip2SameRect": {"intent": "Two clipped corners on one side for an open or connected edge."},
+ "snip2DiagRect": {"intent": "Two diagonally clipped corners for diagonal rhythm or contrast."}
+ }
+ },
+ {
+ "id": "triangular-bodies",
+ "label": "Triangular bodies",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["node", "carrier", "accent", "symbol"],
+ "relationships": ["hierarchy", "order", "contrast", "literal"],
+ "directionality": ["none", "horizontal", "vertical", "diagonal"],
+ "aspects": ["square", "flexible"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Apex, escalation, directional focus, or a literal triangular object.",
+ "Corner anchoring where a diagonal edge materially organizes the page."
+ ],
+ "avoid_for": [
+ "Do not use as a generic card; an apex or diagonal edge creates a strong inference.",
+ "Do not replace a true arrow when movement or endpoint direction is the job."
+ ],
+ "presets": {
+ "triangle": {"intent": "Symmetric triangle for apex, priority, or upward/downward focus."},
+ "rtTriangle": {"intent": "Right triangle for corner anchoring, diagonal split, or literal geometry."}
+ }
+ },
+ {
+ "id": "slanted-quadrilaterals",
+ "label": "Slanted quadrilaterals",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["carrier", "node", "accent"],
+ "relationships": ["order", "contrast", "flow"],
+ "directionality": ["horizontal", "diagonal"],
+ "aspects": ["wide", "flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Motion, transformation, comparison, or a sloped handoff between zones.",
+ "Nodes where the slanted sides reinforce the reading direction."
+ ],
+ "avoid_for": [
+ "Do not use the diamond as a fake flowchart decision outside an actual flowchart.",
+ "Do not use slanted edges on static content with no directional meaning."
+ ],
+ "presets": {
+ "diamond": {"intent": "Four-sided focal node for branching, opposition, or a literal diamond."},
+ "parallelogram": {"intent": "Parallel slants for motion, transfer, or input/output-like movement."},
+ "trapezoid": {"intent": "Symmetric widening or narrowing for expansion, compression, or stage change."},
+ "nonIsoscelesTrapezoid": {"intent": "Asymmetric widening or narrowing for off-axis transition."}
+ }
+ },
+ {
+ "id": "regular-polygons",
+ "label": "Regular polygon bodies",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["carrier", "node", "label", "accent"],
+ "relationships": ["none", "membership", "hierarchy", "contrast"],
+ "directionality": ["none", "radial"],
+ "aspects": ["square"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Compact nodes, numbered stages, badges, or radial systems where side count supports the visual language.",
+ "Focal carriers that need more presence than a circle or rectangle."
+ ],
+ "avoid_for": [
+ "Do not encode a number merely by matching the polygon side count unless readers benefit.",
+ "Do not use many unrelated polygon families on one page."
+ ],
+ "presets": {
+ "pentagon": {"intent": "Five-sided compact node or badge."},
+ "hexagon": {"intent": "Six-sided technical or modular node."},
+ "heptagon": {"intent": "Seven-sided emblematic node with unusual visual rhythm."},
+ "octagon": {"intent": "Eight-sided stop-like or high-presence node."},
+ "decagon": {"intent": "Ten-sided near-circular badge with faceted edges."},
+ "dodecagon": {"intent": "Twelve-sided near-circular badge or radial node."}
+ }
+ },
+ {
+ "id": "organic-carriers",
+ "label": "Organic carriers",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["field", "carrier", "node", "accent"],
+ "relationships": ["membership", "hierarchy", "overlap", "contrast"],
+ "directionality": ["none", "radial"],
+ "aspects": ["flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Soft focal zones, ports, lenses, or organic contrast against angular geometry.",
+ "Overlap and containment when a continuous curved edge improves grouping."
+ ],
+ "avoid_for": [
+ "Do not default to circles for every metric or icon.",
+ "Do not use a teardrop unless its pointed end has a focus or direction."
+ ],
+ "presets": {
+ "ellipse": {"intent": "Continuous oval field, focal lens, or soft node."},
+ "teardrop": {"intent": "Rounded body with one pointed focus for origin, destination, or literal drop imagery."}
+ }
+ },
+ {
+ "id": "ornamental-carriers",
+ "label": "Ornamental carriers",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["carrier", "label", "accent"],
+ "relationships": ["membership", "hierarchy", "contrast"],
+ "directionality": ["none"],
+ "aspects": ["flexible", "wide"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "A single high-emphasis label, title plate, or inset whose edge treatment matches the deck language."
+ ],
+ "avoid_for": [
+ "Do not repeat as ordinary cards; concave corners or beveling create ceremonial emphasis.",
+ "Do not use solely to make a box look less plain."
+ ],
+ "presets": {
+ "plaque": {"intent": "Concave-corner plate for a formal label, title, or emblem."},
+ "bevel": {"intent": "Beveled rectangular body for a raised or inset focal surface."}
+ }
+ },
+ {
+ "id": "radial-contours",
+ "label": "Radial contours and segments",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["field", "spine", "boundary", "accent"],
+ "relationships": ["cycle", "overlap", "membership", "contrast"],
+ "directionality": ["radial", "curved"],
+ "aspects": ["square", "flexible"],
+ "text_capacity": "short",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Cycles, apertures, partial reveals, circular zoning, or a curved page spine.",
+ "Non-quantitative radial structure where the contour itself guides reading."
+ ],
+ "avoid_for": [
+ "Do not imply a measured proportion unless the angle is backed by data.",
+ "Do not imitate a pie or donut chart when a native data chart is required."
+ ],
+ "presets": {
+ "pieWedge": {"intent": "Single circular wedge for a radial anchor or literal sector."},
+ "pie": {"intent": "Circle with an adjustable missing sector for reveal or incomplete-cycle meaning."},
+ "blockArc": {"intent": "Thick curved band for a cycle segment, portal, or curved spine."},
+ "donut": {"intent": "Closed ring for circular containment, focus, or a literal ring."},
+ "chord": {"intent": "Circular segment bounded by an arc and chord for overlap or partial-reveal geometry."},
+ "arc": {"intent": "Open curved contour for a light boundary, trajectory, or partial frame."}
+ }
+ },
+ {
+ "id": "frames-and-corners",
+ "label": "Frames, corners, and edge pieces",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["field", "boundary", "accent"],
+ "relationships": ["membership", "hierarchy", "contrast"],
+ "directionality": ["none", "horizontal", "vertical", "diagonal"],
+ "aspects": ["flexible"],
+ "text_capacity": "none",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Open ownership boundaries, page apertures, edge anchors, and corner-led composition.",
+ "Grouping without turning every content unit into a filled card."
+ ],
+ "avoid_for": [
+ "Do not place a frame around content that already has clear ownership.",
+ "Do not use folded or diagonal details without a matching page-level edge language."
+ ],
+ "presets": {
+ "foldedCorner": {"intent": "Sheet-like carrier or accent with one folded corner."},
+ "frame": {"intent": "Closed rectangular frame for a strong aperture or ownership boundary."},
+ "halfFrame": {"intent": "Partially open frame for directional grouping or an incomplete boundary."},
+ "corner": {"intent": "L-shaped corner piece for edge anchoring or a partial frame."},
+ "diagStripe": {"intent": "Diagonal band for edge emphasis, slanted continuity, or a literal stripe."}
+ }
+ },
+ {
+ "id": "brackets",
+ "label": "Brackets",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["boundary", "callout"],
+ "relationships": ["membership", "annotation", "hierarchy"],
+ "directionality": ["horizontal", "vertical"],
+ "aspects": ["tall", "wide", "flexible"],
+ "text_capacity": "none",
+ "visual_weight": "quiet",
+ "literal_only": false,
+ "recommended_for": [
+ "Collecting adjacent items, marking a range, or assigning a label to one side of a group."
+ ],
+ "avoid_for": [
+ "Do not use when a filled carrier already establishes membership.",
+ "Do not mix bracket directions without a clear ownership side."
+ ],
+ "presets": {
+ "leftBracket": {"intent": "Left-side bracket that collects content to its right."},
+ "rightBracket": {"intent": "Right-side bracket that collects content to its left."},
+ "bracketPair": {"intent": "Paired brackets that enclose a complete range or set."}
+ }
+ },
+ {
+ "id": "braces",
+ "label": "Braces",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["boundary", "callout"],
+ "relationships": ["membership", "annotation", "hierarchy"],
+ "directionality": ["horizontal", "vertical"],
+ "aspects": ["tall", "wide", "flexible"],
+ "text_capacity": "none",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Visible grouping, aggregation, or one-to-many ownership where a bracket is too mechanical."
+ ],
+ "avoid_for": [
+ "Do not use as ornamental punctuation detached from a real group.",
+ "Do not use paired braces when one-sided assignment is the actual relationship."
+ ],
+ "presets": {
+ "leftBrace": {"intent": "Left-side brace that groups or assigns content to its right."},
+ "rightBrace": {"intent": "Right-side brace that groups or assigns content to its left."},
+ "bracePair": {"intent": "Paired braces that enclose a complete set."}
+ }
+ },
+ {
+ "id": "literal-pictograms",
+ "label": "Literal pictograms",
+ "office_category": "basic-shapes",
+ "scope": "literal",
+ "roles": ["symbol", "accent"],
+ "relationships": ["literal"],
+ "directionality": ["none"],
+ "aspects": ["square"],
+ "text_capacity": "none",
+ "visual_weight": "emblematic",
+ "literal_only": true,
+ "recommended_for": [
+ "A concept whose ordinary meaning is exactly the depicted object or symbol."
+ ],
+ "avoid_for": [
+ "Do not select by loose metaphor or keyword association.",
+ "Do not use as a generic visual-energy substitute for real structure."
+ ],
+ "presets": {
+ "cube": {"intent": "Literal cube or compact three-dimensional object."},
+ "can": {"intent": "Literal cylinder, database-like store, or container."},
+ "lightningBolt": {"intent": "Literal lightning, electricity, shock, or sudden-impact symbol.", "avoid_for": ["Do not use for generic tension, urgency, or price change without literal electrical or shock meaning."]},
+ "heart": {"intent": "Literal affection, preference, health-heart, or favorite symbol."},
+ "sun": {"intent": "Literal sun, daylight, heat, or weather symbol."},
+ "moon": {"intent": "Literal moon, night, sleep, or lunar symbol."},
+ "smileyFace": {"intent": "Literal positive-emotion or satisfaction symbol."},
+ "noSmoking": {"intent": "Prohibition symbol with an adjustable slash over a target."},
+ "cloud": {"intent": "Literal cloud, cloud-computing domain, or atmospheric thought field."}
+ }
+ },
+ {
+ "id": "functional-pictograms",
+ "label": "Functional pictograms",
+ "office_category": "basic-shapes",
+ "scope": "literal",
+ "roles": ["symbol", "node", "accent"],
+ "relationships": ["literal", "flow"],
+ "directionality": ["none", "radial"],
+ "aspects": ["square", "tall"],
+ "text_capacity": "none",
+ "visual_weight": "strong",
+ "literal_only": true,
+ "recommended_for": [
+ "Literal mechanism, settings, processing, or filtering concepts."
+ ],
+ "avoid_for": [
+ "Do not use gears as a generic synonym for every process.",
+ "Do not use a funnel unless narrowing, screening, or conversion is the actual relationship."
+ ],
+ "presets": {
+ "gear6": {"intent": "Six-tooth gear for a literal mechanism, settings, or interlocking process."},
+ "gear9": {"intent": "Nine-tooth gear for a denser literal mechanism or system component."},
+ "funnel": {"intent": "Literal filtering, narrowing, qualification, or conversion funnel."}
+ }
+ },
+ {
+ "id": "plus-symbol",
+ "label": "Plus symbol",
+ "office_category": "basic-shapes",
+ "scope": "literal",
+ "roles": ["symbol", "accent", "node"],
+ "relationships": ["literal", "convergence"],
+ "directionality": ["multidirectional"],
+ "aspects": ["square"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": true,
+ "recommended_for": [
+ "Literal addition, inclusion, medical-cross, or combined-value meaning."
+ ],
+ "avoid_for": [
+ "Do not use as a generic decoration between unrelated items.",
+ "Use mathPlus when the page is explicitly mathematical notation."
+ ],
+ "presets": {
+ "plus": {"intent": "Broad plus or cross body for literal addition, inclusion, or cross symbolism."}
+ }
+ },
+ {
+ "id": "corner-tabs",
+ "label": "Corner and edge tabs",
+ "office_category": "basic-shapes",
+ "scope": "general",
+ "roles": ["field", "boundary", "accent"],
+ "relationships": ["membership", "hierarchy", "contrast"],
+ "directionality": ["none", "multidirectional"],
+ "aspects": ["flexible"],
+ "text_capacity": "none",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Four-corner framing, registration marks, or a technical aperture around a focal zone."
+ ],
+ "avoid_for": [
+ "Do not treat the four tabs as independent data points.",
+ "Do not add them when a simpler frame already communicates the boundary."
+ ],
+ "presets": {
+ "cornerTabs": {"intent": "Four triangular corner tabs defining an implied rectangle."},
+ "squareTabs": {"intent": "Four square edge tabs defining an implied rectangle."},
+ "plaqueTabs": {"intent": "Four rounded corner tabs defining an implied rectangle."}
+ }
+ },
+ {
+ "id": "partition-symbols",
+ "label": "Partition symbols",
+ "office_category": "basic-shapes",
+ "scope": "literal",
+ "roles": ["symbol", "node", "accent"],
+ "relationships": ["overlap", "convergence", "literal"],
+ "directionality": ["multidirectional"],
+ "aspects": ["square"],
+ "text_capacity": "none",
+ "visual_weight": "strong",
+ "literal_only": true,
+ "recommended_for": [
+ "A literal four- or six-region partition, intersection, or hub motif."
+ ],
+ "avoid_for": [
+ "Despite their names, these are not charts and carry no data semantics.",
+ "Do not use as a substitute for a native chart or an explained matrix."
+ ],
+ "presets": {
+ "chartX": {"intent": "Rectangle divided diagonally into four triangular regions."},
+ "chartStar": {"intent": "Rectangle divided into six regions by vertical and diagonal lines."},
+ "chartPlus": {"intent": "Rectangle divided into four quarters by vertical and horizontal lines."}
+ }
+ },
+ {
+ "id": "arrow-carriers",
+ "label": "Arrow-shaped carriers",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["carrier", "node", "spine"],
+ "relationships": ["order", "flow", "hierarchy"],
+ "directionality": ["horizontal"],
+ "aspects": ["wide"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Stage bodies, handoffs, and compact process steps whose container and direction are one object."
+ ],
+ "avoid_for": [
+ "Do not use as a generic card; the pointed end asserts flow.",
+ "Do not use when a thin connector between independent nodes is clearer."
+ ],
+ "presets": {
+ "homePlate": {"intent": "Pentagon-like horizontal stage body with one pointed destination edge."},
+ "chevron": {"intent": "Compact V-notched directional stage for repeated sequence or handoff."}
+ }
+ },
+ {
+ "id": "cardinal-arrows",
+ "label": "Cardinal block arrows",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["spine", "edge", "accent"],
+ "relationships": ["order", "flow", "hierarchy"],
+ "directionality": ["horizontal", "vertical"],
+ "aspects": ["wide", "tall"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Strong one-way movement, escalation, decline, or a dominant next-step direction."
+ ],
+ "avoid_for": [
+ "Do not use for a neutral link or divider.",
+ "Do not point toward content unless the endpoint relationship is real."
+ ],
+ "presets": {
+ "rightArrow": {"intent": "Strong left-to-right movement or next-step direction.", "directionality": ["horizontal"], "aspects": ["wide"]},
+ "leftArrow": {"intent": "Strong right-to-left movement, return, or reverse direction.", "directionality": ["horizontal"], "aspects": ["wide"]},
+ "upArrow": {"intent": "Strong upward movement, growth, or escalation.", "directionality": ["vertical"], "aspects": ["tall"]},
+ "downArrow": {"intent": "Strong downward movement, decline, or descent.", "directionality": ["vertical"], "aspects": ["tall"]}
+ }
+ },
+ {
+ "id": "stylized-forward-arrows",
+ "label": "Stylized forward arrows",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["spine", "accent"],
+ "relationships": ["order", "flow", "contrast"],
+ "directionality": ["horizontal"],
+ "aspects": ["wide"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Forward motion where the tail treatment communicates acceleration, entry, or interlock."
+ ],
+ "avoid_for": [
+ "Do not choose the tail treatment only for novelty.",
+ "Do not use when a plain cardinal arrow already expresses the job."
+ ],
+ "presets": {
+ "stripedRightArrow": {"intent": "Right arrow with tail stripes for acceleration, launch, or staged entry."},
+ "notchedRightArrow": {"intent": "Right arrow with an inward tail notch for interlock or handoff."}
+ }
+ },
+ {
+ "id": "multi-axis-arrows",
+ "label": "Multi-axis arrows",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["spine", "node", "accent"],
+ "relationships": ["contrast", "convergence", "flow", "link"],
+ "directionality": ["bidirectional", "multidirectional"],
+ "aspects": ["wide", "tall", "square"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Reciprocity, branching, multi-way movement, or a hub with explicit directional alternatives."
+ ],
+ "avoid_for": [
+ "Do not imply symmetry or available routes that the content does not support.",
+ "Do not use as a generic central decoration."
+ ],
+ "presets": {
+ "leftRightArrow": {"intent": "Horizontal reciprocity or two-way exchange.", "directionality": ["horizontal", "bidirectional"], "aspects": ["wide"]},
+ "upDownArrow": {"intent": "Vertical reciprocity or two-way change.", "directionality": ["vertical", "bidirectional"], "aspects": ["tall"]},
+ "leftUpArrow": {"intent": "Two-route branch toward left and up.", "directionality": ["multidirectional"], "aspects": ["square"]},
+ "leftRightUpArrow": {"intent": "Three-route branch toward left, right, and up.", "directionality": ["multidirectional"], "aspects": ["square"]},
+ "quadArrow": {"intent": "Four-way hub or movement in all cardinal directions.", "directionality": ["multidirectional"], "aspects": ["square"]}
+ }
+ },
+ {
+ "id": "turn-arrows",
+ "label": "Bent and return arrows",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["spine", "edge", "accent"],
+ "relationships": ["order", "flow", "cycle"],
+ "directionality": ["bent", "curved"],
+ "aspects": ["flexible", "square"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "A real turn, reroute, reversal, or return within a process path."
+ ],
+ "avoid_for": [
+ "Do not use a turn arrow for generic progress with no change of direction.",
+ "Do not confuse a filled turn body with a thin routed connector."
+ ],
+ "presets": {
+ "bentUpArrow": {"intent": "Sharp right-angle route ending upward.", "directionality": ["bent", "vertical"]},
+ "bentArrow": {"intent": "Rounded right-angle route for a directional turn.", "directionality": ["bent", "horizontal"]},
+ "uturnArrow": {"intent": "Explicit reversal, return, or loop-back path.", "directionality": ["curved", "vertical"]}
+ }
+ },
+ {
+ "id": "circular-arrows",
+ "label": "Circular arrows",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["spine", "edge", "accent"],
+ "relationships": ["cycle", "flow", "link"],
+ "directionality": ["radial", "bidirectional"],
+ "aspects": ["square"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Closed-loop processes, recurrence, refresh, or circular exchange."
+ ],
+ "avoid_for": [
+ "Do not imply repetition or reversibility unless it exists.",
+ "Do not use as a decorative halo around unrelated content."
+ ],
+ "presets": {
+ "circularArrow": {"intent": "One-direction circular loop or refresh path.", "directionality": ["radial"]},
+ "leftCircularArrow": {"intent": "Counter-oriented circular loop or return path.", "directionality": ["radial"]},
+ "leftRightCircularArrow": {"intent": "Two-way circular exchange or reversible cycle."}
+ }
+ },
+ {
+ "id": "curved-arrows",
+ "label": "Curved and swoosh arrows",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["spine", "edge", "accent"],
+ "relationships": ["order", "flow", "convergence"],
+ "directionality": ["curved", "horizontal", "vertical"],
+ "aspects": ["wide", "tall", "flexible"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Directional motion that must arc around a focal object or converge from an offset origin."
+ ],
+ "avoid_for": [
+ "Do not add curvature merely to make an arrow more expressive.",
+ "Do not use when the path would falsely imply bypass or convergence."
+ ],
+ "presets": {
+ "curvedRightArrow": {"intent": "Curved path ending to the right.", "directionality": ["curved", "horizontal"], "aspects": ["wide"]},
+ "curvedLeftArrow": {"intent": "Curved path ending to the left.", "directionality": ["curved", "horizontal"], "aspects": ["wide"]},
+ "curvedUpArrow": {"intent": "Curved path ending upward.", "directionality": ["curved", "vertical"], "aspects": ["tall"]},
+ "curvedDownArrow": {"intent": "Curved path ending downward.", "directionality": ["curved", "vertical"], "aspects": ["tall"]},
+ "swooshArrow": {"intent": "Fast tapered sweep for launch, acceleration, or a dynamic handoff.", "directionality": ["curved", "horizontal"], "aspects": ["wide"]}
+ }
+ },
+ {
+ "id": "arrow-callouts",
+ "label": "Arrow callout bodies",
+ "office_category": "block-arrows",
+ "scope": "general",
+ "roles": ["carrier", "callout", "spine"],
+ "relationships": ["annotation", "order", "flow", "contrast"],
+ "directionality": ["horizontal", "vertical", "bidirectional", "multidirectional"],
+ "aspects": ["wide", "tall", "square"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "A short message whose body and directional emphasis must be one strong object."
+ ],
+ "avoid_for": [
+ "Do not use as an ordinary content card.",
+ "Do not point in multiple directions unless the message truly applies to each route."
+ ],
+ "presets": {
+ "leftArrowCallout": {"intent": "Text-bearing callout with strong leftward direction.", "directionality": ["horizontal"], "aspects": ["wide"]},
+ "rightArrowCallout": {"intent": "Text-bearing callout with strong rightward direction.", "directionality": ["horizontal"], "aspects": ["wide"]},
+ "upArrowCallout": {"intent": "Text-bearing callout with strong upward direction.", "directionality": ["vertical"], "aspects": ["tall"]},
+ "downArrowCallout": {"intent": "Text-bearing callout with strong downward direction.", "directionality": ["vertical"], "aspects": ["tall"]},
+ "leftRightArrowCallout": {"intent": "Text-bearing callout for horizontal two-way emphasis.", "directionality": ["horizontal", "bidirectional"], "aspects": ["wide"]},
+ "upDownArrowCallout": {"intent": "Text-bearing callout for vertical two-way emphasis.", "directionality": ["vertical", "bidirectional"], "aspects": ["tall"]},
+ "quadArrowCallout": {"intent": "Text-bearing callout for four-way or hub emphasis.", "directionality": ["multidirectional"], "aspects": ["square"]}
+ }
+ },
+ {
+ "id": "equation-operators",
+ "label": "Equation operators",
+ "office_category": "equation-shapes",
+ "scope": "literal",
+ "roles": ["symbol", "node"],
+ "relationships": ["literal", "convergence", "contrast"],
+ "directionality": ["none", "multidirectional"],
+ "aspects": ["square", "wide"],
+ "text_capacity": "none",
+ "visual_weight": "strong",
+ "literal_only": true,
+ "recommended_for": [
+ "An explicit mathematical or logical operator between operands."
+ ],
+ "avoid_for": [
+ "Do not use equation symbols as generic separators or decorative icons.",
+ "Keep operand order and mathematical meaning unambiguous."
+ ],
+ "presets": {
+ "mathPlus": {"intent": "Mathematical addition operator."},
+ "mathMinus": {"intent": "Mathematical subtraction operator."},
+ "mathMultiply": {"intent": "Mathematical multiplication operator."},
+ "mathDivide": {"intent": "Mathematical division operator."},
+ "mathEqual": {"intent": "Mathematical equality operator."},
+ "mathNotEqual": {"intent": "Mathematical inequality operator."}
+ }
+ },
+ {
+ "id": "flowchart-operations",
+ "label": "Flowchart operations",
+ "office_category": "flowchart",
+ "scope": "flowchart",
+ "roles": ["node"],
+ "relationships": ["flow", "order"],
+ "directionality": ["none"],
+ "aspects": ["wide", "flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Exact conventional operation nodes inside an actual flowchart."
+ ],
+ "avoid_for": [
+ "Do not use flowchart notation as a decorative card vocabulary.",
+ "Do not substitute one operation symbol for another because its contour looks better."
+ ],
+ "presets": {
+ "flowChartProcess": {"intent": "Standard process or operation step."},
+ "flowChartPredefinedProcess": {"intent": "Named subprocess or predefined operation."},
+ "flowChartAlternateProcess": {"intent": "Alternate process step."},
+ "flowChartPreparation": {"intent": "Preparation or initialization step."},
+ "flowChartManualOperation": {"intent": "Operation performed manually."},
+ "flowChartDelay": {"intent": "Delay or waiting period."}
+ }
+ },
+ {
+ "id": "flowchart-routing",
+ "label": "Flowchart decisions and routing",
+ "office_category": "flowchart",
+ "scope": "flowchart",
+ "roles": ["node"],
+ "relationships": ["flow", "link", "convergence"],
+ "directionality": ["none", "multidirectional"],
+ "aspects": ["square", "flexible"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Exact branch, merge, junction, or continuation semantics inside an actual flowchart."
+ ],
+ "avoid_for": [
+ "Do not infer routing semantics from appearance alone.",
+ "Do not use these symbols outside a diagram that explains its flow."
+ ],
+ "presets": {
+ "flowChartDecision": {"intent": "Decision or branch point."},
+ "flowChartConnector": {"intent": "On-page continuation connector."},
+ "flowChartOffpageConnector": {"intent": "Continuation to another page or diagram frame."},
+ "flowChartSummingJunction": {"intent": "Summing junction where flows combine."},
+ "flowChartOr": {"intent": "Logical OR junction."},
+ "flowChartCollate": {"intent": "Collate or reconcile inputs into an ordered result."},
+ "flowChartSort": {"intent": "Sort or order operation."},
+ "flowChartExtract": {"intent": "Extract one stream or subset from another."},
+ "flowChartMerge": {"intent": "Merge multiple flow paths into one."}
+ }
+ },
+ {
+ "id": "flowchart-input-output",
+ "label": "Flowchart input and output",
+ "office_category": "flowchart",
+ "scope": "flowchart",
+ "roles": ["node"],
+ "relationships": ["flow"],
+ "directionality": ["none", "horizontal"],
+ "aspects": ["wide", "flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Exact data-entry or presentation nodes inside an actual flowchart."
+ ],
+ "avoid_for": [
+ "Do not use obsolete media symbols unless the depicted medium is intentional.",
+ "Do not use input/output notation as a general slanted content card."
+ ],
+ "presets": {
+ "flowChartInputOutput": {"intent": "General data input or output."},
+ "flowChartManualInput": {"intent": "Data entered manually."},
+ "flowChartPunchedCard": {"intent": "Punched-card input or a deliberately historical medium."},
+ "flowChartPunchedTape": {"intent": "Punched-tape input or a deliberately historical medium."},
+ "flowChartDisplay": {"intent": "Information shown on a display."}
+ }
+ },
+ {
+ "id": "flowchart-documents",
+ "label": "Flowchart documents",
+ "office_category": "flowchart",
+ "scope": "flowchart",
+ "roles": ["node"],
+ "relationships": ["flow", "membership"],
+ "directionality": ["none"],
+ "aspects": ["wide", "flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Document artifacts that enter, leave, or are produced by an actual flowchart."
+ ],
+ "avoid_for": [
+ "Do not use the wavy bottom as a generic decorative card edge."
+ ],
+ "presets": {
+ "flowChartDocument": {"intent": "Single document artifact."},
+ "flowChartMultidocument": {"intent": "Multiple document artifacts or a document set."}
+ }
+ },
+ {
+ "id": "flowchart-storage",
+ "label": "Flowchart storage",
+ "office_category": "flowchart",
+ "scope": "flowchart",
+ "roles": ["node"],
+ "relationships": ["flow", "membership"],
+ "directionality": ["none"],
+ "aspects": ["wide", "tall", "flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Exact storage-media semantics inside an actual flowchart."
+ ],
+ "avoid_for": [
+ "Do not choose a storage symbol by silhouette alone.",
+ "Use historical media shapes only when that distinction matters."
+ ],
+ "presets": {
+ "flowChartInternalStorage": {"intent": "Internal storage or memory."},
+ "flowChartOfflineStorage": {"intent": "Offline storage."},
+ "flowChartOnlineStorage": {"intent": "Online or directly accessible storage."},
+ "flowChartMagneticTape": {"intent": "Sequential-access magnetic tape storage."},
+ "flowChartMagneticDisk": {"intent": "Magnetic disk storage."},
+ "flowChartMagneticDrum": {"intent": "Magnetic drum or direct-access historical storage."}
+ }
+ },
+ {
+ "id": "flowchart-terminator",
+ "label": "Flowchart terminator",
+ "office_category": "flowchart",
+ "scope": "flowchart",
+ "roles": ["node"],
+ "relationships": ["flow", "order"],
+ "directionality": ["none"],
+ "aspects": ["wide"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "Start, end, or terminal state in an actual flowchart."
+ ],
+ "avoid_for": [
+ "Do not use as a generic pill-shaped label when no terminal state is intended."
+ ],
+ "presets": {
+ "flowChartTerminator": {"intent": "Start, end, or terminal state."}
+ }
+ },
+ {
+ "id": "stars",
+ "label": "Stars",
+ "office_category": "stars-and-banners",
+ "scope": "literal",
+ "roles": ["symbol", "accent", "label"],
+ "relationships": ["literal", "hierarchy", "contrast"],
+ "directionality": ["radial"],
+ "aspects": ["square"],
+ "text_capacity": "short",
+ "visual_weight": "emblematic",
+ "literal_only": true,
+ "recommended_for": [
+ "Literal rating, award, sparkle, burst, or one exceptional focal badge."
+ ],
+ "avoid_for": [
+ "Do not use as a routine bullet, card, or unexplained attention device.",
+ "High-point stars carry burst or sparkle energy and are poor text carriers."
+ ],
+ "presets": {
+ "star4": {"intent": "Four-point sparkle or compass-like accent."},
+ "star5": {"intent": "Conventional rating, award, or favorite star."},
+ "star6": {"intent": "Six-point geometric star or literal emblem."},
+ "star7": {"intent": "Seven-point unusual emblem or focal burst."},
+ "star8": {"intent": "Eight-point badge, compass, or controlled burst."},
+ "star10": {"intent": "Ten-point seal-like badge or radial emphasis."},
+ "star12": {"intent": "Twelve-point seal-like badge or radial emphasis."},
+ "star16": {"intent": "Dense burst for exceptional emphasis."},
+ "star24": {"intent": "Very dense sparkle or burst accent."},
+ "star32": {"intent": "Maximum-density sparkle or burst accent."}
+ }
+ },
+ {
+ "id": "irregular-seals",
+ "label": "Irregular seals and explosions",
+ "office_category": "stars-and-banners",
+ "scope": "literal",
+ "roles": ["symbol", "accent", "label"],
+ "relationships": ["literal", "contrast"],
+ "directionality": ["radial"],
+ "aspects": ["square"],
+ "text_capacity": "short",
+ "visual_weight": "emblematic",
+ "literal_only": true,
+ "recommended_for": [
+ "A literal burst, warning, sale seal, or exceptional interruption."
+ ],
+ "avoid_for": [
+ "Do not use for ordinary emphasis or as a recurring section badge.",
+ "Do not place long text inside the irregular contour."
+ ],
+ "presets": {
+ "irregularSeal1": {"intent": "Irregular burst with a coarser explosion edge."},
+ "irregularSeal2": {"intent": "Irregular burst with a denser explosion edge."}
+ }
+ },
+ {
+ "id": "straight-ribbons",
+ "label": "Straight ribbons",
+ "office_category": "stars-and-banners",
+ "scope": "general",
+ "roles": ["label", "carrier", "accent"],
+ "relationships": ["hierarchy", "contrast", "order"],
+ "directionality": ["horizontal", "bidirectional"],
+ "aspects": ["wide"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "One ceremonial title, milestone, award label, or section banner."
+ ],
+ "avoid_for": [
+ "Do not use as a generic content card or repeat on every page.",
+ "Do not imply directional arrows from ribbon tails unless the reading path supports it."
+ ],
+ "presets": {
+ "ribbon": {"intent": "Banner with the center panel raised above its folded ends.", "directionality": ["horizontal"]},
+ "ribbon2": {"intent": "Banner with the center panel lowered below its folded ends.", "directionality": ["horizontal"]},
+ "leftRightRibbon": {"intent": "Straight ribbon with outward left and right tail emphasis."}
+ }
+ },
+ {
+ "id": "curved-ribbons",
+ "label": "Curved ribbons",
+ "office_category": "stars-and-banners",
+ "scope": "general",
+ "roles": ["label", "carrier", "accent"],
+ "relationships": ["hierarchy", "contrast"],
+ "directionality": ["curved", "horizontal"],
+ "aspects": ["wide"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "A single arched title or badge whose curvature is part of the page composition."
+ ],
+ "avoid_for": [
+ "Do not bend ordinary labels for decoration alone.",
+ "Do not use when the curve conflicts with the page's reading axis."
+ ],
+ "presets": {
+ "ellipseRibbon": {"intent": "Curved ribbon arcing upward around a central label."},
+ "ellipseRibbon2": {"intent": "Curved ribbon arcing downward around a central label."}
+ }
+ },
+ {
+ "id": "scrolls",
+ "label": "Scrolls",
+ "office_category": "stars-and-banners",
+ "scope": "literal",
+ "roles": ["label", "carrier", "symbol"],
+ "relationships": ["literal", "hierarchy"],
+ "directionality": ["horizontal", "vertical"],
+ "aspects": ["wide", "tall"],
+ "text_capacity": "medium",
+ "visual_weight": "emblematic",
+ "literal_only": true,
+ "recommended_for": [
+ "A literal scroll, proclamation, archival document, or deliberately historical motif."
+ ],
+ "avoid_for": [
+ "Do not use a scroll as a generic playbook, process card, or long-form content container.",
+ "Do not select it merely because the topic mentions a document."
+ ],
+ "presets": {
+ "verticalScroll": {"intent": "Tall rolled document or vertical historical proclamation.", "directionality": ["vertical"], "aspects": ["tall"]},
+ "horizontalScroll": {"intent": "Wide rolled document or horizontal historical proclamation.", "directionality": ["horizontal"], "aspects": ["wide"]}
+ }
+ },
+ {
+ "id": "waves",
+ "label": "Waves",
+ "office_category": "stars-and-banners",
+ "scope": "literal",
+ "roles": ["accent", "spine", "symbol"],
+ "relationships": ["literal", "flow", "cycle"],
+ "directionality": ["curved", "horizontal"],
+ "aspects": ["wide"],
+ "text_capacity": "none",
+ "visual_weight": "strong",
+ "literal_only": true,
+ "recommended_for": [
+ "Literal wave, oscillation, fluid motion, or one continuous undulating accent."
+ ],
+ "avoid_for": [
+ "Do not use as an arbitrary section divider.",
+ "Do not imply volatility or oscillation unless the content supports it."
+ ],
+ "presets": {
+ "wave": {"intent": "Single undulating band for literal wave or oscillation."},
+ "doubleWave": {"intent": "Double undulating band for stronger ripple or oscillation."}
+ }
+ },
+ {
+ "id": "leader-callouts",
+ "label": "Leader-line callouts",
+ "office_category": "callouts",
+ "scope": "general",
+ "roles": ["callout", "label", "edge"],
+ "relationships": ["annotation", "link"],
+ "directionality": ["callout", "bent"],
+ "aspects": ["flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "moderate",
+ "literal_only": false,
+ "recommended_for": [
+ "A short annotation that must visibly point to one object or region.",
+ "Choose bend count and border/accent treatment from the routing and emphasis need."
+ ],
+ "avoid_for": [
+ "Do not use as a free-standing content card with no target.",
+ "Do not add bends or accent bars that carry no routing or hierarchy purpose."
+ ],
+ "presets": {
+ "callout1": {"intent": "Unbordered callout with a straight leader."},
+ "callout2": {"intent": "Unbordered callout with one bent leader."},
+ "callout3": {"intent": "Unbordered callout with a double-bent leader."},
+ "accentCallout1": {"intent": "Straight-leader callout with an accent bar but no full border."},
+ "accentCallout2": {"intent": "One-bend callout with an accent bar but no full border."},
+ "accentCallout3": {"intent": "Double-bend callout with an accent bar but no full border."},
+ "borderCallout1": {"intent": "Bordered callout with a straight leader."},
+ "borderCallout2": {"intent": "Bordered callout with one bent leader."},
+ "borderCallout3": {"intent": "Bordered callout with a double-bent leader."},
+ "accentBorderCallout1": {"intent": "Bordered straight-leader callout with an accent bar."},
+ "accentBorderCallout2": {"intent": "Bordered one-bend callout with an accent bar."},
+ "accentBorderCallout3": {"intent": "Bordered double-bend callout with an accent bar."}
+ }
+ },
+ {
+ "id": "wedge-callouts",
+ "label": "Wedge and thought callouts",
+ "office_category": "callouts",
+ "scope": "general",
+ "roles": ["callout", "carrier", "label"],
+ "relationships": ["annotation", "link"],
+ "directionality": ["callout"],
+ "aspects": ["flexible"],
+ "text_capacity": "medium",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "A speech, thought, or annotation body whose wedge visibly identifies the target."
+ ],
+ "avoid_for": [
+ "Do not use without a real target.",
+ "Use the cloud variant only for thought, uncertainty, or a literal cloud context."
+ ],
+ "presets": {
+ "wedgeRectCallout": {"intent": "Rectangular annotation body with a pointed wedge to the target."},
+ "wedgeRoundRectCallout": {"intent": "Rounded rectangular annotation body with a pointed wedge."},
+ "wedgeEllipseCallout": {"intent": "Oval speech-like annotation body with a pointed wedge."},
+ "cloudCallout": {"intent": "Cloud-shaped thought callout with a dotted tail."}
+ }
+ },
+ {
+ "id": "action-controls",
+ "label": "Action-button controls",
+ "office_category": "action-buttons",
+ "scope": "navigation",
+ "roles": ["control", "symbol"],
+ "relationships": ["navigation", "literal"],
+ "directionality": ["none", "horizontal"],
+ "aspects": ["square", "flexible"],
+ "text_capacity": "short",
+ "visual_weight": "strong",
+ "literal_only": false,
+ "recommended_for": [
+ "Interactive presentation controls when the matching click or hover action will also be assigned."
+ ],
+ "avoid_for": [
+ "The preset supplies visual geometry only; it does not create navigation, media, or hyperlink behavior.",
+ "Do not use action-button chrome as a decorative icon set in a noninteractive deck."
+ ],
+ "presets": {
+ "actionButtonBlank": {"intent": "Blank action-button body for a custom control label or icon."},
+ "actionButtonHome": {"intent": "Home navigation control."},
+ "actionButtonHelp": {"intent": "Help control."},
+ "actionButtonInformation": {"intent": "Information control."},
+ "actionButtonForwardNext": {"intent": "Forward or next navigation control."},
+ "actionButtonBackPrevious": {"intent": "Back or previous navigation control."},
+ "actionButtonEnd": {"intent": "End or last-slide navigation control."},
+ "actionButtonBeginning": {"intent": "Beginning or first-slide navigation control."},
+ "actionButtonReturn": {"intent": "Return navigation control."},
+ "actionButtonDocument": {"intent": "Document-opening control."},
+ "actionButtonSound": {"intent": "Sound playback control."},
+ "actionButtonMovie": {"intent": "Movie or video playback control."}
+ }
+ }
+ ]
+}
diff --git a/skills/ppt-master/scripts/pptx_shapes/semantics.py b/skills/ppt-master/scripts/pptx_shapes/semantics.py
new file mode 100644
index 00000000..75e7f2c4
--- /dev/null
+++ b/skills/ppt-master/scripts/pptx_shapes/semantics.py
@@ -0,0 +1,716 @@
+#!/usr/bin/env python3
+"""
+PPT Master - DrawingML Preset Shape Semantics
+
+Load and validate the bundled Office-category and authoring-use catalog for
+DrawingML preset shapes.
+
+Usage:
+ Import get_preset_shape_semantics from pptx_shapes.semantics.
+
+Examples:
+ catalog = get_preset_shape_semantics()
+ arrow = catalog.describe("rightArrow")
+
+Dependencies:
+ None (only uses standard library and local PPT Master modules)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Sequence
+
+from .errors import PresetShapeDataError, UnknownPresetShapeError
+from .registry import get_preset_registry
+
+
+BUNDLED_SEMANTICS_PATH = (
+ Path(__file__).resolve().parent / "data" / "presetShapeSemantics.json"
+)
+
+SEMANTIC_ROLES = (
+ "field",
+ "carrier",
+ "node",
+ "edge",
+ "spine",
+ "boundary",
+ "callout",
+ "label",
+ "symbol",
+ "control",
+ "accent",
+)
+SEMANTIC_RELATIONSHIPS = (
+ "none",
+ "membership",
+ "order",
+ "link",
+ "hierarchy",
+ "contrast",
+ "convergence",
+ "cycle",
+ "overlap",
+ "annotation",
+ "flow",
+ "literal",
+ "navigation",
+)
+SEMANTIC_DIRECTIONALITY = (
+ "none",
+ "horizontal",
+ "vertical",
+ "diagonal",
+ "bidirectional",
+ "multidirectional",
+ "bent",
+ "curved",
+ "radial",
+ "callout",
+)
+SEMANTIC_ASPECTS = (
+ "flexible",
+ "wide",
+ "tall",
+ "square",
+ "linear",
+)
+SEMANTIC_TEXT_CAPACITIES = ("none", "short", "medium", "high")
+SEMANTIC_VISUAL_WEIGHTS = ("quiet", "moderate", "strong", "emblematic")
+SEMANTIC_SCOPES = ("general", "literal", "flowchart", "navigation")
+
+_TEXT_CAPACITY_RANK = {
+ value: index for index, value in enumerate(SEMANTIC_TEXT_CAPACITIES)
+}
+_QUERY_TOKEN_RE = re.compile(r"[a-z0-9]+")
+_CAMEL_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+_QUERY_STOP_WORDS = frozenset({
+ "a",
+ "an",
+ "and",
+ "for",
+ "of",
+ "or",
+ "the",
+ "to",
+ "with",
+})
+
+
+class PresetShapeSemantics:
+ """Read-only semantic catalog aligned exactly with the preset registry."""
+
+ def __init__(self, payload: object, expected_names: Sequence[str]) -> None:
+ root = _require_dict(payload, "catalog")
+ self.schema = _require_string(root.get("schema"), "catalog.schema")
+ self.sources = tuple(
+ _require_dict(item, f"catalog.sources[{index}]")
+ for index, item in enumerate(
+ _require_list(root.get("sources"), "catalog.sources")
+ )
+ )
+
+ categories = _require_list(
+ root.get("office_categories"),
+ "catalog.office_categories",
+ )
+ self._categories: list[dict[str, object]] = []
+ self._category_by_id: dict[str, dict[str, object]] = {}
+ for index, raw_category in enumerate(categories):
+ label = f"catalog.office_categories[{index}]"
+ category = _require_dict(raw_category, label)
+ _reject_unknown_fields(category, label, {"id", "label", "summary"})
+ category_id = _require_string(category.get("id"), f"{label}.id")
+ if category_id in self._category_by_id:
+ raise PresetShapeDataError(
+ f"Duplicate Office shape category: {category_id!r}"
+ )
+ normalized = {
+ "id": category_id,
+ "label": _require_string(category.get("label"), f"{label}.label"),
+ "summary": _require_string(
+ category.get("summary"),
+ f"{label}.summary",
+ ),
+ }
+ self._categories.append(normalized)
+ self._category_by_id[category_id] = normalized
+
+ groups = _require_list(root.get("groups"), "catalog.groups")
+ self._groups: list[dict[str, object]] = []
+ self._preset_semantics: dict[str, dict[str, object]] = {}
+ self._group_order: dict[str, int] = {}
+ self._preset_order = {
+ name: index for index, name in enumerate(expected_names)
+ }
+ for index, raw_group in enumerate(groups):
+ group = self._normalize_group(raw_group, index)
+ group_id = str(group["id"])
+ if group_id in self._group_order:
+ raise PresetShapeDataError(
+ f"Duplicate preset semantic group: {group_id!r}"
+ )
+ self._group_order[group_id] = index
+ self._groups.append(group)
+ presets = group["presets"]
+ assert isinstance(presets, dict)
+ for preset_name, preset_details in presets.items():
+ if preset_name in self._preset_semantics:
+ raise PresetShapeDataError(
+ f"Preset appears in multiple semantic groups: {preset_name!r}"
+ )
+ details = dict(group)
+ details.pop("presets")
+ details["preset"] = preset_name
+ details.update(preset_details)
+ details["recommended_for"] = _merge_strings(
+ group["recommended_for"],
+ preset_details.get("recommended_for", ()),
+ )
+ details["avoid_for"] = _merge_strings(
+ group["avoid_for"],
+ preset_details.get("avoid_for", ()),
+ )
+ self._preset_semantics[preset_name] = details
+
+ expected = set(expected_names)
+ actual = set(self._preset_semantics)
+ missing = sorted(expected - actual)
+ extra = sorted(actual - expected)
+ if missing or extra:
+ raise PresetShapeDataError(
+ "Preset semantic catalog differs from ShapeTypeValues: "
+ f"missing={missing}, extra={extra}"
+ )
+
+ @classmethod
+ def bundled(cls) -> PresetShapeSemantics:
+ """Load the semantic catalog shipped with PPT Master."""
+
+ try:
+ payload = json.loads(BUNDLED_SEMANTICS_PATH.read_text(encoding="utf-8"))
+ except OSError as exc:
+ raise PresetShapeDataError(
+ f"Cannot read preset semantic catalog: {exc}"
+ ) from exc
+ except json.JSONDecodeError as exc:
+ raise PresetShapeDataError(
+ "Invalid preset semantic JSON at "
+ f"line {exc.lineno}, column {exc.colno}: {exc.msg}"
+ ) from exc
+ return cls(payload, get_preset_registry().names)
+
+ @property
+ def preset_count(self) -> int:
+ """Return the number of catalogued presets."""
+
+ return len(self._preset_semantics)
+
+ def describe(self, preset: str) -> dict[str, object]:
+ """Return the resolved semantic record for one preset."""
+
+ try:
+ return dict(self._preset_semantics[preset])
+ except KeyError as exc:
+ raise UnknownPresetShapeError(
+ f"Unknown DrawingML preset shape: {preset!r}"
+ ) from exc
+
+ def grouped(self, search: str = "") -> dict[str, object]:
+ """Return a compact Office/group index and matching preset names."""
+
+ query_tokens = _query_tokens(search)
+ category_payloads: list[dict[str, object]] = []
+ for category in self._categories:
+ group_payloads: list[dict[str, object]] = []
+ for group in self._groups:
+ if group["office_category"] != category["id"]:
+ continue
+ presets = group["presets"]
+ assert isinstance(presets, dict)
+ matching_presets = []
+ group_matches = _matches_query(
+ {
+ key: value
+ for key, value in group.items()
+ if key != "presets"
+ },
+ query_tokens,
+ )
+ for name, details in presets.items():
+ if query_tokens and not group_matches and not _matches_query(
+ {"preset": name, **details},
+ query_tokens,
+ ):
+ continue
+ matching_presets.append(name)
+ if not matching_presets:
+ continue
+ recommended_for = group["recommended_for"]
+ assert isinstance(recommended_for, tuple)
+ group_payload = {
+ "id": group["id"],
+ "label": group["label"],
+ "scope": group["scope"],
+ "intent": recommended_for[0],
+ "presets": matching_presets,
+ }
+ group_payloads.append(group_payload)
+ if group_payloads:
+ category_payloads.append({**category, "groups": group_payloads})
+ return {
+ "schema": self.schema,
+ "sources": [dict(source) for source in self.sources],
+ "preset_count": sum(
+ len(group["presets"])
+ for category in category_payloads
+ for group in category["groups"]
+ ),
+ "search": search,
+ "office_categories": category_payloads,
+ }
+
+ def recommend(
+ self,
+ *,
+ roles: Sequence[str],
+ scope: str = "general",
+ relationships: Sequence[str] = (),
+ directionality: str | None = None,
+ aspect: str | None = None,
+ text_capacity: str | None = None,
+ visual_weight: str | None = None,
+ query: str = "",
+ limit: int = 12,
+ ) -> dict[str, object]:
+ """Return a diverse, semantics-matched candidate recall set."""
+
+ query_tokens = _query_tokens(query)
+ candidates: list[dict[str, object]] = []
+ for details in self._preset_semantics.values():
+ if scope != "all" and details["scope"] != scope:
+ continue
+
+ role_matches = [role for role in roles if role in details["roles"]]
+ if not role_matches:
+ continue
+ relationship_matches = [
+ relationship
+ for relationship in relationships
+ if relationship in details["relationships"]
+ ]
+ if relationships and not relationship_matches:
+ continue
+ if directionality and directionality not in details["directionality"]:
+ continue
+ if aspect and not _aspect_matches(details["aspects"], aspect):
+ continue
+ if text_capacity and not _capacity_matches(
+ str(details["text_capacity"]),
+ text_capacity,
+ ):
+ continue
+ if visual_weight and details["visual_weight"] != visual_weight:
+ continue
+
+ query_score = _query_score(details, query_tokens, query)
+ if query_tokens and query_score == 0:
+ continue
+ score = (
+ len(role_matches) * 20
+ + len(relationship_matches) * 12
+ + (5 if directionality else 0)
+ + (4 if aspect else 0)
+ + (3 if text_capacity else 0)
+ + (2 if visual_weight else 0)
+ + query_score
+ )
+ why = [f"role={value}" for value in role_matches]
+ why.extend(
+ f"relationship={value}" for value in relationship_matches
+ )
+ if directionality:
+ why.append(f"directionality={directionality}")
+ if aspect:
+ why.append(f"aspect={aspect}")
+ if text_capacity:
+ why.append(f"text_capacity>={text_capacity}")
+ if visual_weight:
+ why.append(f"visual_weight={visual_weight}")
+ if query_tokens:
+ why.append(f"query={query}")
+ candidates.append({
+ "score": score,
+ "preset": details["preset"],
+ "office_category": {
+ "id": details["office_category"],
+ "label": details["office_category_label"],
+ },
+ "group": details["id"],
+ "scope": details["scope"],
+ "intent": details["intent"],
+ "why": why,
+ "recommended_for": details["recommended_for"],
+ "avoid_for": details["avoid_for"],
+ "literal_only": details["literal_only"],
+ })
+
+ ordered = self._diverse_order(candidates)
+ return {
+ "criteria": {
+ "roles": list(roles),
+ "scope": scope,
+ "relationships": list(relationships),
+ "directionality": directionality,
+ "aspect": aspect,
+ "text_capacity": text_capacity,
+ "visual_weight": visual_weight,
+ "query": query,
+ },
+ "candidate_count": len(candidates),
+ "returned_count": min(len(ordered), limit),
+ "selection_note": (
+ "Candidate recall only. Compare contour, content fit, and avoid_for "
+ "before choosing; this is neither a whitelist nor an automatic choice."
+ if ordered
+ else "No candidates matched. This is a valid recall result; relax or "
+ "change the criteria before selecting a contour."
+ ),
+ "candidates": ordered[:limit],
+ }
+
+ def _normalize_group(
+ self,
+ raw_group: object,
+ index: int,
+ ) -> dict[str, object]:
+ label = f"catalog.groups[{index}]"
+ group = _require_dict(raw_group, label)
+ _reject_unknown_fields(
+ group,
+ label,
+ {
+ "id",
+ "label",
+ "office_category",
+ "scope",
+ "roles",
+ "relationships",
+ "directionality",
+ "aspects",
+ "text_capacity",
+ "visual_weight",
+ "literal_only",
+ "recommended_for",
+ "avoid_for",
+ "presets",
+ },
+ )
+ category_id = _require_string(
+ group.get("office_category"),
+ f"{label}.office_category",
+ )
+ if category_id not in self._category_by_id:
+ raise PresetShapeDataError(
+ f"{label} references unknown Office category {category_id!r}"
+ )
+ scope = _require_choice(group.get("scope"), f"{label}.scope", SEMANTIC_SCOPES)
+ roles = _require_choices(group.get("roles"), f"{label}.roles", SEMANTIC_ROLES)
+ relationships = _require_choices(
+ group.get("relationships"),
+ f"{label}.relationships",
+ SEMANTIC_RELATIONSHIPS,
+ )
+ directionality = _require_choices(
+ group.get("directionality"),
+ f"{label}.directionality",
+ SEMANTIC_DIRECTIONALITY,
+ )
+ aspects = _require_choices(
+ group.get("aspects"),
+ f"{label}.aspects",
+ SEMANTIC_ASPECTS,
+ )
+ presets = _require_dict(group.get("presets"), f"{label}.presets")
+ if not presets:
+ raise PresetShapeDataError(f"{label}.presets must not be empty")
+ normalized_presets: dict[str, dict[str, object]] = {}
+ for preset_name, raw_details in presets.items():
+ preset_label = f"{label}.presets[{preset_name!r}]"
+ details = _require_dict(raw_details, preset_label)
+ _reject_unknown_fields(
+ details,
+ preset_label,
+ {
+ "intent",
+ "scope",
+ "roles",
+ "relationships",
+ "directionality",
+ "aspects",
+ "text_capacity",
+ "visual_weight",
+ "literal_only",
+ "recommended_for",
+ "avoid_for",
+ },
+ )
+ normalized_details: dict[str, object] = {
+ "intent": _require_string(
+ details.get("intent"),
+ f"{preset_label}.intent",
+ )
+ }
+ repeated_choices = {
+ "roles": SEMANTIC_ROLES,
+ "relationships": SEMANTIC_RELATIONSHIPS,
+ "directionality": SEMANTIC_DIRECTIONALITY,
+ "aspects": SEMANTIC_ASPECTS,
+ }
+ for field, choices in repeated_choices.items():
+ if field in details:
+ normalized_details[field] = _require_choices(
+ details[field],
+ f"{preset_label}.{field}",
+ choices,
+ )
+ single_choices = {
+ "scope": SEMANTIC_SCOPES,
+ "text_capacity": SEMANTIC_TEXT_CAPACITIES,
+ "visual_weight": SEMANTIC_VISUAL_WEIGHTS,
+ }
+ for field, choices in single_choices.items():
+ if field in details:
+ normalized_details[field] = _require_choice(
+ details[field],
+ f"{preset_label}.{field}",
+ choices,
+ )
+ if "literal_only" in details:
+ normalized_details["literal_only"] = _require_bool(
+ details["literal_only"],
+ f"{preset_label}.literal_only",
+ )
+ for field in ("recommended_for", "avoid_for"):
+ if field in details:
+ normalized_details[field] = _require_string_list(
+ details[field],
+ f"{preset_label}.{field}",
+ )
+ normalized_presets[preset_name] = normalized_details
+ recommended_for = _require_string_list(
+ group.get("recommended_for"),
+ f"{label}.recommended_for",
+ )
+ avoid_for = _require_string_list(
+ group.get("avoid_for"),
+ f"{label}.avoid_for",
+ )
+ if not recommended_for or not avoid_for:
+ raise PresetShapeDataError(
+ f"{label}.recommended_for and avoid_for must not be empty"
+ )
+ return {
+ "id": _require_string(group.get("id"), f"{label}.id"),
+ "label": _require_string(group.get("label"), f"{label}.label"),
+ "office_category": category_id,
+ "office_category_label": self._category_by_id[category_id]["label"],
+ "scope": scope,
+ "roles": roles,
+ "relationships": relationships,
+ "directionality": directionality,
+ "aspects": aspects,
+ "text_capacity": _require_choice(
+ group.get("text_capacity"),
+ f"{label}.text_capacity",
+ SEMANTIC_TEXT_CAPACITIES,
+ ),
+ "visual_weight": _require_choice(
+ group.get("visual_weight"),
+ f"{label}.visual_weight",
+ SEMANTIC_VISUAL_WEIGHTS,
+ ),
+ "literal_only": _require_bool(
+ group.get("literal_only"),
+ f"{label}.literal_only",
+ ),
+ "recommended_for": recommended_for,
+ "avoid_for": avoid_for,
+ "presets": normalized_presets,
+ }
+
+ def _diverse_order(
+ self,
+ candidates: list[dict[str, object]],
+ ) -> list[dict[str, object]]:
+ candidates.sort(
+ key=lambda item: (
+ -int(item["score"]),
+ self._group_order[str(item["group"])],
+ self._preset_order[str(item["preset"])],
+ )
+ )
+ ordered: list[dict[str, object]] = []
+ scores = sorted({int(item["score"]) for item in candidates}, reverse=True)
+ for score in scores:
+ score_items = [item for item in candidates if item["score"] == score]
+ first_by_group: list[dict[str, object]] = []
+ remaining: list[dict[str, object]] = []
+ seen_groups: set[str] = set()
+ for item in score_items:
+ group_id = str(item["group"])
+ target = first_by_group if group_id not in seen_groups else remaining
+ target.append(item)
+ seen_groups.add(group_id)
+ ordered.extend(first_by_group)
+ ordered.extend(remaining)
+ return ordered
+
+
+@lru_cache(maxsize=1)
+def get_preset_shape_semantics() -> PresetShapeSemantics:
+ """Return the process-wide, lazily loaded bundled semantic catalog."""
+
+ return PresetShapeSemantics.bundled()
+
+
+def _require_dict(value: object, label: str) -> dict[str, object]:
+ if not isinstance(value, dict):
+ raise PresetShapeDataError(f"{label} must be a JSON object")
+ return value
+
+
+def _reject_unknown_fields(
+ value: dict[str, object],
+ label: str,
+ allowed: set[str],
+) -> None:
+ unknown = sorted(set(value) - allowed)
+ if unknown:
+ raise PresetShapeDataError(
+ f"{label} contains unsupported fields: {', '.join(unknown)}"
+ )
+
+
+def _require_list(value: object, label: str) -> list[object]:
+ if not isinstance(value, list):
+ raise PresetShapeDataError(f"{label} must be a JSON array")
+ return value
+
+
+def _require_string(value: object, label: str) -> str:
+ if not isinstance(value, str) or not value.strip():
+ raise PresetShapeDataError(f"{label} must be a non-empty string")
+ return value.strip()
+
+
+def _require_bool(value: object, label: str) -> bool:
+ if not isinstance(value, bool):
+ raise PresetShapeDataError(f"{label} must be a boolean")
+ return value
+
+
+def _require_choice(value: object, label: str, choices: Sequence[str]) -> str:
+ text = _require_string(value, label)
+ if text not in choices:
+ raise PresetShapeDataError(
+ f"{label} must be one of {', '.join(choices)}; got {text!r}"
+ )
+ return text
+
+
+def _require_choices(
+ value: object,
+ label: str,
+ choices: Sequence[str],
+) -> tuple[str, ...]:
+ values = _require_string_list(value, label)
+ if not values:
+ raise PresetShapeDataError(f"{label} must not be empty")
+ unknown = sorted(set(values) - set(choices))
+ if unknown:
+ raise PresetShapeDataError(
+ f"{label} contains unsupported values: {', '.join(unknown)}"
+ )
+ return values
+
+
+def _require_string_list(value: object, label: str) -> tuple[str, ...]:
+ items = _require_list(value, label)
+ values = tuple(
+ _require_string(item, f"{label}[{index}]")
+ for index, item in enumerate(items)
+ )
+ if len(values) != len(set(values)):
+ raise PresetShapeDataError(f"{label} contains duplicate values")
+ return values
+
+
+def _merge_strings(first: object, second: object) -> tuple[str, ...]:
+ merged: list[str] = []
+ for values in (first, second):
+ assert isinstance(values, tuple)
+ for value in values:
+ if value not in merged:
+ merged.append(value)
+ return tuple(merged)
+
+
+def _query_tokens(query: str) -> tuple[str, ...]:
+ normalized = _CAMEL_BOUNDARY_RE.sub(" ", query).casefold()
+ return tuple(
+ token
+ for token in _QUERY_TOKEN_RE.findall(normalized)
+ if token not in _QUERY_STOP_WORDS
+ )
+
+
+def _search_text(value: object) -> str:
+ if isinstance(value, str):
+ return _CAMEL_BOUNDARY_RE.sub(" ", value).casefold()
+ if isinstance(value, (list, tuple)):
+ return " ".join(_search_text(item) for item in value)
+ if isinstance(value, dict):
+ return " ".join(_search_text(item) for item in value.values())
+ return ""
+
+
+def _matches_query(details: dict[str, object], query_tokens: Sequence[str]) -> bool:
+ if not query_tokens:
+ return True
+ haystack = _search_text(details)
+ return all(token in haystack for token in query_tokens)
+
+
+def _query_score(
+ details: dict[str, object],
+ query_tokens: Sequence[str],
+ query: str,
+) -> int:
+ if not query_tokens:
+ return 0
+ haystack = _search_text(details)
+ matches = sum(1 for token in query_tokens if token in haystack)
+ if matches == 0:
+ return 0
+ score = matches * 4
+ normalized_query = " ".join(_query_tokens(query))
+ if normalized_query and normalized_query in haystack:
+ score += 10
+ preset = str(details["preset"])
+ if query.casefold() == preset.casefold():
+ score += 20
+ return score
+
+
+def _aspect_matches(values: object, requested: str) -> bool:
+ assert isinstance(values, tuple)
+ return requested in values or "flexible" in values
+
+
+def _capacity_matches(actual: str, requested: str) -> bool:
+ return _TEXT_CAPACITY_RANK[actual] >= _TEXT_CAPACITY_RANK[requested]
diff --git a/skills/ppt-master/scripts/preset_shape_svg.py b/skills/ppt-master/scripts/preset_shape_svg.py
index 3bd574fa..4f3cacc8 100644
--- a/skills/ppt-master/scripts/preset_shape_svg.py
+++ b/skills/ppt-master/scripts/preset_shape_svg.py
@@ -2,17 +2,21 @@
"""
PPT Master - Preset Shape SVG Fragment Tool
-List DrawingML presets or print compact canonical native-preset SVG groups to
-stdout for manual insertion into a hand-authored page or template.
+Browse and recommend DrawingML presets, or print compact canonical
+native-preset SVG groups to stdout for manual insertion into a hand-authored
+page or template.
Usage:
- python3 scripts/preset_shape_svg.py list [--search QUERY]
+ python3 scripts/preset_shape_svg.py list [--grouped] [--search QUERY]
python3 scripts/preset_shape_svg.py describe PRESET
+ python3 scripts/preset_shape_svg.py recommend --role ROLE [options]
python3 scripts/preset_shape_svg.py render PRESET --id ID --frame X Y W H
python3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASH
Examples:
- python3 scripts/preset_shape_svg.py list --search arrow
+ python3 scripts/preset_shape_svg.py list --grouped
+ python3 scripts/preset_shape_svg.py recommend --role spine \
+ --relationship order --directionality horizontal
python3 scripts/preset_shape_svg.py describe rightArrow
python3 scripts/preset_shape_svg.py render rightArrow --id next-step \
--frame 160 210 320 112 --fill "#2563EB" --stroke none
@@ -32,6 +36,16 @@ from typing import Sequence
from console_encoding import configure_utf8_stdio
from pptx_shapes import CONNECTOR_PRESET_TYPES, get_preset_registry
+from pptx_shapes.semantics import (
+ SEMANTIC_ASPECTS,
+ SEMANTIC_DIRECTIONALITY,
+ SEMANTIC_RELATIONSHIPS,
+ SEMANTIC_ROLES,
+ SEMANTIC_SCOPES,
+ SEMANTIC_TEXT_CAPACITIES,
+ SEMANTIC_VISUAL_WEIGHTS,
+ get_preset_shape_semantics,
+)
from pptx_to_svg.preset_authoring import render_preset_shape_fragment
@@ -73,7 +87,18 @@ def build_parser() -> argparse.ArgumentParser:
list_parser.add_argument(
"--search",
default="",
- help="Case-insensitive preset-name substring.",
+ help=(
+ "Case-insensitive preset-name substring; grouped output also "
+ "searches semantic text."
+ ),
+ )
+ list_parser.add_argument(
+ "--grouped",
+ action="store_true",
+ help=(
+ "Print a compact Office-category and semantic-group index with "
+ "one-line intent summaries and preset names as JSON."
+ ),
)
describe_parser = subparsers.add_parser(
@@ -82,6 +107,65 @@ def build_parser() -> argparse.ArgumentParser:
)
describe_parser.add_argument("preset", help="DrawingML preset name.")
+ recommend_parser = subparsers.add_parser(
+ "recommend",
+ help="Recall semantically matched preset candidates as JSON.",
+ )
+ recommend_parser.add_argument(
+ "--role",
+ action="append",
+ required=True,
+ choices=SEMANTIC_ROLES,
+ help="Required page role; repeat to allow multiple roles.",
+ )
+ recommend_parser.add_argument(
+ "--relationship",
+ action="append",
+ default=[],
+ choices=SEMANTIC_RELATIONSHIPS,
+ help="Required relationship fit; repeat to allow alternatives.",
+ )
+ recommend_parser.add_argument(
+ "--scope",
+ choices=("all", *SEMANTIC_SCOPES),
+ default="general",
+ help=(
+ "Semantic scope. The general default excludes literal-only, "
+ "flowchart, and navigation shapes."
+ ),
+ )
+ recommend_parser.add_argument(
+ "--directionality",
+ choices=SEMANTIC_DIRECTIONALITY,
+ help="Required direction or route character.",
+ )
+ recommend_parser.add_argument(
+ "--aspect",
+ choices=SEMANTIC_ASPECTS,
+ help="Required frame tendency; flexible candidates also match.",
+ )
+ recommend_parser.add_argument(
+ "--text-capacity",
+ choices=SEMANTIC_TEXT_CAPACITIES,
+ help="Minimum useful text capacity.",
+ )
+ recommend_parser.add_argument(
+ "--visual-weight",
+ choices=SEMANTIC_VISUAL_WEIGHTS,
+ help="Required visual-weight band.",
+ )
+ recommend_parser.add_argument(
+ "--query",
+ default="",
+ help="Optional English intent terms used to refine the recall set.",
+ )
+ recommend_parser.add_argument(
+ "--limit",
+ type=_positive_integer,
+ default=12,
+ help="Maximum returned candidates; default: 12.",
+ )
+
render_parser = subparsers.add_parser(
"render",
help="Print one canonical authored-preset <g> fragment to stdout.",
@@ -184,6 +268,13 @@ def main(argv: Sequence[str] | None = None) -> int:
registry = get_preset_registry()
if args.command == "list":
+ if args.grouped:
+ payload = get_preset_shape_semantics().grouped(args.search)
+ if payload["preset_count"] == 0:
+ print(f"No preset semantics match {args.search!r}", file=sys.stderr)
+ return 1
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+ return 0
query = args.search.casefold().strip()
names = [
name for name in registry.names
@@ -210,10 +301,26 @@ def main(argv: Sequence[str] | None = None) -> int:
"path_count": len(definition.paths),
"connection_site_count": len(definition.connections),
"has_text_rectangle": definition.text_rectangle is not None,
+ "semantics": get_preset_shape_semantics().describe(args.preset),
}
print(json.dumps(payload, ensure_ascii=False, indent=2))
return 0
+ if args.command == "recommend":
+ payload = get_preset_shape_semantics().recommend(
+ roles=args.role,
+ scope=args.scope,
+ relationships=args.relationship,
+ directionality=args.directionality,
+ aspect=args.aspect,
+ text_capacity=args.text_capacity,
+ visual_weight=args.visual_weight,
+ query=args.query,
+ limit=args.limit,
+ )
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+ return 0
+
if args.command == "render-batch":
try:
items = _read_batch_items(args.input)
@@ -260,6 +367,16 @@ def _parse_adjustments(values: Sequence[str]) -> dict[str, str]:
return adjustments
+def _positive_integer(value: str) -> int:
+ try:
+ number = int(value)
+ except ValueError as exc:
+ raise argparse.ArgumentTypeError("expected a positive integer") from exc
+ if number < 1:
+ raise argparse.ArgumentTypeError("expected a positive integer")
+ return number
+
+
def _style_from_args(args: argparse.Namespace) -> dict[str, str]:
return _style_from_values(
fill=args.fill,