petrowsky/icon-swap

Icon Swap

Replace embedded SVG icons in FileMaker layout objects with icons from open-source libraries. Supports both fill-based and stroke-based icon libraries — stroke-based icons are automatically converted to FM-compatible filled SVGs via a rasterise-then-trace pipeline.

---

Step 0: Ensure dependencies

Always available (no deps)

The icon extraction and XML replacement functionality uses stdlib Python only. Swapping icons from fill-based libraries (Heroicons solid, MDI, Bootstrap Icons, Phosphor, Tabler filled, Ionicons filled) works without any extra dependencies.

Required for stroke-based libraries

Stroke-based libraries (Lucide, Heroicons outline, Tabler, Iconoir, Ionicons outline) require conversion dependencies. Check first:

python3 agent/scripts/fm_svg_convert.py --check-deps

If deps are missing, guide the developer through setup:

Stroke-to-fill conversion requires additional dependencies.

These are needed because FileMaker button icons only support filled shapes — stroke-based SVG libraries (like Lucide) must be converted.

Option A: venv in the project folder (recommended)

python3 -m venv agent/.venv
source agent/.venv/bin/activate
pip install cairosvg Pillow

System dependency (potrace):

brew install potrace   # macOS

Once set up, run commands with the venv active, or prefix with agent/.venv/bin/python3.

If the developer declines, suggest a fill-based alternative library instead:

• Lucide (stroke) → suggest Heroicons solid or Bootstrap Icons as fill-based alternatives
• Tabler (stroke) → suggest Tabler filled or MDI

---

Step 1: Determine input source

Same as icon-extract skill — the input can come from:

A) File in sandbox:

python3 agent/scripts/fm_icon_extract.py agent/sandbox/<filename>.xml --json

B) Clipboard via companion server:

curl -s http://local.hub:8765/clipboard | python3 -c "
import json, sys
data = json.load(sys.stdin)
if data.get('success'):
    with open('agent/sandbox/_clipboard_input.xml', 'w') as f:
        f.write(data['xml'])
    print('Saved clipboard content to agent/sandbox/_clipboard_input.xml')
else:
    print('ERROR:', data.get('error', 'Unknown error'), file=sys.stderr)
    sys.exit(1)
"

Fall back to host.docker.internal:8765 if local.hub:8765 is unreachable.

C) Developer pastes XML directly — save to sandbox and proceed.

---

Step 2: Extract and catalogue current icons

Run extraction:

python3 agent/scripts/fm_icon_extract.py agent/sandbox/<input>.xml --json

Also save individual SVGs for visual reference:

python3 agent/scripts/fm_icon_extract.py agent/sandbox/<input>.xml --output-dir agent/sandbox/icons_current/

Present the catalogue to the developer:

| # | Label | Current Icon | Suggested Replacement | Preview | |---|-------|--------------|-----------------------|---------| | 0 | Dashboard | grid/table (filled) | layout-dashboard | view | | 1 | Companies | building (filled) | building-2 | view | | 2 | Contacts | person (filled) | contact | view |

Replace the preview URLs with the correct pattern for the target library (see URL patterns in Step 3).

---

Step 3: Build the icon mapping

Auto-matching (attempt first)

Use the button name and label to suggest matching icons from the target library. Common mappings for business apps:

| Label pattern | Lucide suggestion | Heroicons suggestion | |---|---|---| | Dashboard | layout-dashboard | squares-2x2 | | Company/Companies | building-2 | building-office-2 | | Contacts | contact | user-group | | Leads | target | flag | | Opportunities | trending-up | chart-bar | | Quotes/Estimates | file-text | document-text | | Orders | shopping-cart | shopping-cart | | Purchase Orders/POs | clipboard-list | clipboard-document-list | | Shipments | truck | truck | | Receiving | package-check | inbox-arrow-down | | Returns | undo-2 | arrow-uturn-left | | Work Orders | wrench | wrench-screwdriver | | Reports | bar-chart-3 | chart-bar | | Settings/Setup | settings | cog-6-tooth | | Builds | hammer | wrench | | Inventory | warehouse | archive-box | | Invoices | receipt | document | | Payments | credit-card | credit-card | | Calendar/Schedule | calendar | calendar | | Search | search | magnifying-glass | | Users | users | users | | Home | home | home | | Email | mail | envelope | | Phone | phone | phone | | Notes | sticky-note | document |

Present mapping for approval

Always present the proposed mapping and ask the developer to confirm or override before proceeding. Include a Preview column with a direct link to the icon on the library's website so the developer can visually verify each choice.

Icon preview URL patterns by library:

| Library | URL pattern | |---|---| | Lucide | https://lucide.dev/icons/{name} | | Heroicons (outline/solid) | https://heroicons.com/outline#{name} or https://heroicons.com/solid#{name} | | Tabler | https://tabler.io/icons/icon/{name} | | Phosphor | https://phosphoricons.com/icons/{name} | | Bootstrap | https://icons.getbootstrap.com/icons/{name}/ | | Iconoir | https://iconoir.com/icons/{name} | | MDI | https://pictogrammers.com/library/mdi/icon/{name}/ | | Ionicons | https://ionic.io/ionicons/ionicons/#{name} |

Example presentation:

Proposed icon mapping (library: Lucide)

| # | Label | Replacement icon | Preview | |---|-------|-----------------|---------| | 0 | Dashboard | layout-dashboard | view | | 1 | Companies | building-2 | view | | ... | | | |

