Fonts
Every text element can set a font:
"font": { "family": "Michroma", "size": 0.05, "weight": "regular" }| Field | Required | Meaning |
|---|---|---|
size |
yes | Text size as a fraction of the screen height (0.02 is small, 0.16 is huge). See Position and size. |
family |
no | The font family’s name. Leave it out for the system font. |
weight |
no | ultraLight, thin, light, regular (default), medium, semibold, bold, heavy or black |
Without a font, text uses the system font at size 0.02.
The system font
Section titled “The system font”Leaving out family gives you SF Pro, the font macOS itself uses. It has every weight from ultraLight to black and looks crisp at any size. It’s a good default:
{ "text": "{hour}:{minute}", "font": { "size": 0.16, "weight": "ultraLight" } }Michroma
Section titled “Michroma”Atsurae comes with Michroma, the wide, geometric font the built-in widgets use. It’s available to every widget:
{ "text": "{weekday|upper}", "font": { "family": "Michroma", "size": 0.05 }, "tracking": 0.42 }Michroma has one weight (regular) and looks best in UPPERCASE with wide letter spacing. It’s licensed under the SIL Open Font License.
Installed fonts
Section titled “Installed fonts”Any font installed on the Mac works by its family name, as shown in the Font Book app: "Avenir Next", "Helvetica Neue", "Menlo", "New York", "SF Mono", "Georgia" and so on.
"font": { "family": "Avenir Next", "size": 0.03, "weight": "medium" }If a font isn’t found, Atsurae uses the system font and shows a warning in Problems & Console:
Font “Fancy Sans” isn’t installed or in the widget’s fonts folder; the system font is used instead.
Bringing your own font
Section titled “Bringing your own font”Put .ttf or .otf files in a fonts folder inside your widget’s package:
Retro Clock.atsuraewidget/├── widget.json└── fonts/ └── VT323-Regular.ttfand use the font’s family name (not the file name):
"font": { "family": "VT323", "size": 0.08 }To find a font’s family name, open the file in Font Book; the name in the window’s title is the family. Fonts in a widget’s fonts folder are available only inside Atsurae; they aren’t installed on the Mac.
Weights
Section titled “Weights”weight picks the closest weight the family has. A family with only Regular and Bold shows semibold as Bold and light as Regular. Some families name their weights differently (Book, Demi, Heavy); weight still maps to the nearest one.
Letter spacing
Section titled “Letter spacing”tracking adds space between letters, in ems (fractions of the font size):
tracking |
Look |
|---|---|
-0.02 |
slightly tighter, good for huge numbers |
0 |
normal (default) |
0.1–0.2 |
airy, good for small caps labels |
0.4 |
very wide, like the built-in Day |
Spacing is added between letters only, so wide-spaced text stays centered.
