Position and size
Widgets have to look right on a 13-inch laptop, a 27-inch 5K display and everything in between. So Atsurae never uses pixels or points. Every size and distance in widget.json is a fraction of the screen height.
The unit: screen height
Section titled “The unit: screen height”A size of 0.1 means one tenth of the screen’s height.
| Value | On a 1080-point-tall screen | Feels like |
|---|---|---|
0.01 |
~11 points | fine print |
0.016 |
~17 points | a caption, the built-in Date |
0.03 |
~32 points | a heading |
0.05 |
~54 points | the built-in Day |
0.16 |
~173 points | a huge clock |
The same unit is used for:
font.size: the text’s size (roughly the height of a capital letter plus a bit)size: [width, height]of images, shapes and progress barsoffset: [x, y]cornerRadius,strokeWidthandlineWidth
Width uses the screen height too, so [0.1, 0.1] is always a square, even on an ultrawide display.
Where the widget goes
Section titled “Where the widget goes”You don’t choose where your widget sits on the screen; the person using it does. In Customize Widgets they drag it to a spot, and Atsurae stores that spot as an anchor point: a position given as fractions of the screen’s width and height, so it stays in the same place if the resolution changes.
Each placement also has:
- Size: a multiplier from 0.25× to 3× applied to every size and offset in your widget, so the whole widget scales together
- Color: replaces the color of text and progress bars, and the tint of tinted images (Color)
- Option values: whatever your options let people choose
A new widget starts at the center of the screen.
Where elements go
Section titled “Where elements go”Every element is positioned relative to the widget’s anchor point:
offset [-0.1, -0.05] ● anchor ✛ (where the widget was placed) ● offset [0.1, 0.05]offset: [x, y]moves the element from the anchor. Positive x is right, positive y is down. Leave it out for[0, 0].- Vertically, an element is always centered on its offset point.
- Horizontally,
alignmentdecides which part of the element sits on the offset point:"center"(default): the element’s middle"leading": its left edge"trailing": its right edge
So a two-column layout puts labels on the left with "alignment": "leading" and values on the right with "alignment": "trailing":
{ "text": "LONDON", "alignment": "leading", "offset": [-0.13, 0] },{ "text": "20:18", "alignment": "trailing", "offset": [ 0.13, 0] }Both columns line up neatly however long the text is. The World Clock example works this way.
Design around the anchor
Section titled “Design around the anchor”Because people place widgets by dragging the anchor, put the anchor somewhere that makes sense:
- A single line or block: center everything on the anchor (all offsets near
[0, 0]). Snapping to the screen’s center then centers your widget. - A stack: put the most important element on the anchor and stack others above and below it.
- A card: put the card’s background shape at
[0, 0]and lay the contents out inside it.
Drawing order
Section titled “Drawing order”Elements are drawn in the order they’re listed. Later elements are drawn on top. Put background shapes first.
Multiple displays
Section titled “Multiple displays”Widgets appear on the main display (the one with the menu bar in System Settings ▸ Displays). Positions are fractions of that display, so they survive resolution changes and switching between the built-in screen and an external one.