Edit any names, or reply go to proceed.

Developer-provided mapping

If the developer provides explicit icon names (one-for-one list), use those directly. The developer may provide them as:

• A numbered list: 0: home, 1: building, 2: users
• A comma-separated list (positional): home, building, users, target, ...
• A JSON object: {"Dashboard": "layout-dashboard", "Companies": "building-2"}

---

Step 4: Fetch and convert replacement icons

For each icon in the mapping:

4a. Fetch from library

python3 agent/scripts/fm_svg_convert.py --fetch lucide:layout-dashboard --fm -o agent/sandbox/icons_new/layout-dashboard.svg

If the icon is not found (404), inform the developer and ask for an alternative name. Common issues:

• Plural vs singular (users vs user)
• Hyphenation (shopping-cart vs shoppingcart)
• Library-specific naming (file-text in Lucide vs document-text in Heroicons)

4b. Convert stroke-based icons

If the library is stroke-based, the --fm flag on fm_svg_convert.py handles conversion automatically. If conversion deps are not available, the script will error — fall back to a fill-based library.

4c. Format for FileMaker

Whether fetched as fill-based or converted from stroke, the final SVG must have:

• <g class="fm_fill"> wrapping all shape elements
• viewBox="0 0 24 24" (or matching dimensions)
• width and height attributes with px units
• No stroke attributes on any element
• No fill="none" on shape elements
• XML declaration: <?xml version="1.0" encoding="utf-8"?>

The format_for_fm() function in fm_svg_convert.py handles this, and is also invoked by the --fm flag.

For fill-based libraries that don't need stroke conversion, use the formatting function directly:

from agent.scripts.fm_svg_convert import format_for_fm
formatted = format_for_fm(svg_text)

Or from the CLI:

python3 -c "
import sys; sys.path.insert(0, '.')
from agent.scripts.fm_svg_convert import format_for_fm, fetch_icon
svg = fetch_icon('heroicons-solid', 'building-office-2')
print(format_for_fm(svg))
" > agent/sandbox/icons_new/building-office-2.svg

---

Step 5: Build the replacement XML

Use the replace_icons_in_file function from fm_icon_extract.py:

python3 -c "
import sys; sys.path.insert(0, '.')
from agent.scripts.fm_icon_extract import replace_icons_in_file

# Read all replacement SVGs
replacements = {}
# Map: index -> path to replacement SVG
mapping = {
    0: 'agent/sandbox/icons_new/layout-dashboard.svg',
    1: 'agent/sandbox/icons_new/building-2.svg',
    # ...
}
for idx, path in mapping.items():
    with open(path) as f:
        replacements[idx] = f.read()

replace_icons_in_file(
    'agent/sandbox/<input>.xml',
    replacements,
    'agent/sandbox/<input>_updated.xml'
)
"

The function:

• Updates the <HexData> with the new SVG encoded as uppercase hex
• Updates the <Stream size=""> attribute to match the new byte count
• Preserves the GLPH stream and all other XML structure unchanged
• Writes to _updated suffix file

---

Step 6: Deploy or deliver

If the input came from clipboard, write the updated XML back to clipboard:

python3 agent/scripts/clipboard.py write agent/sandbox/<input>_updated.xml

Then instruct the developer:

The updated layout object is on your clipboard. In FileMaker Layout Mode:

1. Delete the original button bar
2. Cmd+V to paste the updated version

If the input came from a file, inform the developer:

The updated XML is at agent/sandbox/<input>_updated.xml. You can load it to clipboard with:

python3 agent/scripts/clipboard.py write agent/sandbox/<input>_updated.xml

---

Supported icon libraries

| Library | ID | Style | Conversion needed? | |---|---|---|---| | Lucide | lucide | stroke | Yes | | Heroicons (outline) | heroicons-outline | stroke | Yes | | Heroicons (solid) | heroicons-solid | fill | No | | Tabler Icons | tabler | stroke | Yes | | Tabler Icons (filled) | tabler-filled | fill | No | | Phosphor Icons | phosphor | fill | No | | Bootstrap Icons | bootstrap | fill | No | | Iconoir | iconoir | stroke | Yes | | Material Design Icons | mdi | fill | No | | Ionicons (outline) | ionicons-outline | stroke | Yes | | Ionicons (filled) | ionicons-filled | fill | No |

Browse icons at their respective websites to find names:

• Lucide: https://lucide.dev/icons
• Heroicons: https://heroicons.com
• Tabler: https://tabler.io/icons
• Bootstrap: https://icons.getbootstrap.com
• MDI: https://materialdesignicons.com
• Phosphor: https://phosphoricons.com
• Iconoir: https://iconoir.com
• Ionicons: https://ionic.io/ionicons

---

Troubleshooting

• Icon not found (404): Check the exact icon name on the library's website. Names are kebab-case.
• Conversion produces blank SVG: The render size may be too small for fine details. Try --render-size 2048.
• Converted icon looks rough: Potrace tracing is lossy. For critical icons, consider using a fill-based library instead, or manually adjusting the traced SVG.
• FM doesn't show the icon: Verify the SVG has <g class="fm_fill"> and no stroke attributes. Check that the XML declaration is present.
• Size mismatch: The stream_size must match the actual byte count of the hex-decoded SVG. The replacement function handles this automatically.