Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

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.

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" } }

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.

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.

Put .ttf or .otf files in a fonts folder inside your widget’s package:

Retro Clock.atsuraewidget/
├── widget.json
└── fonts/
└── VT323-Regular.ttf

and 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.

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.

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.