| 1 | # SVG Icon Library |
| 2 | |
| 3 | This directory provides **12,027 high-quality SVG icons** across five libraries that can be directly embedded into SVG files generated by PPT Master. Default Strategist or the Quick Generate main agent chooses at most one primary library from the four stylistic libraries; the brand-logo library (`simple-icons`) is prepared as needed for real brands and may be used alone or alongside it. It is not a separate Confirm UI choice. |
| 4 | |
| 5 | Upstream versions, compatibility overlays, licenses, attribution, and trademark boundaries are recorded in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md). |
| 6 | |
| 7 | ## Libraries |
| 8 | |
| 9 | | Library | Style | Count | viewBox | Prefix | |
| 10 | |---------|-------|-------|---------|--------| |
| 11 | | `chunk-filled` | fill · compact, chunky 16px silhouettes | 641 | primarily `0 0 16 16` | `chunk-filled/` | |
| 12 | | `tabler-filled` | fill · bezier-curve forms (smooth, rounded contours) | 1,055 | `0 0 24 24` | `tabler-filled/` | |
| 13 | | `tabler-outline` | stroke / line | 5,138 | `0 0 24 24` | `tabler-outline/` | |
| 14 | | `phosphor-duotone` | duotone · single color + 0.2 opacity backplate (soft depth) | 1,518 | `0 0 256 256` | `phosphor-duotone/` | |
| 15 | | `simple-icons` | **brand logos** (real company / product marks) — single-color silhouettes, color in via `fill` | 3,675 | `0 0 24 24` | `simple-icons/` | |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Per-project icons folder |
| 20 | |
| 21 | This directory is the **global library**. The active resource owner copies chosen icons into the deck's own `<project>/icons/<lib>/` with `icon_sync.py` before SVG authoring: |
| 22 | |
| 23 | ```bash |
| 24 | python3 skills/ppt-master/scripts/icon_sync.py <project_path> tabler-outline/home tabler-outline/bulb simple-icons/github |
| 25 | ``` |
| 26 | |
| 27 | Missing names and a single selection batch that mixes the four stylistic libraries exit non-zero; `simple-icons` may coexist for real brand marks. Once files are under `<project>/icons/`, they form the prepared project asset pool and may be combined freely with user-provided, custom, or imported icons. `finalize_svg.py embed-icons` embeds **project-first**; its per-icon global fallback exists for legacy compatibility, not new asset discovery. |
| 28 | |
| 29 | **Custom icons**: drop your own `.svg` into `<project>/icons/<lib>/` (any `<lib>`, e.g. `custom/`) and reference it as `data-icon="<lib>/<name>"` — it embeds like any library icon. |
| 30 | |
| 31 | **Imported vectors**: `create-template` reserves the project-local `imported/` |
| 32 | namespace. Each extracted vector lives once at |
| 33 | `<workspace>/icons/imported/<name>.svg` and is referenced as |
| 34 | `data-icon="imported/<name>"`; do not duplicate it under `templates/` or use |
| 35 | `imported/` as a hand-curated style library. |
| 36 | |
| 37 | ## Usage |
| 38 | |
| 39 | Use placeholder syntax **during SVG generation**: |
| 40 | |
| 41 | ```xml |
| 42 | <!-- chunk-filled (compact, chunky — strong small-size legibility) --> |
| 43 | <use data-icon="chunk-filled/home" x="100" y="200" width="48" height="48" fill="#0076A8"/> |
| 44 | |
| 45 | <!-- tabler-filled (rounded, organic — lifestyle/health/home tone) --> |
| 46 | <use data-icon="tabler-filled/home" x="100" y="200" width="48" height="48" fill="#0076A8"/> |
| 47 | |
| 48 | <!-- tabler-outline (light, line-art — refined screen-only showcases) --> |
| 49 | <use data-icon="tabler-outline/home" x="100" y="200" width="48" height="48" fill="#0076A8"/> |
| 50 | |
| 51 | <!-- phosphor-duotone (soft depth — single color renders the backplate at 20% opacity) --> |
| 52 | <use data-icon="phosphor-duotone/house" x="100" y="200" width="48" height="48" fill="#0076A8"/> |
| 53 | |
| 54 | <!-- simple-icons (brand logo — used alone or alongside the deck's primary stylistic library) --> |
| 55 | <use data-icon="simple-icons/github" x="100" y="200" width="48" height="48" fill="#181717"/> |
| 56 | ``` |
| 57 | |
| 58 | **Attributes**: |
| 59 | - `data-icon` — `<library>/<icon-name>` (filename without `.svg`) |
| 60 | - `x`, `y` — Position |
| 61 | - `width`, `height` — Size (recommend 32–48px for legibility) |
| 62 | - `fill` — Color |
| 63 | |
| 64 | `data-icon` is case-sensitive because it resolves a real filename. Bundled library directories and basenames are canonical lowercase: use `tabler-outline/award`, not `tabler-outline/Award`. Custom icons retain the exact case of their files; the resolver intentionally does not lowercase identifiers. |
| 65 | |
| 66 | `finalize_svg.py` auto-embeds all placeholders during post-processing. To run manually: |
| 67 | |
| 68 | ```bash |
| 69 | python3 scripts/svg_finalize/embed_icons.py svg_output/*.svg |
| 70 | ``` |
| 71 | |
| 72 | --- |
| 73 | |
| 74 | ## Searching for Icons |
| 75 | |
| 76 | For a known basename, run `icon_sync.py` directly; it copies and validates without a per-file precheck. |
| 77 | |
| 78 | For an uncertain basename, search only the chosen stylistic library; use `simple-icons` only for a real brand mark. |
| 79 | |
| 80 | **Hard rule**: search by the drawable object, not the abstract concept. These libraries store things that can be drawn — `bulb`, `target`, `trending-up`, `alert-triangle` — so concept words such as `idea`, `goal`, `growth`, `warning`, or `innovation` return nothing in most of them. Translate the semantic into an object first, then search. |
| 81 | |
| 82 | **Reference — not a constraint**: one concept usually has several valid objects. Which one fits is a per-deck judgment of page register and visual style, not a fixed mapping. |
| 83 | |
| 84 | **Hard rule**: basenames are not portable across the four stylistic libraries; verify inside the selected one. `alert-*` exists in the tabler libraries but not in `phosphor-duotone`, which uses `warning-*`; `arrow-trend-*` exists in `chunk-filled`, while `tabler-outline` uses `trending-*`. |
| 85 | |
| 86 | ```bash |
| 87 | rg --files "skills/ppt-master/templates/icons/tabler-outline" -g '*chart*.svg' |
| 88 | rg --files "skills/ppt-master/templates/icons/simple-icons" -g '*github*.svg' |
| 89 | ``` |
| 90 | |
| 91 | Do not load a full index or enumerate broad keyword families. Re-pick from the narrow result and rerun the final batch until clean; never switch stylistic libraries for a missing generic icon. |
| 92 | |
| 93 | **Empty result** → translate the semantic into a different drawable object and search the same library again. When several translations stay empty, that semantic has no fit in the selected library: let another carrier take it — a chart, typography, or a shape — rather than forcing a loose icon. Widening the keyword family is not the fallback. |
| 94 | |
| 95 | --- |
| 96 | |
| 97 | ## Style Rules |
| 98 | |
| 99 | **No default library — actively choose based on the deck's visual needs.** Read the source material first, then pick the library whose visual character best serves the presentation. Each library has a distinct visual personality: |
| 100 | |
| 101 | - **`chunk-filled`** — **fill** style, designed as compact 16px silhouettes. Bold forms may combine rectilinear and curved geometry while staying highly legible at small sizes. Visual weight: heavy, solid, compact. |
| 102 | - **`tabler-filled`** — **fill** style, built from bezier curves and arcs (C/A). Smooth, rounded, organic contours; warmer and softer than `chunk-filled`. Visual weight: medium, approachable. |
| 103 | - **`tabler-outline`** — **stroke** style (line art, default stroke-width 2). Airy, refined, lightweight; uses negative space. Visual weight: light, elegant. Best for screen-only viewing since thin strokes may become hard to read when printed or projected. |
| 104 | - **`phosphor-duotone`** — **duotone** style; main shape at full opacity plus a backplate of the same color at 20% opacity, producing a soft sense of depth. Visual weight: medium, layered, contemporary. |
| 105 | |
| 106 | > **Two axes to consider when choosing**: |
| 107 | > 1. **Geometry**: compact silhouettes (`chunk-filled`) vs. rounded curves (`tabler-filled` / `phosphor-duotone`) vs. open strokes (`tabler-outline`) |
| 108 | > 2. **Visual weight**: heavy solid (`chunk-filled`) → medium solid (`tabler-filled`) → medium layered (`phosphor-duotone`) → light stroke (`tabler-outline`) |
| 109 | |
| 110 | **At most one primary bundled stylistic library per deck selection.** When generic icons are useful, pick one of `chunk-filled` / `tabler-filled` / `tabler-outline` / `phosphor-duotone` (home, chart, users, etc.). If it lacks an exact icon, find the closest available alternative within that library instead of selecting from another bundled stylistic library. This is a catalog-selection rule, not a prohibition on combining assets that already exist in the project's `icons/` directory. |
| 111 | |
| 112 | **Brand-logo exception (`simple-icons`).** `simple-icons` is **not a stylistic library**, does not participate in the "one library" rule, and is not presented as a user-facing library choice. Its job is brand recognition — Slack's purple, GitHub's cat, AWS's color — which is intentionally heterogeneous. Prepare it **alone or alongside** the chosen stylistic library only when actual content needs a company / product / service brand mark. Do **not** reach for it as a substitute when the chosen stylistic library lacks a generic icon. |
| 113 | |
| 114 | | Use `simple-icons` for | Do NOT use `simple-icons` for | |
| 115 | |------------------------|-------------------------------| |
| 116 | | Customer / partner / ecosystem logos on a "trusted by" page | Generic concepts (home, chart, settings, etc.) | |
| 117 | | Tech stack icons on architecture / integration diagrams | Replacing a missing icon in `chunk-filled` / `tabler-*` / `phosphor-duotone` | |
| 118 | | Social media handles in a footer | Decorative / illustrative purposes | |
| 119 | |
| 120 | ⚠️ During bundled selection, choose generic icons from only one of the four **stylistic** libraries. Prepare `simple-icons` independently when real brand marks are needed. Project-local assets are already prepared material and are not subject to a runtime mixing ban. |
| 121 |