Comment ça marche
- Télécharger le thème de départUn .zip avec
theme.jsonettheme.css, déjà conforme à chaque vérification. Décompressez-le, puis changez sonidet sonname. - Écrire votre CSSStylez les éléments de la page et définissez ses tokens. Écrivez des règles pour la page telle qu’elle est ; vous ne modifiez jamais son balisage.
- RecompresserZippez les fichiers, ou le dossier qui les contient. Les images et polices sont à côté de
theme.css, listées danstheme.json. - La boutique l’ajouteLe propriétaire ajoute le .zip dans la console : Magasins, le magasin, Commande à retirer, Vos thèmes, puis le choisit pour la Mini App, la page du QR code ou les deux.
Un thème n’est que du CSS. Le menu, les prix, le panier et le paiement appartiennent à la page, donc un thème ne peut pas casser une commande.
Le paquet
Un seul .zip, de 5 Mo au plus. theme.json et theme.css à la racine, ou dans un seul dossier à la racine. Chaque autre fichier est listé dans theme.json files.
- Images : png, jpg ou webp. Polices : woff2. Pas de SVG, car il peut contenir du script.
- Noms de fichiers en minuscules, sans dossiers à l’intérieur :
bg.webp,stall.woff2. - Jusqu’à 30 fichiers, 1 Mo chacun.
theme.cssjusqu’à 150 Ko,theme.jsonjusqu’à 16 Ko. - Les fichiers que votre ordinateur ajoute seul (
__MACOSX,.DS_Store) sont ignorés. Tout autre fichier non listé est refusé.
theme.json
Qui a fait le thème, pour quels modes, ses fichiers, et les réglages que le propriétaire peut changer sans toucher à votre 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 | Le contrat pour lequel le thème est écrit. Aujourd’hui : 1. |
id | 2 à 40 lettres minuscules, chiffres et tirets. Le même id à nouveau remplace le thème dans cette boutique : une nouvelle version. |
name | Ce que le propriétaire voit dans la console, jusqu’à 40 lettres. |
version | Trois nombres, comme 1.0.0. |
author | name, et un url si vous le souhaitez. |
description | Une ligne à son sujet, jusqu’à 280 lettres. |
modes | light, dark ou les deux. Un thème pour un seul mode s’affiche toujours dans celui-ci, et la page masque son choix de mode. |
files | Chaque image et police que le CSS utilise. |
settings | Jusqu’à 12. Une color avec une valeur light et une valeur dark, lue comme var(--setting-<id>) ; un switch qui définit html[data-setting-<id>] quand il est activé. |
Ce que la page donne à un thème
La page a le même balisage pour chaque apparence et chaque thème. Ces attributs sont posés sur <html> :
data-theme-pkg | L’id de votre thème. La vérification limite chacune de vos règles à lui. |
data-theme | light ou dark : le choix du client, celui du téléphone, ou celui de Telegram. |
data-tg | La page est dans Telegram. --tg-top est l’espace que prennent les boutons de Telegram. |
data-scrolled | Le menu a défilé sous l’en-tête. |
lang | en, fr, km ou zh. Le khmer et le chinois ont besoin d’une police qui contient leurs lettres : gardez var(--sans) ou var(--km) pour eux. |
Tokens
À vous de les définir, sur :root ou html, et pour [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
À vous de les lire, jamais de les définir : les couleurs verrouillées et l’accent propre à la boutique, rendus lisibles pour chaque 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');
}Utilisez --acc-solid, --acc-ink, --acc-tint et --acc-line pour la couleur de marque de la boutique. Chaque boutique qui porte votre thème garde la sienne.
Éléments et états
Les classes qu’un thème stylise, par zone. Vous pouvez styliser tout élément à l’intérieur ; voici les noms qui restent.
| Zone | Classes |
|---|---|
| Page | .to.to-menu.po-nobar.po-bar |
| En-tête | .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 |
| Un plat, liste | .po-dish.po-dish-open.to-dish-img.to-dish-text.to-dish-desc.po-initial.po-deal-mark |
| Un plat, grille | .po-card.po-card-open.to-card-img.to-card-text.po-card-foot |
| Boutons et prix | .po-add.to-stepper.to-price.to-icon-btn |
| Commande | .to-bar.to-sheet.to-sheet-head.to-field.to-opt.to-group.to-lines.to-sum |
États
.in est un plat dans le panier ; .reveal puis .seen un plat ou un titre avant et après son défilement (seulement sous le premier écran, jamais avec la réduction des animations) ; .no-photo un plat sans image ; .on la pastille de section visible ; aria-pressed sur le bouton de bascule liste et grille.
Ce qui est vérifié
Chaque paquet est vérifié à l’ajout, et un refus liste chaque problème avec sa ligne, pour tout corriger d’un coup.
| Refusé | Pourquoi |
|---|---|
| Échappements par antislash | Ils peuvent écrire n’importe quoi, url( compris. |
@import et toute règle at- sauf @media, @supports, @container, @keyframes, @font-face | Rien ne se charge depuis l’extérieur ; rien ne réordonne les règles de la page. |
url() vers autre chose que les fichiers du paquet | Un lien vers l’extérieur pourrait dire à un autre site qui a ouvert la page. |
!important | Les règles verrouillées l’utilisent, donc rien d’un thème ne passe au-dessus d’elles. |
| Définir un token verrouillé | Le bouton de commande, les statuts et les erreurs gardent leurs couleurs ; l’accent reste celui de la boutique. |
Du texte dans content | Un thème ne peut pas écrire sur la page, par exemple un faux prix. "", none et les compteurs sont permis. |
expression(, javascript:, -moz-binding, behavior | Ils exécutent ou vont chercher quelque chose. |
| Règles imbriquées, CSS qui ne s’analyse pas, plus de 150 Ko | Chaque règle doit pouvoir être restreinte à votre thème. |
Ce qui passe est restreint à html[data-theme-pkg="<id>"], ses @keyframes sont renommés avec le nom du thème, et son url() pointe vers l’endroit où le fichier est servi.
Ce qui ne change jamais
Après votre CSS, la page ajoute des règles qu’aucun thème ne peut dépasser, pour que chaque boutique reste sûre pour commander :
- Le bouton principal de commande garde sa couleur et reste un bouton plein et lisible.
- Les erreurs et les refus gardent leur rouge.
- Les prix sont toujours là, à lire.
- Le focus du clavier est toujours visible.
- Avec la réduction des animations, rien ne bouge.
Essayer sur une boutique
Ajouter un thème est inclus avec Growth et Pro. Ajoutez le .zip sous Vos thèmes, puis choisissez-le pour la Mini App ou pour la page du QR code. Ouvrez la page depuis la console pour la voir en clair et en sombre, en liste et en grille, et en khmer et en chinois.
- Ajouter le même
idà nouveau le remplace, et les boutiques qui le portent le gardent : c’est ainsi que vous publiez une nouvelle version. - Retirer un thème remet chaque boutique sur son apparence de page.
- Votre CSS est mis en cache selon sa version : chaque nouvel envoi a une nouvelle adresse, et les clients ne voient jamais une moitié de fichier.
Versions du contrat
Les classes, états et tokens de cette page sont le contrat 1. Nous les complétons sans rien renommer. Si un changement doit un jour le casser, ce sera le contrat 2, et la page continue de servir à chaque thème le contrat qu’il indique, jusqu’à sa mise à jour.