GlyphPact

GlyphPact

The deterministic SVG-to-Flutter icon compiler.

Website · Stable codepoints · Flutter guide · Changelog

GlyphPact turns a directory of SVG files into a validated OpenType/CFF icon font and a const Dart IconData API. It keeps codepoints stable across pack changes, records what happened to every source, and refuses to hide fidelity loss.

The default policy is strict:

• lossless SVG normalization happens automatically
• deterministic approximation requires explicit permission
• omission requires separate explicit permission
• malformed, unsafe, unknown, or resource-exhausting input always fails
• a failed build never replaces the last valid generated output

GlyphPact is a CLI compiler. There is no website upload step, no desktop project file, and no server that receives your artwork.

Quick start

GlyphPact requires Python 3.10 or newer. Generated providers require Dart 3 or newer.

Install the latest stable release from PyPI with uv:

uv tool install glyphpact

Upgrade an existing installation when a new release is available:

uv tool upgrade glyphpact

Pin the version in CI or any other reproducible environment:

uv tool install glyphpact==1.0.1

Compile a Flutter icon pack:

glyphpact assets/icons \
  --output lib/generated/app_icons \
  --name AppIcons

Or run the checked-in example from a source checkout:

uv sync --locked
uv run glyphpact --config examples/icon_font.json

The example SVGs are original MIT-licensed fixtures. See examples/README.md.

Claude Code and Codex plugin

The optional glyphpact plugin gives Claude Code and Codex a project-aware skill plus four local MCP tools:

• audit an SVG file or directory once, then page a stable local snapshot
• build the output declared by a checked-in config
• check committed output for staleness without rewriting generated artifacts
• page through large machine-readable reports

The plugin bundles the exact GlyphPact 1.0.1 wheel, starts its MCP server automatically, and does not require a source checkout or global GlyphPact installation. Add this repository as a marketplace, then install the plugin.

Claude Code:

claude plugin marketplace add omar-hanafy/glyphpact
claude plugin install glyphpact@glyphpact

Codex:

codex plugin marketplace add omar-hanafy/glyphpact
codex plugin add glyphpact@glyphpact

Start a new session after installation. Do not add a duplicate personal MCP configuration. See the plugin guide for its runtime requirements, mutation boundary, and maintainer validation flow.

An audit response with findings includes a snapshot.id and findings.nextOffset. Pass that ID back to audit_icon_pack with successive offsets instead of recompiling the pack. Release it explicitly with release_snapshot=true; otherwise the private local snapshot expires automatically.

What gets generated

For --name AppIcons, GlyphPact owns the selected output directory and writes:

.glyphpact.json           output ownership marker
ATTRIBUTION.md            artwork licensing and provenance
fonts/AppIcons.otf        validated OpenType/CFF font
layer_fonts/layer_*.otf   optional solid-alpha paint-order layers
app_icons.dart            const Flutter IconData provider
iconfont.lock.json        stable codepoint and provenance registry
iconfont.report.json      deterministic machine-readable build report

Register the font in the Flutter app's pubspec.yaml. Asset paths are relative to that file:

flutter:
  fonts:
    - family: AppIcons
      fonts:
        - asset: lib/generated/app_icons/fonts/AppIcons.otf

Import the generated provider and use it like any other Flutter icon:

Icon(
  AppIcons.back,
  semanticLabel: 'Back',
)

The provider follows Flutter's tree-shaking contract:

import 'package:flutter/widgets.dart' as flutter;

@flutter.staticIconProvider
abstract final class AppIcons {
  static const flutter.IconData back = flutter.IconData(...);
}

When the font is shipped by a Dart package, pass its package name:

glyphpact assets/icons \
  --output lib/generated/app_icons \
  --name AppIcons \
  --font-package my_icon_package