Lunaya

Making a theme

A theme is one small JSON file: a palette, a paper texture, corner radii, and optionally a different arrangement of the blocks on the day sheet. Take one from the gallery, change what you want, and import it back.

Start from a file that already works

1. Download any theme from the gallery — the .json source sits beside the .lunayatheme package.
2. Change id to something of your own. An id that matches a built-in theme is silently ignored by the app: no error, no new theme. The nine taken ids are do-tet · gach-bong · giay-cu · giay-do · giay-moi · muc-dem · nuoc-luc · son-mai · truc-xanh.
3. Change name and the colours. Keep basedOn — it inherits every field you don't write.
4. Rename the file to <your-id>.lunayatheme and import it: in Lunaya, Settings → Appearance → Import theme from file. Plain JSON works too; the app checks the first four bytes and reads either form.

Colours

Eleven tokens. Every colour in the app comes from one of them, so a theme never names a colour twice. Values are #RRGGBB.

The contrast gate

The app measures the WCAG contrast ratio between ink and paper. Below 4.5 it warns; below 3 it warns harder. It never refuses the file — a theme you can barely read is still your choice, and the warning tells you which pair is at fault.

Two tokens are easy to forget: inkFaint carries the small labels, and vermilion carries holiday names and Sundays. Both are real text — check them against paper too, not just ink.

Paper texture

Grain, staining and ink bleed are drawn by the app over the paper colour. Patterns are drawn in code, not images, so they follow your ink colour and stay sharp at any density. Five slugs:

hoi-van · song-nuoc · tram-cham · mat-vai · hoa-thi

Out of range means clamped, not rejected

Write 5.0 where the range stops at 1.4 and the app uses 1.4 — it does not throw the file away. That is deliberate: a number nudged out of range should not cost you the whole theme. Ranges read from the spec:

Light and dark

Set isDark to say which one your palette is. A light theme may also carry darkVariant — the same token names, different values — and the app swaps to it when the palette needs a dark counterpart. Omit it and the theme simply stays as written.

Rearranging the day sheet

The Today screen is not a fixed layout — the app draws it from a tree your theme can describe. You place components into named slots; you do not set coordinates. Free coordinates break on every screen size other than yours, and a broken layout cannot be clamped back the way a colour can.

What a component does when tapped is decided by the app, by component type — a theme cannot change it. Fonts: be-vietnam-pro · playfair-display · bitter

Package layout and limits

A .lunayatheme file is a zip with theme.json at the root and, if you have images, an assets/ folder beside it. Entry names must match the pattern below exactly — it is an allow-list, not a block-list.

ten-giao-dien.lunayatheme
├── theme.json
└── assets/
    └── hoa-van.png

When something is wrong

Errors have stable codes, so the app and the web editor can disagree in wording but never in meaning. ERR_ refuses the file; WARN_ accepts it and tells you.

Every number on this page is read from the app's own spec when the page is built, so it cannot drift out of date.