How it works
- Download the starter themeA .zip with
theme.jsonandtheme.css, already passing every check. Unzip it, rename itsidandname. - Write your CSSStyle the page’s parts and set its tokens. Write rules for the page as it is; you never change its markup.
- Zip it againZip the files, or the folder that holds them. Pictures and fonts sit beside
theme.css, listed intheme.json. - The shop adds itThe owner adds the .zip in the console: Stores, the store, Pick-up ordering, Your themes, then picks it for the Mini App, the QR code page or both.
A theme is only CSS. The menu, prices, the basket and paying are the page’s own, so a theme cannot break an order.
The package
One .zip, at most 5 MB. theme.json and theme.css at the top, or in one folder at the top. Every other file is listed in theme.json files.
- Pictures: png, jpg or webp. Fonts: woff2. No SVG, since it can hold script.
- Plain lowercase file names, no folders inside:
bg.webp,stall.woff2. - Up to 30 files, 1 MB each.
theme.cssup to 150 KB,theme.jsonup to 16 KB. - What your computer adds by itself (
__MACOSX,.DS_Store) is left out. Any other file not listed is refused.
theme.json
Who made the theme, which modes it is for, its files, and the settings an owner can change without touching your CSS.
{
"contract": 1,
"id": "night-market",
"name": "Night Market",
"version": "1.0.0",
"author": { "name": "Sok Dara", "url": "https://example.com" },
"description": "Kraft paper by day, dark roast by night.",
"modes": ["light", "dark"],
"files": ["bg.webp", "stall.woff2"],
"settings": [
{ "type": "color", "id": "stall", "label": "Stall color", "light": "#B4532A", "dark": "#E08A5F" },
{ "type": "switch", "id": "paper", "label": "Paper texture", "on": true }
]
}contract | The contract the theme is written for. Today: 1. |
id | 2 to 40 lowercase letters, digits and hyphens. The same id again replaces the theme at that shop: a new version. |
name | What the owner sees in the console, up to 40 letters. |
version | Three numbers, like 1.0.0. |
author | name, and a url if you like. |
description | A line about it, up to 280 letters. |
modes | light, dark or both. A theme for one mode is always shown in it, and the page hides its mode switch. |
files | Every picture and font the CSS links to. |
settings | Up to 12. A color with a light and a dark value, read as var(--setting-<id>); a switch that sets html[data-setting-<id>] when on. |
What the page gives a theme
The page is the same markup for every look and every theme. These are set on <html>:
data-theme-pkg | Your theme’s id. The checker scopes every rule of yours to it. |
data-theme | light or dark: the customer’s choice, the phone’s, or Telegram’s. |
data-tg | The page is inside Telegram. --tg-top is the room Telegram’s buttons take. |
data-scrolled | The menu has scrolled under the header. |
lang | en, fr, km or zh. Khmer and Chinese need a face that has their letters: keep var(--sans) or var(--km) for them. |
Tokens
Yours to set, on :root or html, and for [data-theme="dark"]:
--bg--bg-deep--panel--line--line-soft--ink--ink-soft--muted--look-backdrop--look-hero--look-hero-r--look-r--look-r-sm--look-bw--look-shadow--look-shadow-color--look-tile--look-img--look-head--look-blur--look-chip-r--look-badge-r
Yours to read, never to set: the locked colors and the shop’s own accent, made readable for each mode.
--primary--danger--ok--warn--info--acc-*--tg-*--acc-solid--acc-ink--acc-tint--acc-line
:root {
--bg: #FBF7F1;
--panel: #FFFFFF;
--look-r: 18px;
}
html[data-theme="dark"] {
--bg: #16130F;
--panel: #221D17;
}
.to-section h2 {
color: var(--setting-stall);
border-bottom: 2px solid var(--acc-line);
}
html[data-setting-paper] .to {
background: url('bg.webp');
}Use --acc-solid, --acc-ink, --acc-tint and --acc-line for the shop’s brand color. Every shop wearing your theme keeps its own.
Parts and states
The classes a theme styles, by area. You may style any element inside them; these are the names that stay.
| Area | Classes |
|---|---|
| Page | .to.to-menu.po-nobar.po-bar |
| Header | .to-head.to-logo.to-lang.look-mode.lang-menu.lang-menu-panel.lang-menu-name.lang-menu-chev.po-hours.po-hours-head.po-deals.po-member |
| Sections | .po-catbar.to-cats.po-layout.to-section.to-grid |
| A dish, list | .po-dish.po-dish-open.to-dish-img.to-dish-text.to-dish-desc.po-initial.po-deal-mark |
| A dish, grid | .po-card.po-card-open.to-card-img.to-card-text.po-card-foot |
| Buttons and prices | .po-add.to-stepper.to-price.to-icon-btn |
| Ordering | .to-bar.to-sheet.to-sheet-head.to-field.to-opt.to-group.to-lines.to-sum |
States
.in is a dish in the basket; .reveal then .seen a dish or title before and after it scrolls in (below the first screen only, never under Reduce Motion); .no-photo a dish without a picture; .on the section chip in view; aria-pressed on the list and grid switch.
What is checked
Every package is checked when it is added, and a refusal lists every problem with its line, so it can be fixed in one go.
| Refused | Why |
|---|---|
| Backslash escapes | They can spell anything, url( included. |
@import and every at-rule but @media, @supports, @container, @keyframes, @font-face | Nothing loads from outside; nothing reorders the page’s rules. |
url() to anything but the package’s own files | A link out could tell another site who opened the page. |
!important | The locked rules use it, so nothing of a theme outranks them. |
| Setting a locked token | The order button, statuses and errors keep their colors; the accent stays the shop’s. |
Text in content | A theme may not write on the page, such as a fake price. "", none and counters are fine. |
expression(, javascript:, -moz-binding, behavior | They run or fetch something. |
| Nested rules, CSS that does not parse, over 150 KB | Each rule is scoped as written. |
What passes is scoped to html[data-theme-pkg="<id>"], its @keyframes renamed to the theme’s own, and its url() pointed at where the file is served.
What never changes
After your CSS, the page adds rules no theme can outrank, so every shop stays safe to order from:
- The main order button keeps its color and stays a full, readable button.
- Errors and refusals keep their red.
- Prices are always there to read.
- Keyboard focus is always visible.
- Under Reduce Motion, nothing moves.
Try it on a shop
Adding a theme is on Growth and Pro. Add the .zip under Your themes, then pick it for the Mini App or for the QR code page. Open the page from the console to see it in light and dark, in the list and the grid, and in Khmer and Chinese.
- Adding the same
idagain replaces it, and the stores wearing it keep it: that is how you ship a new version. - Removing a theme puts each store back on its page look.
- Your CSS is cached by its version, so each new upload is a new address and customers never see half of one.
Contract versions
The classes, states and tokens on this page are contract 1. We add to it without renaming. If a change ever has to break it, that is contract 2, and the page keeps serving each theme the contract it names until it is updated.