playbooks

home / skills / openclaw / skills / sfsymbol-generator

sfsymbol-generator skill

/skills/svkozak/sfsymbol-generator

This skill generates a complete SF Symbol .symbolset from an SVG, creating Assets.xcassets entries and Contents.json for Xcode projects.

npx playbooks add skill openclaw/skills --skill sfsymbol-generator

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.7 KB
---
name: sfsymbol-generator
description: Generate an Xcode SF Symbol asset catalog .symbolset from an SVG. Use when you need to add a custom SF Symbol (build-time) by creating the symbolset folder, Contents.json, and SVG file.
---

# SF Symbol Generator

## Usage

You can override the default asset catalog location with `SFSYMBOL_ASSETS_DIR`.

### Raw symbolset (no template injection)

```bash
./scripts/generate.sh <symbol-name> <svg-path> [assets-dir]
```

- `symbol-name`: Full symbol name (e.g., `custom.logo`, `brand.icon.fill`).
- `svg-path`: Path to the source SVG file.
- `assets-dir` (optional): Path to `Assets.xcassets/Symbols` (defaults to `Assets.xcassets/Symbols` or `SFSYMBOL_ASSETS_DIR`).

### Template-based symbolset (recommended)

```bash
./scripts/generate-from-template.js <symbol-name> <svg-path> [template-svg] [assets-dir]
```

- `template-svg` (optional): SF Symbols template SVG to inject into (defaults to the first `.symbolset` SVG found in `Assets.xcassets/Symbols`, otherwise uses the bundled skill template).

## Example

```bash
./scripts/generate-from-template.js pi.logo /Users/admin/Desktop/pi-logo.svg
```

## Requirements

- SVG must include a `viewBox`.
- Use **path-based** shapes (paths are required; rects are supported and converted, but other shapes should be converted to paths).
- Prefer **filled** shapes (no strokes) to avoid thin artifacts.

## Workflow

1. Validates the SVG path and viewBox.
2. Computes path bounds and centers within the SF Symbols template margins.
3. Injects the paths into the SF Symbols template (Ultralight/Regular/Black).
4. Creates `<symbol-name>.symbolset` inside the asset catalog Symbols folder.
5. Writes a matching `Contents.json`.

Overview

This skill generates an Xcode SF Symbol asset catalog .symbolset from a source SVG so you can add custom SF Symbols at build time. It creates the .symbolset folder, writes a matching Contents.json, and places the processed SVG into your Assets.xcassets/Symbols folder. Use the template-based option to inject artwork into SF Symbols templates for consistent weights and alignment.

How this skill works

The tool validates the input SVG (requires viewBox and path-based shapes), computes path bounds, and recenters artwork to fit SF Symbols template margins. It can inject paths into a template SVG for multiple weights (Ultralight/Regular/Black) or produce a raw symbolset without template injection. Finally it writes the <symbol-name>.symbolset directory and Contents.json to the target Symbols asset catalog.

When to use it

  • You need a custom SF Symbol added to an app at build time.
  • You have an SVG you want converted into an Xcode .symbolset for use in asset catalogs.
  • You want consistent sizing and alignment across SF Symbol weights using a template.
  • You prefer automating symbol creation as part of a build or design-to-code workflow.
  • You need to place symbols into a specific Assets.xcassets/Symbols location.

Best practices

  • Provide SVGs with a viewBox and convert non-path shapes to paths before running the tool.
  • Use filled shapes (no strokes) to avoid thin stroke artifacts when rendered at small sizes.
  • Prefer the template-based generate-from-template mode to ensure correct margins and weight variants.
  • Name symbols using the full symbol style (e.g., custom.logo or brand.icon.fill) to keep catalog organization clear.
  • Set SFSYMBOL_ASSETS_DIR to override the default Symbols folder for CI or custom project layouts.

Example use cases

  • Automate converting a designer-provided SVG into an Xcode-compatible .symbolset during CI builds.
  • Inject a company logo into SF Symbols templates so it lines up correctly with system icons at multiple weights.
  • Create a set of branded icons as symbol assets to distribute across multiple apps consistently.
  • Quickly produce a raw .symbolset for a single-use custom icon without template injection.

FAQ

What SVG requirements must I follow?

The SVG must include a viewBox and use path-based shapes. Rectangles are supported but other primitive shapes should be converted to paths to ensure accurate conversion.

When should I use the template-based generator?

Use the template-based mode when you need consistent alignment and weight variants. It injects artwork into SF Symbols templates (Ultralight/Regular/Black) and yields better visual harmony with system symbols.