Font.Garden
← Guide index

must→Source repository structure

Every source repository in the collection has one layout. The layout lets the build, the checks and the corpus builder find the sources without configuration for each repository. New repositories start from the project template. The reference project is Virtua Grotesk.

Background reading:
learn Hosting sources on GitHub
templ Start a font project

The layout

├── AGENTS.md
├── AUTHORS.txt
├── CONTRIBUTORS.txt
├── OFL.txt
├── README.md
├── CONTEXT.md
├── STATUS.md
├── WORKLOG.md
├── Makefile
├── requirements.in
├── requirements.txt
├── .agents
│   └── tasks
├── documentation
│   └── google-fonts.md
├── fonts
│   ├── ttf
│   └── variable
├── sources
│   ├── Style.designspace
│   ├── Style-Regular.ufo
│   ├── Style-Bold.ufo
│   ├── config.yaml
│   ├── held-out-glyphs.toml
│   └── specimen

The layout follows the Google Fonts project template, with the Font.Garden files added. The tools are not in the repository. They are in fgtools. A Python file in sources/ holds only what one font needs.

sources

pathcontent
Style-Master.ufoOne UFO for each master.
Style.designspaceThe masters, the axes and the named instances. A project with one master has no designspace.
config.yamlThe recipe of the gftools builder. A project is a directory that contains this file.
held-out-glyphs.tomlThe cases of the drafting evaluation.
proof-samples.tomlOptional. Text samples for the web proof and for the proof view and the Proof section of Runebender.
specimen/Optional. The specimen image and labels.json, for a font traced from a specimen.

Only drawn <source> masters are training data. Instances are not. Generated files go to output/, which Git ignores.

Files that people edit use TOML with comments. JSON is only for data that a program writes. config.yaml is YAML because gftools requires it.

CONTEXT.md

CONTEXT.md is the one design file of a project. It starts with a description of the font, a table of contents and the chapter “The idea”, which gives the purpose and the precedents of the design in prose. Text about the design in a README, a specimen or an article comes from there. The chapters after that hold the numbered design rules of the style. Below a rule, a toml code block holds the values that the tools check for that rule:

R1. Every point is on the 2-unit grid. Structural points are on the 8-unit grid.

```toml
[grid]
source = 2
machine_draft = 8
```
  • Agents and people read the whole file. Runebender gives it to its agents.
  • fgtools reads only the toml blocks, as one TOML document: the grid, the stroke targets, the weights, the mark colors, the reference fonts, the QA exclusions and the start date of the corrections list.
  • A design value is stated only in this file.

documentation

documentation/google-fonts.md is the one document of the release: the project facts, the QA, the package and, for a traced font, the origin of the specimen. The folder also holds the Google Fonts article. A project has no other documents: the design is in CONTEXT.md, and the way of work is in AGENTS.md.

Agent files

AGENTS.md gives the rules for coding agents, as short bullets. WORKLOG.md is their shared record of work. .agents/tasks/ holds task contracts for long and unattended tasks. Each contract gives a goal, acceptance checks, constraints and the form of the report.

What does not belong

The repository holds sources, tests and maintained documents. It does not hold records of work.

  • No handoffs, receipts, reports, plans, audits or dated documents. WORKLOG.md is the one record of work: short entries, newest first, that every agent reads when it starts and adds to when it stops.
  • A tracked file has at most 500 KB. A specimen scan in sources/specimen/ can be larger.

fgtools check-repository enforces these rules, and make test runs it in CI. Each tracked file must have a place in the layout, which is the same for every Font.Garden project and is in fgtools. The command also fails when a document names a file or a make target that does not exist. When a document has a chapter ## Contents, the command fails when that chapter and the ## chapters of the document differ. A Python file in sources/ is optional: it holds only what one font needs, for example its own Fontspector checks.

Top-level files

  • README.md states what the style is and gives the commands.
  • STATUS.md is generated by make status from the mark colors.
  • OFL.txt, AUTHORS.txt, CONTRIBUTORS.txt: see Licenses.
  • Makefile is the entry point for every workflow. make help lists the targets. Each target calls fgtools.
  • requirements.txt pins every Python dependency, with fgtools pinned to a commit.
Next reading:
templ Licenses
must→ The dyadic grid