Source tools for the Font.Garden font projects. The tools read the UFO
masters of a project, report their mark colors, check glyphs against the
design targets, check source changes before review, lint the outlines,
evaluate drafting methods and list the reviews of drafts from the Git
history. proof-web shows a build beside reference fonts in a browser.
Most tools only read the UFO sources. The commands that change them say so: edit, place-anchors --write, build-accented-letters --write and customize.
The package installs one command, fgtools.
The build uses fontc, the Rust compiler of Google Fonts that replaces
fontmake, through gftools builder. Quality control of a build uses
diffenator3: fgtools diff compares a build with the build of
another revision, and diff --fontmake compares fontc with fontmake.
The package was extracted from the scripts of Virtua Grotesk, which is the reference project.
The package needs Python 3.13 or later. Install it into the virtual environment of the font project:
.venv/bin/python -m pip install -e /path/to/fgtools
.venv/bin/fgtools install-toolsinstall-tools installs the pinned fontc and Fontspector release binaries
into the same environment, after a check of their SHA-256 checksums. It also
compiles DesignBot from a pinned commit with Cargo, which needs the cargo
command and, on Linux, the fontconfig headers. A second run skips a tool that
is already installed at its pinned version. It names ffmpeg and runebender
if they are missing. build
and diff also need gftools, from the requirements of the project.
check-design and check-changes --proof need the Runebender binary. Set
RUNEBENDER to its path if it is not on PATH.
A project is a directory that contains sources/config.yaml, the gftools
builder configuration. The commands use the current directory or the nearest
parent that contains that file. The tools read these files:
| File | Use |
|---|---|
sources/config.yaml |
sources names the designspace. outputDir is the fonts directory. Both are relative to sources/. |
| The designspace | The masters are its <source> elements, in order. |
CONTEXT.md |
The design rules of the font. The tools read its toml code blocks as one TOML document: grid, stroke targets (targets), the weights that draft-weights drafts (weights), mark colors (colors) and the first date that corrections lists ([corrections] start). |
sources/held-out-glyphs.toml |
The cases of evaluate-drafting. |
sources/proof-samples.toml |
Optional. The text samples of proof-web. |
reference-fonts/ |
The TTF and OTF files that proof-web shows beside the font. Keep the license of each font with it, and keep the folder out of Git. |
The name of a master is the stylename attribute of its <source>. Without
that attribute, it is the part of the UFO file name after the last -,
without .ufo. For example, Family-Bold.ufo gives Bold. The first source
is the default master.
Glyph names give the script of a glyph: a name that contains -ar is
Arabic, -hb is Hebrew, and every other glyph is in the group "Latin and
other". These are the suffixes of the Glyphs naming convention.
check-changes and corrections read the Git history. The project root must
be the top level of its Git repository.
| Command | Use |
|---|---|
fgtools status [--print] |
Write STATUS.md in the project root from the mark colors. --print prints it only. |
fgtools queue |
Rank the glyphs that most composites wait on. The same as check-design --queue. |
fgtools check-design GLYPH ... |
Check glyphs against the grid and stroke targets, and their color in text against the reference fonts. Also --not-green, --green, --ready, --observe, --json. |
fgtools check-changes [--base REV] [--glyphs "a b"] [--allow-other] [--proof DIR] |
Compare the sources with a base revision (default main). Exit status 1 when a green glyph changed or a changed contour glyph is not purple. |
fgtools lint-glifs [GLYPH ...] |
Find structural faults in the GLIF files and differences between the masters. |
fgtools lint-curves MASTER (GLYPH ... | --all) [--joins] |
Crest centering, tension breaks, inflections and join continuity in one master. |
fgtools evaluate-drafting prepare TASK RUN |
Copy the sources into RUN/sources and hide or move the held-out glyphs. TASK is redraw, bold, repair or relatives. |
fgtools evaluate-drafting score RUN |
Score the drafts in RUN against the project sources. |
fgtools evaluate-drafting compare RUN RUN |
Compare the scores of two runs. |
fgtools evaluate-drafting run TASK RUN --harness NAME [--model M] [--max-time S] |
Prepare RUN, run an agent harness in it without a person, record its time, exit status and cost, and score it. The harnesses and their permissions are in fgtools/harnesses.toml: Claude Code, Codex and OMP. |
fgtools evaluate-drafting table RUN ... |
One line for each run: harness, model, task, overlap, distance, compatible glyphs, time and cost. |
fgtools report-grid-levels [--master NAME] [--glyphs "NAMES"] |
Count the points on the 8-unit grid, on the 2-unit grid only, and off both, by script and mark color, with the advances and kerning values off the 8-unit grid. With --glyphs, list the points of each named glyph that are off the 8-unit grid. |
fgtools check-accents [--master NAME] [--tolerance UNITS] [--all] |
List the accented letters whose mark is not where the other accented letters predict, or not where the anchors of its parts are. See Accent placement. |
fgtools place-anchors [--set NAME] [--master NAME] [--include-green] [--write] |
Add the top, bottom, _top and _bottom anchors that are missing on the base letters and the marks of a set of accented letters. See Accented letters. |
fgtools build-accented-letters [--set NAME] [--characters TEXT] [--glyphs "NAMES"] [--replace-drafts] [--write] |
Add the accented letters of a set as purple composites, in every master. |
fgtools render-accent-proofs [--master NAME] [--glyphs "NAMES"] [--references DIR] [--out DIR] |
Draw each accented letter beside the reference fonts, and measure it against them. |
fgtools evaluate-accent-placement [FONT.ttf ...] [--letters] |
Test the accent placement methods on compiled fonts, where the positions of the designer are known. Without fonts, it uses one upright font of each family of the reference fonts. |
fgtools fetch-reference-fonts [DIRECTORY] [--family NAME ...] |
Download the shared OFL reference fonts from Google Fonts. With --project, get the families that CONTEXT.md lists into reference-fonts/ of the project. |
fgtools draft-weights [NAME ...] [--build] |
Draft the masters of more weights, for example Thin and Black, from two masters. Each [weights.<name>] table of CONTEXT.md names the two masters and gives the vertical stem and the horizontal stroke of each master and of the weight. Each coordinate is calculated on the line through its two values, with one position for x and one for y. The drafts go to output/weights/ with a designspace of all masters, every drafted glyph is purple, and sources/ does not change. The report lists the glyphs that are not compatible in the two masters and the glyphs with a contour that turned inside out. --build compiles a variable font with fontc. |
fgtools corrections [--all] |
List the reviews of purple drafts from the Git history. |
fgtools build [--compiler fontmake] |
Remove the fonts directory and build the fonts with gftools builder and fontc, from a temporary copy of the sources that has one glyph order in all masters. --compiler fontmake builds with fontmake. |
fgtools qa [--checks all|google-fonts|fontgarden | --package DIR] |
Run Fontspector with the Font.Garden profile (the Google Fonts profile plus the Font.Garden checks: em size, grid, vendor ID, license, ink, marks, Arabic joins, Hebrew marks, precomposed letters and STAT weight) and the checks of the project in sources/fontspector_checks.py, on the built fonts. --checks google-fonts runs only the Google Fonts checks, and --checks fontgarden only the Font.Garden checks and the checks of the project. It leaves out the known faults in [qa.exclude] of CONTEXT.md; --package runs every check on a google/fonts package. Reports go to output/qa/<checks>/. |
fgtools render "GLYPHS" [--master NAME] [--beside "GLYPHS"] [--base REV] [--out FILE] |
Draw glyphs large in one PNG: the change since REV (default main), the filled glyph, its points and handles, other glyphs of the project and the same character in each reference font, all at one scale and baseline. Writes to output/render/. Under each glyph it sets the glyph in a block of text, sharp and blurred, beside the same block in the reference font with the median color, and gives the color as a number. |
fgtools media [FORMAT ...] [--canvas NAME] [--lattice] [--specimen] [--proof] [--list] [--copy FORMAT] |
Render the specimens and the marketing media of the project: each format on each of its canvases, into output/media/, laid out on the lattice of the typeface and checked. --specimen writes the print specimen, and --proof writes the print proof. See Specimens and marketing media. |
fgtools site |
Collect the print specimen, output/proof/proof.pdf and the renders of output/media/ into output/site/, with an index page. The CI of a project publishes the folder on GitHub Pages. |
fgtools measure-picture PICTURE [--text CHARACTERS] |
Measure the glyphs in a picture of one line of text, for example a screenshot of another font: width, top, bottom and strokes of each glyph, in cap heights and H stems when the text has an H. |
fgtools edit GLYPH [--master NAME] set-coordinate | set-sidebearings | copy |
Change a glyph with a calculated operation: move an edge to a coordinate, set the sidebearings, or copy a donor with a mirror. A second run changes nothing. It marks the glyph purple and refuses a green glyph. |
fgtools check-repository |
Check that every tracked file has a place in the layout of a Font.Garden project, that no file is larger than 500 KB, and that no document names a file or a make target that does not exist. |
fgtools diff [--base REV | --fontmake] |
Build the sources of the working tree and of REV (default main), or with fontc and fontmake, and compare the builds with diffenator3. HTML reports go to output/diff/. Exit status 1 when a glyph or word image differs. |
fgtools customize --family NAME --designer NAME --email ADDRESS [--repository URL] |
Rename a project made from the project template: the family name in the sources, the documents and the file names. |
fgtools install-tools |
Install the pinned fontc, Fontspector and DesignBot binaries next to the Python of the environment. |
fgtools proof-web [--current | --snapshot DIR | --directory DIR] [--port N] [--check] |
Serve the font beside reference-fonts/ in a browser. See Web proof. |
fgtools proof-web prepare --comparison FILE --output-dir DIR |
Prepare a Before and Candidate snapshot from fixed font files. |
fgtools proof-web render-detail --text TEXT --weight N --output FILE |
A DesignBot PNG of one sample in each font of the proof. Needs DesignBot, from install-tools. |
fgtools COMMAND --help lists the arguments of a command. Each command
runs one module, so python -m fgtools.status --print is the same as
fgtools status --print.
| Module | Command |
|---|---|
fgtools.status |
status |
fgtools.check_design |
check-design, queue |
fgtools.check_changes |
check-changes |
fgtools.glif_lint |
lint-glifs |
fgtools.curve_lint |
lint-curves |
fgtools.evaluate_drafting |
evaluate-drafting |
fgtools.draft_weights |
draft-weights |
fgtools.benchmark |
evaluate-drafting run, evaluate-drafting table |
fgtools.grid_levels |
report-grid-levels |
fgtools.accent_placement |
check-accents, evaluate-accent-placement |
fgtools.accented_letters |
place-anchors, build-accented-letters |
fgtools.accent_proofs |
render-accent-proofs |
fgtools.reference_fonts |
fetch-reference-fonts |
fgtools.list_corrections |
corrections |
fgtools.build_source_snapshot |
build |
fgtools.qa, fgtools.fontspector_plugin, fgtools.shaped_font |
qa |
fgtools.check_repository |
check-repository |
fgtools.render_glyphs |
render |
fgtools.measure_picture |
measure-picture |
fgtools.site |
site |
fgtools.media |
media |
fgtools.media_layout |
the lattice, the typesetter and the checks of media |
fgtools.text_color |
the color of a glyph in text, for render and check-design |
fgtools.edit_glyph |
edit |
fgtools.diff |
diff |
fgtools.install_tools |
install-tools |
fgtools.customize |
customize |
fgtools.proof_web |
proof-web. The web app is in fgtools/proof_web/app/. |
fgtools.source_inventory |
None. Other modules import it to read glyph records. |
fgtools.project |
None. It finds the project and reads its layout. |
An accented letter is a composite of a base letter and a mark, for example
Aacute = A + acute. Unicode decomposition gives the parts. The module
predicts the offset of the mark with three methods:
| Method | Uses | Top marks within 0.8% of the em |
|---|---|---|
outlines |
The outlines only: the mark is centered on the top of the base and keeps its drawn height over the x-height or the cap height. | 33% |
calibrated |
The outlines, with the constant of each mark from the other letters that use it. | 67% |
anchors |
The base anchor and the mark anchor that the other accented letters imply, fitted with medians. | 99% |
The numbers are from evaluate-accent-placement on one upright font of each
of the 9 families of the reference fonts, 2162 marks, on
2026-11-14. Each letter
is predicted without itself. The anchors method needs another mark on the
same base and another base with the same mark; it predicts 86% of the marks.
Bottom marks (cedilla, ogonek, comma accent) are within 0.8% for 72% of the
marks with the anchors method, because an ogonek joins a stroke and is not
centered.
The rules are for Latin letters with one mark. A caron on d, t, l and L is left out, because it is drawn as an apostrophe beside the letter.
check-accents uses the anchors method on the masters of the project, with
the calibrated method where the first has no prediction. It does not
change the sources. A listed letter is a reason to look: a mark on the stem
of L is correct and is not where the centered marks predict.
Three commands do the work on accented letters, and a review closes it:
place-anchorsadds the anchors that are missing. An anchor that is in the sources is the designer's and does not change. A missing anchor is fitted to the accented letters that are in the sources (theanchorsmethod), or comes from the outline for a glyph that no accented letter uses. Purple and red accented letters are not evidence. Green glyphs are left out without--include-green.build-accented-lettersadds each accented letter of a set that is not in the sources, as a purple composite at the offsetanchor of the base - anchor of the mark, in every master, and adds it tocontents.plistandpublic.glyphOrder. The sets are infgtools/accented_letters.toml. The default,google-fonts-latin-core, has the 145 accented letters of the Google Fonts Latin Core glyph set.--replace-draftsalso sets the components of the purple accented letters again. The command lists the letters that it does not build: two marks, the caron of d, t, l and L, and the comma accent of g.render-accent-proofsdraws each accented letter of the project beside the same character in each family of the reference fonts, at the weight of the master, and writesreview.json. A letter gets a finding when its mark is outside the range of the reference fonts, not where the other accented letters of the project predict, or not where the anchors of its parts are. The sheets show every letter, the letters with findings first.
Both writing commands print their list and change nothing without --write.
The review is the work of an agent that can read images, or of the designer.
The task contract accented-letters.md and the skill accent-review of the
project template give
the method and the rules of a correct accented letter. The reviewer gives
each letter a verdict: correct, fault or designer. A finding is a
reason to look. It is not a fault, because the reference fonts do not
dictate the design.
A trial on Virtua Grotesk on 2026-11-15 removed all 145 accented letters
from a copy of both masters and built them again. With the anchors of the
designer in place, 269 of 280 composites (96%) were within 8 units of the
position of the designer. The other 11 are letters that the designer placed
away from the anchors, mostly ogoneks. With the top and bottom anchors
also removed, 60% were within 8 units and 80% within 20 units: the vertical
position was correct for all but one letter, and the horizontal position of
acute, grave, cedilla and ogonek needs the anchors of a designer or the
review.
One shared collection of OFL fonts serves every comparison and measurement:
the accent placement evaluation, proofs and checks. It is not a source of
outlines. Set FONTGARDEN_REFERENCE_FONTS to its directory, then run
fgtools fetch-reference-fonts. The command downloads the families of
fgtools/reference_fonts.toml from https://github.com/google/fonts. That
file is the trusted list: each family has the reason that it is a reference,
and the designer decides which families it holds. Each family goes into <directory>/<family>/ with its
OFL.txt. A family with variable fonts gets those. Another family gets its
Regular, Italic, Bold and Bold Italic. A family that is present is not
downloaded again, and --family NAME adds a family of google/fonts/ofl.
Each project names its own reference families in CONTEXT.md:
[reference_fonts.families]
heebo = "A Hebrew extension of Roboto: a plain sans for text."A key is a directory name of https://github.com/google/fonts under ofl/,
so the upstream of a family is
https://github.com/google/fonts/tree/main/ofl/<name>. The value is the
reason that the family is a reference. fgtools fetch-reference-fonts --project (make reference-fonts) copies the upright fonts and the
OFL.txt of each family into reference-fonts/<name>/ of the project. Git
ignores that folder. proof-web and Runebender read it. A family comes from
the first place that has it: the shared collection, a local clone of
google/fonts that FONTGARDEN_GOOGLE_FONTS names, or a download from GitHub.
The command lists the folders that CONTEXT.md does not name, and does not
remove them.
fgtools media renders the pictures, the carousels and the videos of a font
for Instagram, TikTok, LinkedIn, X and Mastodon, and fgtools media --specimen writes the print specimen. fgtools media --proof writes the
print proof, for the designer: the character set, the sizes, reading text,
spacing, kerning, diacritics, the weight axis, the short lines of
sources/proof-samples.toml and the tables of the Arabic script. Its pages
are the scripts of fgtools/media_formats/proofs/, the same for every font.
The command needs designbot, and ffmpeg for video.
A name after the command selects a part: a format, a kind of format
(images, carousels or videos), or with --proof or --specimen a
page. --canvas selects one canvas, and --list lists every name.
Every picture is laid out on the lattice of the typeface. The numbers are in
the [layout] block of CONTEXT.md of the project, and the defaults are the
same:
| Rule | Default |
|---|---|
| The module: the large step of the design grid | 64 pixels |
| The unit: every position is a multiple of it | 8 pixels |
| The type sizes, which double | 32, 64, 128, 256, 512, 1024, and 24 for labels |
The live area of a canvas is a whole number of modules, and the margin is the rest. The text area is the live area less one module on each side, inside the safe area of the platform. The cap top of a line stands on a module line. A text is chosen to fit its measure: the size never changes to make a text fit.
| Part | File | Work |
|---|---|---|
| Lattice, typesetter, checker | fgtools/media_layout.py |
Gives a canvas its areas, measures text with HarfBuzz, fits a word to a measure, breaks a paragraph, and checks each element |
| Formats | fgtools/media_formats/ |
One Python file for each format. A format places type, rules and paths on the lattice. |
| Canvases | fgtools/media_canvases.toml |
The sizes and the safe areas of the platforms, and the print page |
| Words | fgtools/media_words.toml |
The supply of words for the large settings, for Latin, Arabic and Hebrew |
| Plotter | fgtools/media_plotter.rs |
DesignBot draws the checked layout from a plot file |
A layout with a fault is not written: a size that is not on the scale, a
position off the unit, ink outside the text area, or more than three sizes or
two weights in a picture. --lattice draws the lattice and the text area on
each picture.
Every project gets the default formats: words, weights, text,
scripts, release, link-card, glyph, characters and weight-axis. A
project changes the media for its font in documentation/media/:
| File | Content |
|---|---|
brand.toml |
The colors and the texts of the font. A new font needs only this file. |
formats.toml |
Optional. A table with the name of a format gives it other canvases, a caption and an alternative text. A table with a new name is a format of this font. |
images/<format>.py, carousels/<format>.py, videos/<format>.py |
Optional. A script with the name of a default format replaces it; fgtools media --copy <format> copies the default script to start from. The folder says what the format makes. |
A script defines draw(sheet, job). The sheet has the lattice (sheet.cols,
sheet.rows, sheet.text, sheet.label, sheet.header, sheet.rule), and
the job has the font (job.type), the brand and the texts. A script returns a
sentence when it cannot draw, for example for a font with one weight.
A font at the start of its design has few glyphs, and the formats use what it has. A text with a character that the font does not have is left out, and a font that can set no word shows the letters that exist. A picture never shows a system font.
One output is one format on one canvas:
output/media/<folder>/<format>/<family>_<format>_<canvas>.<extension>, with a
JSON record of the caption, the alternative text, the size and the commit of
the sources. output/media/index.html shows every output. The print specimen
is output/specimen/<family>-specimen.pdf: the formats on A4 pages, at half
size, with dark ink on a light ground. Git ignores output/.
The last line of media, render, diff and proof-web is Open: and the
file or address to look at. Most terminals open it with a Command-click.
fgtools proof-web --current serves the current build beside the fonts in
reference-fonts/, at one em size and weight, on http://127.0.0.1:60272/.
The current build is the TTF with an fvar table in <fonts>/variable/, or
else the first TTF in the fonts directory. The page title is familyName
of config.yaml. The server reads reference-fonts/ again when its files
change. It does not read the UFO sources, so build again after an edit.
--check prepares and checks the files and does not start the server.
Generated files go to output/proof-web/.
The modes are Compare, Toggle (Before and Candidate in place, key B), Waterfall and Text. The samples are live browser text. The proof checks the SHA-256 hash of each font before it shows it. A reference font without a glyph shows the missing code points, not a fallback font. Browser rendering is not release QA.
For a Before and Candidate comparison, write a comparison file with the
paths and hashes of fixed font files, run proof-web prepare, then
proof-web --snapshot DIR. The command remembers the snapshot, and
proof-web without a mode serves it again. If a Before or Candidate font is
missing, stop. Do not use the current build in its place. The manifest
format is in the docstring of fgtools/proof_web/prepare.py.
The package has default samples for Latin, Hebrew and Arabic in
fgtools/proof_web/samples.toml. The proof uses a sample only when the
font has at least half of the basic letters of each script in its scripts.
sources/proof-samples.toml adds samples. A sample with the key of a
default sample replaces it. defaults = false removes all default samples.
defaults = true # false: use only the samples of this file
# A short sample for Compare, Toggle and Waterfall.
[sample.figures]
label = "Figures"
scripts = ["Latin"] # optional: Latin, Hebrew or Arabic
text = "0123456789"
lang = "en" # optional: else the language of the first script
# A text sample for the Text mode.
[text.hebrew-news]
label = "Hebrew news"
scripts = ["Hebrew"]
overview = false # true: each paragraph is a labeled section,
# and the sample is also in the other modes
[[text.hebrew-news.paragraphs]]
text = "..." # or `runs`, for mixed directions:
# runs = [{ text = "..." }, { text = "Latin", lang = "en", dir = "ltr" }]
# A paragraph can have `label`, `lang`, `dir` and `scripts`.The proof also adds the sample "Encoded repertoire": every printable character in the cmap of the font, by script.
The guide of the Font.Garden system is at https://font.garden/docs. Its
source is https://github.com/fontgarden/fontgarden.github.io
(src/content/docs/). When you change a command, a make target, a mark
color, the layout or a workflow in this package, update the chapter of the guide in the
same session. The README of that repository lists the chapter for each kind
of change, and its scripts/check_guide.py finds the differences.
python -m unittest discover -s testsThe tests build a small project with two masters in a temporary directory.
The proof-web tests also make small fonts with FontBuilder. The test of the
JavaScript face selection needs Node.js and is skipped without it.
To run the project tests on a real project too, set FONTGARDEN_TEST_PROJECT
to its root.
Apache License 2.0. See LICENSE.